Practices

At the moment you ask an agent for something, you know what you meant. The problem arrives two weeks later, when you look at the code and cannot separate "the agent did something else" from "I asked for that". With nothing written beforehand there is no way to tell: your memory of the request has been contaminated by the result.

A spec fixes that by being prior and independent. It does not describe the implementation — that is the design — but the observable behaviour: what has to happen, with which inputs, and how it is checked. Written that way, anyone can verify the result without having been in the conversation. Including you, in two weeks.

There is a side effect worth more than the original one: if you cannot write down how you will check that it is right, you do not yet know what you are asking for. Half the tasks an agent "got wrong" were badly formed tasks, and specifying them makes that fail before a single token is spent.

The phased cycle — explore, propose, specify, design, tasks, apply, verify, archive — exists for a mechanical reason, not a ceremonial one: each phase needs different context and has a different definition of done. Collapsing them into one request is asking the same person to design, build and inspect at once. They will approve their own work.

Watch the other extreme, though. A three-page spec for a two-line change is not rigour, it is theatre. The ceremony has a fixed cost and it should only be paid when the change earns it.

The idea that outlives the tools

If you cannot write down how you will check that it is right, you do not yet know what you are asking for.

The reason is mechanical and has nothing to do with moral discipline. Ask for the tests after the code is written and the agent writes tests that pass. That is literally what you asked for, and it will do it well. The result is a green suite that proved nothing, because no test in it ever had the opportunity to fail.

Which is why the step people skip — seeing the test red — is not a formality. For behaviour that does not exist yet it is the entire mechanism: red is the proof that the test can detect the absence of the thing it tests. Green on the first run tells you the test runs, which is a different claim and a less useful one. The rule is narrower than the slogan, though. A characterisation test fencing behaviour that already ships is supposed to pass immediately — it is not proving a new behaviour, it is pinning down an old one.

With an agent there is also a failure mode of its own: it mocks the thing under test. If the test for the billing function mocks the billing function, it passes forever and covers nothing. That sounds like a joke until you see it in a pull request. The defence is reading what the test mocks, not counting how many tests there are.

And there is a second-order benefit that matters more in a team than the first: a test written beforehand is an executable specification. It cannot drift from the code — the day the two disagree, the build says so. It can still drift from what you actually wanted, which is why the spec and the record exist and the test does not replace them.

The idea that outlives the tools

For new behaviour, a test you have never watched fail is not a test: it is an opinion written in green.

Start with the real problem, which is not the quality of the review but its repetition. You review a change. Then comes the commit, the push, the pull request, the release. At each of those points somebody — or some agent — asks again: "has this been reviewed?" With no verifiable answer, the only honest move is to review it again. And reviewing again with an agent costs money and time, every time.

The receipt cuts that. Review happens once, against an immutable target: the exact tree, the exact paths, the exact modes. What remains is a receipt bound to that content. The later points do not review: they validate. And if the content changed by so much as a byte, the receipt does not apply — which is precisely what you want to happen.

It also settles the problem of review never ending. An agent asked to "review this" keeps producing one more thing to say for as long as you keep asking; with no declared limit, review stops when you get tired, which is not a criterion. Here the correction budget is fixed when review opens, scaled to the size of the change, and is not renegotiated afterwards. What shows up later is new work, not an extension.

The other half is proportionality. A documentation change does not deserve the same scrutiny as one touching permissions or payments. The risk of the change decides how much analysis runs: none for the trivial, one focused lens for the ordinary, the full sweep for the dangerous. Choosing that by hand, change after change, is exactly the kind of decision people stop making by week three.

One warning, because this pattern degrades fast: a receipt that cannot be invalidated is a rubber stamp. All of its value lies in being fragile to a change of content. If your process keeps it valid "because it is basically the same", you no longer have control — you have paperwork.

The idea that outlives the tools

A review without a receipt has to be repeated; a receipt that cannot be invalidated is not a review.

Code tells you what was decided. It does not tell you what else was on the table, why that was dropped, or what you agreed to pay in exchange. That part was never in the repository: it was in a conversation, in a Slack thread, or in the head of somebody who now works somewhere else.

With an agent the problem changes scale. A human colleague who does not understand a decision asks. The agent does not ask: it completes. It sees a service that does not use the project's ORM and "fixes" it; it sees two modules not sharing a helper and unifies them. Every one of those corrections is reasonable if you do not know what the record knew, and none of them gets flagged in review, because the diff looks fine.

What makes a record useful is not the decision you took — that one is in the code — but the list of the ones you did not. A record with no rejected alternatives is a long comment. With them it is the only thing that can close an argument without having it again, and the only format you can hand an agent so it does not reopen it.

The cost is low, and that is worth saying: fifteen lines written the day the argument ends. The trap is not the effort, it is writing it while you still know why. A week later you have already rewritten the memory around how it turned out.

And there is a convention that holds the whole practice up, and that people break immediately: an accepted record is not rewritten. While it is still proposed it can change; once accepted, you write a new one that supersedes it and the old one is marked superseded rather than removed. Edit it to say what is true today and you lose exactly what you came for — the thread between what was decided and what shipped.

The idea that outlives the tools

A decision nobody wrote down is not a decision: it is a coincidence somebody will undo.

The failure mode here is not code that does not work. It is code that works and was not what was needed. It compiles, the tests pass, review approves it, and three weeks later somebody from the business looks at the screen and says that is not a discount. Nobody caught it earlier because nothing was wrong: something was different.

Of everything in domain-driven design, two pieces carry almost all the weight once you are working with agents. The first is one rule: one word, one meaning, and the same word in the conversation, in the spec, in the code and in the tests. That sounds small until you see what happens without it. At every point where you have to translate, somebody translates; and when the translator is a model, it takes the translation from the average of the internet rather than from your business.

The second is accepting that the same word means different things in different places, and that this is fine. A "shipment" in billing is a line with a price; in logistics it is a box with a weight. The answer is not to pick one: it is to mark the border where the meaning changes and make it explicit. For an agent that border is also a reading limit — it says how far it has to understand in order to be right, which is the same question hexagonal asks from the other side.

Now the honest part, because domain-driven design has a reputation for being expensive and earned it. What I just described — the vocabulary and the borders — is cheap and pays from day one. The tactical patterns — aggregates, value objects, repositories, domain events — are expensive and most codebases do not need them. They are two different things that arrived in the same book.

And be careful asking an agent for them, because it knows them and applies them with enthusiasm. A pattern with a proper name is exactly what a model reproduces best: ask for domain-driven design over a six-column table and you get an aggregate, a repository and a factory to store a name and an email address. That is not a modelled domain, it is domain vocabulary painted onto a CRUD.

The idea that outlives the tools

The agent does not build what you meant: it builds what your words say.

An agent is correct in proportion to what it can see at once. If changing a business rule means understanding the ORM, the router and three shared helpers, the agent has to load all of it, and the moment it does not fit, it starts inventing. An isolated domain hands it a small, bounded surface. This is not elegance: it is a reduction in the amount of context required to not be wrong.

The other half is what things are called. A folder structure that screams what the business does — billing, bookings, shipping — gives the agent free context before it opens a single file. One that screams the framework makes it read ten files to infer the same thing. Names are the cheapest context there is, and the only kind that is not consumed.

Now the part almost nobody applies: the same architectural idea can be applied to your AI workflow. The model is an adapter. The harness — Claude Code, Cursor, whatever you use — is an adapter. Your domain is the specs, the memory, the standards and the tests. If your knowledge lives inside a tool, you do not have an architecture: you have a dependency.

That is exactly the test this site uses to mark each tool portable or not. Portability is not an abstract virtue: it is the port/adapter boundary applied to your own working environment. What sits inside survives a change of tool. What sits outside does not.

And the downside, because there is one: hexagonal applied badly — a port for everything, interfaces with a single implementation, four layers to read one record — hands the agent more surface, not less. An abstraction that separates nothing real is precisely the kind of pattern a model reproduces enthusiastically.

The idea that outlives the tools

If changing a business rule means touching the framework, the agent will touch the framework.