Decision records and why-this-exists trails

A decision record is a short written account of a choice the team made and the reasoning behind it: the situation the team was in, the options on the table, the one it picked, and what it expected the choice to cost. The standard format comes from Michael Nygard, who named them architecture decision records: one small markdown file per significant decision, stored in the repository next to the code the decision governs, with a fixed skeleton of context, decision, and consequences. The advice is good, and I hold my own teams to it; asking a repository why it is shaped the way it is and getting silence back is a slow way to spend an afternoon, and I have spent a few. A file that short gets written in the half hour after a review ends rather than joining a backlog of documentation debt, it travels with the code through every branch and clone, and an engineer who reads it a year later learns what the code cannot tell them: why it looks the way it does.

The format does not, by itself, keep the practice alive: the common ending is an adr/ folder holding six records, the most recent one eight months old, started by an enthusiastic tech lead and abandoned once writing them began to feel like compliance. The abandoned folder also has a nastier cousin: the record that outlived the reasoning it captured, read by someone who takes three-year-old logic as current fact. Keeping a trail of records alive, and keeping it honest, takes a handful of habits the template does not supply.

Record only what will be questioned

Write a record when the decision was contested, when it would be expensive to reverse, or when the result will look arbitrary to a reader a year from now, and skip everything else. A library choice nobody argued about, swappable in a week, does not need a file; a service boundary that took three meetings to settle does. Hold the line on volume: a trail with two hundred entries buries the five that matter, and a team that promises to record everything eventually records nothing, because nobody keeps paying the overhead. When someone asks whether a decision deserves a record, ask back whether a future engineer could plausibly stand in front of the result and wonder why. If nobody will ever ask, the record has no reader, and a folder of unread records does not survive long enough to reach seven.

Capture within a day, next to the code

Write the record within a day of the decision closing, whichever forum it closes in: a design review or an argument on a pull request. The forum that makes the decision should also produce the record, as its last act, because a week later the losing arguments have gone soft in everyone's memory, and a record written late turns into a justification of the choice rather than an account of it. Keep the skeleton fixed and small: context, options considered, choice, consequences accepted. Keep the file in the repository, next to the code it governs, because a record kept in a separate wiki fails slowly: nobody opens the wiki during real work, so the records sit unread and go stale.

A decision record is also a different document from the ones that come before it: a request-for-comments document hosts structured disagreement before a commitment, a design document explores a solution space, and the record captures what was finally committed and why. A team that runs both of those still needs the record at the end, because the discussion is where the record's raw material comes from.

Spend the words on the rejected options

Give the bulk of the record's length to the roads not taken and the forces that ruled them out. The chosen option is the least valuable thing to describe, because it is visible in the code and stays visible; the options the team rejected, and the constraint that killed each one, stop existing the moment the meeting ends unless someone writes them down. A record that restates the implementation adds nothing and teaches readers to skip the folder. The rejected options also protect the engineer who argued for them: their reasoning stays on the record rather than being erased by the outcome, which makes it easier to commit to the decision honestly. Teams that skip this section pay for it later in confident cleanups: a senior hire, three weeks in, refactors a deliberately verbose retry path into something elegant, because the verbosity was the decision and nothing durable said so.

Supersede, never edit

Records have a lifecycle, and Nygard's template already contains it: a status field that moves through proposed, accepted, and superseded, along with the convention that an accepted record is never rewritten. When a recorded decision stops fitting the evidence, leave the old file alone and write a new record that points back at the one it replaces and says what changed in the world. A wiki page silently overwrites the team's old mind, while a trail keeps every change of mind readable. That difference pays for itself the first time the team needs to reverse course: nobody has to relitigate the original argument or defend a two-year-old position, because the new record only has to show what changed since. Companies that argue their engineering decisions in public request-for-discussion archives keep the superseded documents readable for the same reason; the visible history of changed minds is part of the value. You can fail in the other direction too: a team that treats an accepted record as permanent turns the trail into an argument against ever changing course.

Put the record where the question lands

A record only pays off when someone finds it at the moment their question forms, and that is a placement problem more than a search problem: link each record from the spots where "why is this like this" gets asked.

• Put the record's id in a code comment at the strange boundary.
• Link the relevant records from the service README.
• Put the two or three most consequential ones on the new-hire reading path.

Every one of those placements is aimed at one moment: a new engineer, two weeks in, asks why the service is split at an odd place, and the honest answer is that the reasoning lives in the head of someone who left last spring. Good placement also protects readers from stale records: someone who reaches a record from the code it governs sees the claim and the reality side by side, so a mismatch shows, while someone who arrives through search sees only the record and has no way to notice that it went stale.

Give the trail its second reader

If coding agents produce a meaningful share of your team's changes, the decision trail has a second reader. An agent that reads only the code sees what exists and nothing about why it exists, so deliberately awkward code looks like a cleanup opportunity; the verbose retry path from earlier is exactly the kind of thing an agent will politely simplify every time it passes through. I give agents two standing instructions: read the decision folder before proposing structural changes, and draft a record, marked proposed, for anything they decide on their own. Nothing new gets written for any of this; the same short files serve the second reader, and the rejected-options section earns its length a second time, because the designs the team walked away from live only in the record, so the record is the only place an agent can find them before proposing the next cleanup. I do not know yet whether the records agents propose for themselves will be worth keeping, and the instruction is cheap enough to find out. Building memory that both people and agents can read is a larger project than one folder; the decision trail is where I would start.

When not to write one

Each record costs a half hour now and pays off months later, and the reader it finally pays is rarely the person who wrote it. That gap means the habit needs defending before it shows results, and it also means some teams should barely write any: a prototype still hunting for product shape, or a codebase that turns over completely every quarter. In both, the honest answer to "will anyone stand here in a year and wonder why" is no, so record almost nothing. Everywhere else, the trail earns its keep quietly: it is the cheapest way a team buys the ability to change its mind without relitigating how it got here, and the only durable way to tell a future reader, human or otherwise, that the awkward part is awkward on purpose.