Where Software Takes Shape in the Age of Agents

From writing code to architecting intention in the age of generative AI

The code is not the system. For my entire career, we pretended it was. This was mainly because the code was all we could see, the only artifact we could touch. You had an intention. An engineer translated it into syntax. The code became the interface, the contract, the source of truth. Everything else—the design, the judgment, the specification—was scaffolding around the translation.

That era is not ending, exactly. Code still matters. But code is no longer the only place where software takes shape.

The Expansion Beyond Code

If you ask a junior engineer what a software system is, they’ll likely point to the repository. The code. And until recently, they wouldn’t be wrong. Code was where intention became concrete. Every decision about data structures, control flow, error handling, and performance lived in the code. To understand a system, you read the code. To build the system, you wrote the code. To change the system, you edited the code.

But something has shifted. The emergence of AI agents capable of acting on specifications, tests, and architectural constraints has revealed something profound: the code is not the system. The code is the artifact. The system is something broader, something that lives in layers above and around the code itself.

Consider what happens when you prompt a capable AI model with a clear specification. You don’t need to hand-translate the specification into code yourself. The model can do that translation. And when the model gets it right, when the generated code matches your intent perfectly, it’s a striking moment. The code doesn’t matter as much as the clarity and completeness of the intent you provided.

This is the real insight. When the act of coding can be partially or wholly automated, what becomes precious is not the syntactic translation but the semantic clarity. The intent layer.

Defining the Intent Layer

The intent layer is the collection of artifacts that define what a system must do, without committing to how it is built. It is where clarity replaces guesswork and where meaning exists independently of implementation.

It includes specifications, which describe behavior, constraints, and edge cases with precision. It includes tests, which make those expectations executable and verifiable. It includes architectural principles that shape how the system is allowed to evolve, along with constraints such as performance limits and security requirements that bound what is acceptable.

It also includes design documents that capture reasoning, trade-offs, and rejected alternatives, preserving the thinking behind decisions. And it includes concrete examples and real-world scenarios that anchor abstract intent in lived use.

Taken together, these artifacts form a complete expression of intent—one that can be understood, validated, and acted upon without relying on any particular codebase.

These elements aren’t new. Good engineers have always written specifications, tests, and design documents. But they lived in a supporting role, in comments and docstrings and PRs and wikis. They were the description of what the code did. The code itself was the source of truth.

The shift is that the intent layer is becoming the primary artifact. The code is becoming the derived artifact—generated, maintained, and validated by tools that understand intent.

Why This Matters

The quality of software has always depended on the clarity of intention. A vague specification leads to misunderstood requirements, which lead to wasted time in rework. A missing test case hides a lurking bug that surfaces in production. A poorly documented architecture decision leads to future developers making contradictory choices.

But when engineers were the ones translating intent into code, there was a natural quality gate. If the specification was unclear, the engineer would ask for clarification. If the test case was missing, the engineer would discover it in the implementation process. If the architectural principle was violated, the engineer would notice it during code review.

With AI agents doing the translation, that gate shifts. The agent will implement the spec as written, gaps and all. The agent will generate code that follows the specification but violates architectural principles if those principles aren’t explicit in the spec.

This is not a weakness of AI agents. It’s a feature. It forces intention to be made explicit. It makes the fuzzy, implicit knowledge that good engineers carry in their heads become concrete, shareable, and verifiable. It scales that knowledge.

An AI agent trained on incomplete specifications will generate incomplete software. But an AI agent trained on complete, precise, well-tested specifications will generate reliable software at scale. The quality of software in an agent-driven world is almost entirely determined by the quality of the intent layer.

The Three Dimensions of Intent

A complete intent layer has three dimensions:

The declarative dimension describes what the system does: the features, the behaviors, the outcomes. This is the specification. This is the user-facing contract.

The imperative dimension describes how the system should achieve those outcomes: the architecture, the algorithms, the structural constraints. This is where you embed your expertise about what makes software maintainable, scalable, and resilient. This is how you prevent agents from reinventing problems you’ve already solved.

The evaluative dimension describes how you measure whether the system has achieved its intent: the tests, the success criteria, the health metrics. This is how you validate that intent has been correctly translated into implementation.

Many teams focus primarily on the declarative dimension. They write user stories and feature specs, and they leave the imperative and evaluative dimensions implicit. In a world where code is handwritten, this is manageable. The engineer’s experience fills in the gaps. In a world where code is generated, it’s a source of brittleness.

The teams that will thrive in this new era are the ones that make all three dimensions explicit. They write specifications so precise that a machine can implement them. They codify their architectural wisdom so clearly that a machine won’t violate it. They write tests so comprehensively that correctness is verifiable without human code review.

The Inversion of Control

Here’s what’s truly revolutionary: the inversion of control. For seventy years, the engineer owned the intent. The engineer decided what the system should do, how it should do it, and whether it was done correctly. The code was the engineer’s primary expression.

In the age of agents, the intent owner still decides, but they now own the specification of intent, not the code. The engineer becomes the architect of the intent layer rather than the author of the artifact. The engineer’s time goes not to syntax and logic translation, but to precision, completeness, and the encoding of expertise.

This is more intellectually demanding, not less. It’s easier to write a function that works than to specify in unambiguous terms what that function should do and why it should do it that way. It’s easier to debug a failing test case than to write a test that comprehensively covers all the edge cases you haven’t yet discovered. It’s easier to make an ad-hoc architectural decision than to codify architectural principles that will guide every decision downstream.

But it’s also more powerful. An engineer who masters the intent layer can multiply their impact. Instead of translating specifications into one hand-written codebase, they can provide specifications to many agents, each generating implementations in different languages, for different platforms, at different scales. The engineer’s intention scales. The engineer’s expertise scales. The code becomes disposable, but the intent becomes precious.

The Foundation of the Next Era

We are at the threshold of a fundamental reorganization of software engineering. The act that defined the discipline—the translation of human intention into executable code—is no longer the bottleneck. The bottleneck is now the clarity, completeness, and precision of the intention itself.

This isn’t a threat to engineering. It’s a liberation. It means we can stop pretending that code is the thing that matters, and start acknowledging what we’ve always known: the thing that matters is the intention. The insight. The design. The specification. The constraint. The principle. The test that catches the bug that would have cost a million dollars.

The intent layer is where software takes shape in the next era. Master it, and you master the future of engineering. Ignore it, and you’ll find your code generated by agents that don’t understand what it’s supposed to do.

The choice is ours. But the direction is clear.