Agent-generated code looks right. It reads well. It often works on the first try.

But “looks right” is not sufficient for production software. The question is not whether the code is readable or plausible. The question is whether it can be trusted.

Built for human mistakes

Code review worked because humans wrote code, and humans could review it. A senior engineer could glance at a diff and spot the bug—the off-by-one error, the missing null check, the race condition. Code review was archaeology. You were reading the bones of someone’s thinking, and your job was to catch what they’d missed or misunderstood.

This works because human error follows patterns. We forget boundary conditions. We misread specifications. We over-index on common cases and forget about the edge. A trained reviewer learns to smell these mistakes. They become reflex.

Clean code can be confidently wrong

When an agent generates code, you can’t read it the way you read human code. Agent code is often cleaner than human code. It doesn’t have the accidental architecture, the shortcuts born from deadline pressure, or the documentation gaps. But clean code can be confidently wrong. An agent can misunderstand a spec in ways that produce perfectly formatted, well-structured, plausible code that does the wrong thing with absolute consistency.

The problem: human code review was optimized for catching human mistakes. It wasn’t optimized for catching confident misunderstandings. When a human reads an agent diff, they’re still looking for the mistakes a human would make. But agents don’t make those mistakes. They make different ones.

This is not a weakness of code review. It’s a signal that code review, as a mechanism, has to change.

The trust boundary moves upstream

Here’s what changes: the trust boundary moves from the diff itself to the boundaries around it.

The diff stops being the evidence. When humans wrote code, the diff was the artifact that mattered. You reviewed it, you approved it, and you deployed. The diff was proof that someone had made a deliberate choice. With agent-generated code, the diff is just output. It’s what came out the back of a process. The real evidence lives upstream: in the specification, in the test suite, in the type system, in the runtime constraints that box in what the code can actually do.

Think of it this way. When you review human code, you’re verifying that a person understood the problem and made the right trade-offs. When you review agent code, you’re verifying that the spec was clear enough, the tests were comprehensive enough, and the types were tight enough to force the agent toward correctness.

Tests become the primary review mechanism

Not a mechanism. The primary one. With human code, tests are one signal among many. A reviewer might catch bugs that tests miss. But with agent code, tests are the only unambiguous proof that the code does what you want. An agent can’t reason about your unstated needs. It only knows what the spec says and what the tests verify. If your tests don’t cover a case, the agent will have no signal to write code that handles it. If your tests pass on generated code, that’s not lucky—that’s the contract being fulfilled.

This means test suites need to be different. They need to be exhaustive in a way that matters more. You can’t rely on a human coming in later and saying, “Oh, we should handle this case.” The human review step is downstream. It’s looking at whether the generated code violates the test suite or spec, not whether the human would have written it differently. This is a relief and a constraint in equal measure.

Types become guardrails

A strongly typed system doesn’t just prevent bugs. It prevents categories of bugs. When an agent generates code, a tight type system becomes a boundary that forces correctness in ways that human reviewers never had to. If you’ve typed your functions precisely—if you’ve made illegal states unrepresentable—then the agent can’t generate code that violates those invariants. It can be wrong, but not in those specific ways. You’ve narrowed the surface area of what “wrong” can mean.

This is why languages with weaker type systems will struggle with agent-generated code. Python can be wonderfully flexible in human hands. An experienced Python engineer can hold complex invariants in their head and write code that violates type hints when there’s a good reason. An agent has no head to hold anything in. It sees “any” and generates code that might crash at runtime because nothing caught the mistake earlier.

Runtime constraints become part of the contract

Error handling. Rate limiting. Circuit breakers. Timeouts. These aren’t just defensive programming anymore. They’re part of the contract. When a human writes code that calls an external API, they might add error handling because they’ve been burned before. An agent writes error handling because the spec says the operation can fail. But the distinction doesn’t matter. What matters is that runtime constraints—things that actually execute and enforce boundaries—become part of what you’re verifying when you look at generated code.

You’re not asking, “Did the developer think to handle this?” You’re asking, “Does the system enforce this?” Because if it doesn’t, the agent won’t either.

Review the spec, not just the code

This is the inversion. The human reviewer’s job shifts upstream. Instead of reviewing the diff, you’re reviewing the spec. Is it complete? Does it cover the cases that matter? Are the invariants stated clearly? Have you told the agent what failure looks like? This is harder work in some ways and easier in others. You’re not reading code. You’re reading requirements. But you’re reading them with new intensity because now they’re the thing that actually shapes the output.

The diff is still reviewed. But the review is compressed. You’re looking for obvious violations of the specification, not reading the code as if a human wrote it. Does it call functions that don’t exist? Does it assume behavior that contradicts the spec? Is there a category of error it silently ignores? These are fast questions to answer. They’re high-signal gates.

Trust the boundaries you built

The unsettling truth is this: trust is no longer about trusting the coder. It’s about trusting the boundaries you’ve built. If you’ve specified clearly, if your tests are complete, if your types are tight, if your runtime constraints are enforced—then agent-generated code is as trustworthy as the system that produced it. And that system is entirely under your control.

What feels like a loss of human judgment is actually a transfer of judgment upstream. You can’t rely on a reviewer to catch mistakes during code review because code review is too late. The reviewer can’t see what wasn’t specified. They can’t know what the agent should have assumed. The decisions that matter happen before the code is written: in the spec, in the test design, and in the type definitions you choose.

The diff is still worth reading

This is harder in some ways. It requires discipline. It means you can’t ship incomplete specs and count on human reviewers to fill in the gaps. But it’s also more honest. You’re no longer pretending that code review is the thing that ensures correctness. You’re admitting that correctness comes from specification, from testing, from constraint. Code review becomes what it always should have been: a check that the output matches the input, not the entire quality gate.

The diff is still worth reading. But reading it doesn’t create trust. Trust comes from knowing the system that made it. And that system is built from specs, tests, types, and constraints, the things that agents can actually learn from and be held accountable to.

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.

Software development is undergoing a phase change.

For decades, the primary interface between human intention and software behavior has been code. Engineers translated goals into implementation details by hand. Product managers wrote requirements. Designers created mockups. Engineers decomposed work, wrote code, tested it, reviewed it, deployed it, and operated it.

AI agents are beginning to disturb that model.

The important shift is not simply that agents can generate code. Code generation is only the visible symptom. The deeper change is that a new abstraction layer is emerging above the codebase: a layer where humans express intent, constraints, specifications, architectural principles, tests, workflows, policies, and desired outcomes, and agents translate those into working software.

That layer needs a name.

The Intent Layer will be a publication about this emerging discipline: how software gets built when human beings move from typing every line of code to designing, supervising, constraining, reviewing, and orchestrating intelligent systems that can act inside the development process.

This is not a newsletter about “AI coding tips.” It is about the new operating model for software engineering.