Make your coding agent show its work

A coding agent can ship a feature faster than anyone writes down what it changed or why. The code lands in git. The reasoning does not, and a week later nobody can reconstruct the decision from the diff alone.

That happened on one of our services last week. An agent shipped a feature, the diff was clean, the tests passed. Ask it why the booking flow charges the card synchronously instead of queuing the charge, and the honest answer is that nobody knows anymore. The reasoning lived in a chat session that scrolled out of reach about an hour after the branch merged.

When a person writes a service, the context has somewhere to go on its way out. It leaks into the pull request description, a design review, a thread someone can dig up later. When an agent writes the same service in twenty minutes, that context was never anyone's to begin with. It existed for the length of a prompt and then it was gone. What's left is a working change with no account of itself.

We're not arguing against any of this. Agents do most of the implementation work on ArchDocs now, and we're not going back. The problem worth solving is narrower than "should we use them." An agent produces code far faster than it produces any record of what the code is for, and it will tell you it's finished without giving you a way to check that claim. The speed is fine. The missing paper trail is the tax you pay for it.

Write it down, before and after

The fix is unglamorous: a record of the change, written in three parts that do different jobs at different times.

The spec is the decision and the thinking behind it. What's changing, which risks you accepted, which alternatives you turned down. It's written before the work starts. The plan is the approach, plus the specific services and documents the change expects to touch, also written up front. The evidence is what actually happened, written after: the pull requests, where the work drifted from the plan, and the things you decided not to do after all.

None of this needs AI to exist. A person can write every part by hand. But the agent is worth putting to work here, because it holds the full context at the one moment it still has it, while it's doing the work, and it can write the spec and the plan as it goes instead of leaving you to reconstruct them later.

Why the agent's word isn't proof

An agent will tell you the work is done. It will tell you the tests are green. Of course it will. It's the same system that wrote the code, and it has every incentive to call the thing finished. None of that is proof. It's a report of a result, not the result itself, and the two have every reason to differ.

This is the same gap that makes architecture diagrams stop matching reality. Code has feedback loops that make drift loud: tests fail, types break the build, CI goes red. A sentence in a document saying "I tested this in staging and it works" has none of that. It stays green forever, because nothing checks it.

So the part of the record that can be checked against reality shouldn't rest on the agent's say-so. It has to come from the thing that ran: the test output, the CI status on the merge commit, the deploy that either came up or didn't, read straight from the source rather than typed into the document by the agent. If the checks are red, the record says red, no matter how confidently the session reported success.

An agent can run the tests, the staging deploy, the whole CI pipeline. What it can't be is the proof they passed. The record cites what ran, not the agent's word that it ran.

The plan does the same work from the other direction. It carries an explicit list of what the change was supposed to touch. The record of what actually changed is compared against it, and where the two disagree, the gap is flagged: something changed that nobody planned for. That gap is usually where the useful part of the review turns out to be.

A record that stays put

A decision record is only worth keeping if it isn't rewritten later to match whatever shipped. So the record freezes once the decision is made. You can still change it, but the change is an amendment with a reason attached, kept in the history, rather than an edit that erases what you used to believe. A design doc is the frozen why, the same instinct behind an architecture decision record, scoped to a single change instead of a single decision.

The system it describes keeps moving, the way a real system does. That's the split worth holding onto: the record is the frozen account of one change, and the architecture catalog is the living description of what's running today. Keeping those two apart is most of the idea.

A record you can't find again is nearly as useless as no record. If the names in it are links to the real services rather than loose prose, each service can list the changes that touched it, newest first. The question from the top of this post, why the booking flow charges synchronously, then has an answer six months from now with a date and a name on it, one click from the service itself.

Where this stops

Two caveats. A record like this doesn't read your code, so it won't notice on its own when the implementation drifts from the spec, and the plan-versus-actual check only reflects the changes that were actually recorded, by the agent or by you. It's a discipline, not a thing that happens while you sleep.

And it's overhead you don't want everywhere. A one-line fix doesn't need a spec, a plan and an evidence trail, and forcing one just teaches the team to rubber-stamp. This earns its keep on the change someone will question later, the one where in half a year the only witness left is an agent that has moved on to the next prompt.

In ArchDocs this is a design doc, and an agent connected over MCP can write the spec, the plan and the evidence as it works, with the service names resolving to real objects in the catalog. There's a short walkthrough on the coding agents page. Reading the diff the agent produced is a separate skill, covered here; this post is about the record you keep around it. If you don't keep architecture docs at all, a decision written into the pull request is the cheaper start, and the same rule holds there: cite what ran, not the agent's word that it ran.

The agent can write the code, run the checks, and draft most of the record around them. What you don't lean on is its say-so. The proof is whatever actually ran, and the record's job is to cite that, so nobody has to take the agent's word for it, or yours.