Keeping the reasons behind a change
Teams lose the reasons behind their code, and making engineers write decision records afterwards hasn't fixed it. Let a model draft the record from the threads where the decision was made, and have a person sign off on every entry.
Say your team owns a nightly job that exports the day’s orders to a partner’s API in batches. Near the top of the file there’s a constant:
EXPORT_BATCH_SIZE = 25
A new engineer picks up a ticket about the export being slow and asks an agent to speed it up. The agent sees 25, bumps it to 500, runs the tests (they use a fake of the partner’s API, so they pass) and opens a two-line pull request, which is approved before lunch.
Two years ago somebody set that number to 25 on purpose. The partner’s API times out on big requests, and at 100 rows per batch the export was falling over every few nights. Whoever tracked it down wrote the whole story into the review thread, including the two fixes they tried first. Retrying failed batches doubled the load on the partner. Sending batches in parallel got rows rejected for arriving out of order. But the commit message only says “reduce export batch size.” git blame takes you straight to that commit, and the commit tells you nothing about why.
Michael Nygard described this problem back in 2011, in the post where he proposed architecture decision records. When you hit a decision you don’t understand, he said, you’ve got two choices: blindly accept it, or blindly change it. Accept every old decision and the team ends up scared to touch anything. Change one without knowing why and you can undo whatever it was protecting. Our engineer and their agent changed it. They had no way of knowing better, because the reason was sitting in a two-year-old thread that nobody reads before changing a constant.
Where the reasons end up
Researchers at William & Mary went looking for where reasons like these get written down. In a preprint from April 2026, they took a small sample of commits from five Java projects and read everything linked to each one: the commit message, the code comments, the issues, the pull requests and the code reviews. Nearly every commit had something saying what the change was for, but only about half had anything saying why it was needed. About 14 percent mentioned an alternative anyone had considered. Every one of those alternatives was in an issue, a pull request or a code review, and none was in a commit message or a code comment.
So the reasons that do get written down end up in the places a newcomer won’t look, and review threads don’t make much of an archive. Across two OpenStack projects, only 9 and 14 percent of review comments even touched on design. Most of what people say in review is about the lines on the screen, and the design talk that does happen is scattered across threads nobody will search.
Agents add one more place for reasons to disappear. When you and an agent work through two approaches in a session, that session ends up with a better account of the decision than anything else your team has: the options, what got tried, what broke and why. Then the session ends. Claude Code, for one, saves every conversation on the machine where it ran, which helps the person who had the conversation and nobody else.
Mandating decision records hasn’t worked
The usual answer is “write an ADR.” Nygard’s format is short: a title, the context, the decision, its status and its consequences, kept in the repo, with a reversed decision marked superseded instead of deleted. It’s a good format, and it caught on.
But look at what people actually write with it. A paper at ICSA 2026 went through thousands of decision records in open-source repos on GitHub, and most of them (about 63 percent) were created already marked accepted. The authors point out that this skips the deliberation the records are supposed to capture. The decision got made somewhere else, in a thread or a meeting, and someone wrote it up afterwards because the process said to.
That’s what happens when writing the record is a step in a process, and it’s why I think teams should stop mandating them.
A mandate doesn’t change who pays. Writing down reasons costs the person who knows them, right when they’ve finished and want to move on, and the payoff goes to somebody else a year or two later. Make the template stricter, or add an “ADR written?” box to the pull request checklist, and you’ll get more records written after the fact. But you still won’t get the alternatives and the failed fixes, because those were in the thread, and nobody copies a thread into a template.
Let a model draft it, and have a person sign off
The reasons are already written down, in the review thread and in the session. What’s missing is turning them into something the next person will find, and models are good at that part. One can read a merged pull request, its review thread and the session behind it, and draft an entry with:
- the decision, in a sentence;
- the reason, plus the alternatives that got tried or turned down;
- the code it applies to, like a constant, a route or a table;
- links back to the thread and the session.
Then somebody who was part of the decision signs off on it, fixes it, or throws it out.
The sign-off matters because extraction still isn’t reliable. The William & Mary researchers built an extractor for this kind of rationale. On alternatives it found most of the ones that were there (80 percent recall), but only about 15 percent of what it flagged were alternatives at all. The rest were sentences it mistook for them. Store every draft and your record fills up with things nobody decided, and your agents read them as settled.
Some review tools already learn from comments, and their defaults point the wrong way. CodeRabbit, a code review service, turns preferences people write in pull request and issue comments into “learnings” that shape its later reviews. You can require an admin to approve them, but a pending learning gets approved automatically when the waiting period runs out unless an admin rejects it first. The waiting period defaults to zero days. The same page suggests reviewing your learnings every quarter and warns that conflicting ones “can produce inconsistent behavior.” That might be acceptable for a naming preference. But for the reason a batch size is 25, a tool that writes rules into your process unless an admin happens to catch them in time is guessing on your behalf. I’d keep everything out of the record until somebody who was there says it’s right.
Old decisions get replaced
Even an entry somebody signed off on goes stale when the decision behind it changes. Maybe the partner fixes its API next year, and then 25 makes the job slow for no reason anyone remembers. A record that keeps the old entry next to the new one, with nothing linking them, is about as useful as no record at all.
Nygard already handled this: mark the old entry superseded and keep it. Deciding which entry replaces which is a judgment call, and it belongs to a person. A model can notice that a pull request touches the code an old entry is about and flag it for a person to look at, and I’d stop there. If the model decides on its own that last month’s decision no longer applies, you’re back where Nygard started, with someone changing a decision blindly.
Tying each entry to code also tells you when to look. An entry about EXPORT_BATCH_SIZE belongs in front of the author and the reviewer of any pull request that touches EXPORT_BATCH_SIZE. For entries about routes, tables and queues, a tool that reads the code can tell you when the behavior an entry describes has changed. suss is one: it writes down what each handler, consumer and query does, without using AI, which gives an entry about a route something to be checked against.
What the record is for
If the export job had an entry tied to that constant, the agent would’ve run into it before touching the number. The entry would have told it that the partner times out somewhere above 100 rows, and that retries and parallel batches were tried and dropped. It might still propose a change, but it would be one that deals with the timeout, and the reviewer would see the entry right next to the two-line diff.
In an earlier post I argued that a rule in a markdown file is only a suggestion to an agent while a failing test is a fact, and I still think so. Where a decision can be a test, like a check that fails when the batch size goes past the partner’s limit, write the test and link the entry to it. Most reasons can’t be tests, though. “Parallel batches arrived out of order and the partner rejected them” is context, and context has to live where people and agents both look before they change the code.
You’ve already paid for those reasons once, when somebody worked them out in a thread. Keeping them costs a draft from a model and a minute from someone who was there, which is a lot cheaper than the next engineer learning about the timeout from the partner.