Decision capture for AI coding agents: a write-path problem, not a discipline problem

Why documentation loses to the deadline at enterprise scale, and the write path that does not.

July 2, 2026 9 min read

A team inherits a billing service that has run in production for six years. The engineers who built it have moved on, or moved companies. The code tells the new team exactly what it does, and nothing tells them why it rejected the obvious queue-based design, which of its three retry paths is load bearing and which is vestigial, or why one deliberately ugly function has survived every refactor since a 2023 outage. That reasoning was real, and it lives nowhere a new hire or an AI agent can reach. Three weeks in, an agent tidies the ugly function and reopens the outage. The instinct that follows is the one every engineering org has: we need to be more disciplined about documenting our decisions.

You will not be more disciplined, and neither will any team, and it is not a character flaw. Decision capture for AI coding agents is not a discipline problem. It is a write-path problem, and that distinction decides whether the record is ever written. Capturing that decision was a separate act, done after the fact, from memory, that cost the writer time now and paid some stranger later, and under a deadline that is the first work to fall off. This is not a small tax. When Fortune reported MIT's finding that 95% of enterprise generative-AI pilots were failing, the diagnosed cause was not model quality; the tools "stall in enterprise use since they don't learn from or adapt to workflows." An agent that cannot see why your org decided anything is running on a fraction of the context, and the missing fraction is the part nobody wrote down.

Why do AI coding agents ignore decisions your team already made?

Because the decision is not in the code. Code records what a system does, never why the team chose it over the alternative it rejected. That rationale lives in a pull request thread, a design doc, a call, or a person's memory, and an agent reads none of those at the moment it edits a file. As Stack Overflow's engineering editorial put it in March 2026, the context these tools lack is "the knowledge that teams tried that approach two years ago and changed course for good reasons." The first post in this series made the structural version of the point: a decision only binds an agent if the store it reads carries who decided it and whether it is still in force. This post is about the step before any store can help. Someone has to get the decision into it, and that is where teams actually fail.

Decision capture is a write-path problem, not a discipline problem

Capture fails on economics, not willpower. A separate act of documentation has an immediate personal cost and a deferred, externalized benefit: you spend minutes now, and someone else, later, gets the payoff. Work with that shape is exactly what a person under deadline drops, so the capture rate settles at a low ceiling. When people put a realistic number on it, it tends to come back around a quarter to a third, reached only after months of habit building. Treat that as a hypothesis to measure on your own teams rather than a law, but the mechanism is not mysterious, and no mandate has ever durably moved it, because engineers correctly notice that the last record they wrote helped no one they could see. As Gergely Orosz and Elin Nilsson wrote in May 2026, "AI is an amplifier, not a fixer. Good software engineering practices get multiplied. So do the bad ones." The distance between the decisions a team makes and the ones it records is one of those practices, and an agent now multiplies it into everything it builds.

The decisions that go missing are the ones that matter most

The misses are not random, and this is the part the "just document more" advice never reckons with. The calm, low-stakes, uncontested decisions are the ones with time to write down. The fast, contested, high-stakes calls are the ones that skip it, because that is when urgency is highest and when writing the decision down means reopening an argument and naming who lost. At enterprise scale it gets worse in a specific way: the decisions with no single owner, the cross-team ones about authentication, retries, data residency, are simultaneously the highest-stakes and the least likely to be captured, because no individual is accountable for recording them. Your write path fails hardest on exactly the decisions a new team, or an agent, most needs to be told.

A decision recorded later is not a decision record

When the gap becomes visible, the reflex is to backfill: write the record three months on. It does not work, and the reason matters. A decision reconstructed after the fact has the form of a decision and not the substance. The alternatives are forgotten, the constraints are hazy, and the consequences get written as outcomes you already know rather than as a forecast the team actually committed to. For an org under SOC 2 or similar change-management controls, this is not a nuance, it is the difference between evidence and theater. An auditor asking why a change was authorized, and by whom, cannot accept a rationale invented after the change shipped, any more than an agent can trust it. Provenance is only real if it is captured at the moment of the decision, the property the first post called admission, and you cannot manufacture it later for either reader.

At scale, a low capture rate is a continuity risk

The usual framing treats captured context as an onboarding win: new hires can read the decisions. Invert it. The decisions a new hire most needs are the adversely-selected ones that were never written, so ramp time is bounded not by how searchable your wiki is but by how much was captured in the first place. The same gap is a business-continuity risk. When the staff engineer who is the living rationale for a subsystem leaves, the org does not lose a person, it loses the only copy of why the subsystem is the way it is. And across dozens of teams, a decision no one recorded is a decision every team re-derives, which is architectural drift on a schedule and re-litigation as a standing meeting. At one team these are annoyances. At fifty they are the operating cost of not having a write path.

The write path that survives shipping speed

If a separate authoring act ceilings out, the capture cost has to approach zero, which means capture cannot be a separate act at all. The decision is already being expressed, in writing, at the moment it is made: the pull request comment, the review approval, the ticket that just closed with a stated reason. A write path that works reads it from there and drafts the record, so the decider's marginal cost is the words they were already going to write. The first post established the one human step that cannot be removed, and this post assumes it: an extracted decision is a belief until someone with standing ratifies it, so the person confirms rather than composes. What makes this an enterprise argument rather than a startup one is that large organizations already run the boundaries it attaches to. Change-approval boards, sign-offs, mandatory review: the ratification step is already there and already required. The distance between the person who decides and the person who would have documented is widest at enterprise scale, which is precisely where collapsing the two into a single ratified byproduct pays the most. You are not adding a process. You are capturing the one you already run.

What this does and does not claim

It does not claim documentation is worthless; some decisions earn a deliberate written record, and you should write those. It does not claim full automation; the ratification step is human and load bearing on purpose, because a machine draft of intent can be wrong and a wrong record is worse than none. And the capture-rate ceiling is a number to measure on your own teams, not a guarantee. The narrow claim, and I think a hard one to escape, is this: any write path whose cost to the decider is a separate authoring act will settle below the decisions that matter most, so capture has to ride the act where the decision is already made, with the human ratifying rather than authoring. Build that write path yourself if you prefer; the economics do not move, because they come from what a deadline does to deferred work. We built Brief to be that write path, and the store, described in the first post, that it fills.

Your team's discipline was never the bottleneck. Capture the decision where it already happens, let the person confirm instead of compose, and the record starts to exist for the auditor, the new hire, and the agent, in the one moment it is still true.

Frequently asked questions

Why does my AI coding agent keep re-suggesting an approach we already rejected? Because the rejection lived in a review thread or a call, not in the code, so the agent never sees it. Code encodes the chosen path, not the rejected alternative or the reason for rejecting it. Until the decision and its rationale sit somewhere the agent reads at edit time, it keeps re-deriving the most conventional option, which is frequently the one you ruled out.

What is the difference between an ADR, a decision log, and an AGENTS.md file? An architecture decision record captures one decision and its rationale at a point in time. A decision log is a running list of them. An AGENTS.md or CLAUDE.md file is standing instructions loaded into an agent's context. All three are author-first: someone has to stop and write them, which is why they capture only the decisions that had time to spare. The write-path problem is orthogonal to the format.

How do you capture engineering decisions automatically? By reading them from where they are already written, the pull request, the review approval, the resolved ticket, and drafting a record the decider ratifies rather than authors. That drops the marginal cost of capture close to zero, which is the only thing that lifts the capture rate above the author-first ceiling.

Do bigger context windows or better models fix this? No, and that is the previous post in this series: a larger window can hold more context, but it cannot capture a decision that was never written down, and it cannot tell a current decision from a superseded one. Capacity is a read-side lever. Capture is a write-side one.