GitHub stores the code, not the decision. Where the "why" should actually live.

An architecture decision record (ADR) is a short document that captures one architecturally significant decision: the context that forced the choice, the decision itself, and the consequences that follow. Michael Nygard proposed the format in 2011, and the convention that stuck is a numbered Markdown file in doc/adr/ in the repository, one page, written once and never edited. If the decision changes later, you do not rewrite the old record. You write a new one that supersedes it, so the log stays append-only and the history of your thinking stays readable.

That is the whole idea, and it is a good one. The rest of this post is about the part the format does not solve: most of the decisions that shape a codebase never become an ADR at all, and the reason is not laziness.

#What goes in an ADR

The Nygard template has four sections, and nearly every variant since (MADR, the AWS and Microsoft prescriptive versions) is a reshuffle of the same bones.

Title. A short noun phrase naming the decision. "Use PostgreSQL for the primary datastore," not "Database discussion."

Status. Proposed, accepted, rejected, deprecated, or superseded. The status is what makes the log a log rather than a pile.

Context. The forces in play: the constraints, the requirements, the things that were true when you decided. This is the section people skimp on and the section future readers actually need. A decision without its context reads as arbitrary six months later.

Decision. What you chose, in active voice. "We will use PostgreSQL," not "PostgreSQL seems like it might be reasonable."

Consequences. What follows, good and bad. What this makes easy, what it makes hard, what you now have to live with, and what you ruled out to get here.

Keep it to a page. An ADR is a snapshot of a decision, not a design document, and the moment it grows sections it stops getting written.

#When to write one

The rule of thumb from the AWS guidance and the Red Hat writeup agrees on the shape: write an ADR when the decision is architecturally significant, meaning it is expensive to reverse, it affects the structure of the system, or it constrains what the team can do later. Choosing Postgres over DynamoDB is an ADR. Choosing a variable name is not. Adopting an event-driven boundary between two services is an ADR. Bumping a patch version is not.

The useful test is the one Red Hat gives: an ADR is not a glorified changelog, and it does not replace good commit messages. If the answer to "why is this like this" is already visible in the diff, you do not need a record. You need one when the answer lives in a conversation that the diff cannot show, and when getting it wrong later will cost a rewrite.

#The decisions that never make it to doc/adr/

Here is the honest gap, and it is worth naming precisely because ADRs are good, not because they are not.

The ADR format works well for the decisions you know are significant at the moment you make them. You recognize the fork, you convene the discussion, someone writes the file. But most architectural drift is not made of those. It is made of the smaller decisions that only look significant in retrospect: the retry semantics someone picked while fixing a flaky test, the approach that got ruled out in a pull request thread and never wrote itself down, the reason the third service does its own auth instead of using the shared middleware. Nobody stops mid-fix to open a numbered Markdown file for those. They are load-bearing anyway.

Those decisions do get made somewhere, and the somewhere is almost always the work: an issue, a comment thread, a pull request review, a session with a coding agent. Git stores the code that came out the other side. It does not store the four alternatives you rejected, the constraint that ruled out the obvious approach, or the argument that changed someone's mind. The commit is the artifact, not the reasoning.

This has gotten sharper with agents in the loop. When an agent plans an approach, rules out two others, and implements the third, all of that reasoning exists in a context window, and the context window compacts or ends. The code survives. The reasoning does not, unless something outside the model wrote it down.

#Two records, one repository

The version that works in practice is not "ADRs or the tracker." It is both, doing different jobs.

Keep doc/adr/ for the big irreversible forks: the datastore, the service boundaries, the auth model. Those deserve a numbered, append-only, superseded-not-edited file that ships with the code and gets read on onboarding.

Then let the ordinary decisions land where the work already is, in the issue that produced them, at the moment they are made. The record is worth having only if writing it costs nothing, which means it has to happen in the same motion as the work, not as a separate ceremony afterward.

Radial is an issue tracker built so that motion is one command. It has a real CLI, a plain REST API, and an MCP server against the same issue lifecycle, so the same decision gets recorded whether you are in the terminal, in CI, or driving it with an agent. Every command takes --json.

# Record the decision on the issue that produced it, as it happens
radial comment RAD-482 -m "Chose optimistic locking over a row-level mutex. Ruled out the queue: adds a broker to a path that must stay synchronous. Revisit if write contention exceeds ~200/s."

# Link it to the issue that will actually have to live with it
radial link RAD-482 related RAD-611

# The constraint that ruled out the obvious approach is itself work: file it
radial create "Write ADR-014: locking strategy for the ledger writer" -t ENG -p high --json

That last command is the seam between the two records. The tracker catches the decision at the moment it is made, when the context is still in someone's head, and the ones that turn out to be architecturally significant graduate into a proper ADR in the repository. The ones that do not are still findable, still attached to the work, and still readable by the next person or the next agent.

Nothing about this is an AI feature. Radial does not read your code, summarize your diffs, or generate your ADRs. It is a fast issue tracker that people and agents can drive over CLI, REST, and MCP, and the durable record is what happens when decisions get filed the ordinary way. The intelligence stays in your agent, your model, your keys.

#FAQ

#What is an architecture decision record?

An architecture decision record (ADR) is a short document capturing one architecturally significant decision, along with its context, the decision itself, and its consequences. It is typically a numbered Markdown file stored in the code repository, often under doc/adr/, and it is written once rather than edited: if the decision changes, a new record supersedes the old one, keeping the log append-only.

#What should an ADR contain?

The Nygard template, which most variants follow, has four sections: title (a short noun phrase naming the decision), status (proposed, accepted, rejected, deprecated, or superseded), context (the forces and constraints that made the decision necessary), decision (what you chose, in active voice), and consequences (what follows, including what you ruled out and what you now have to live with). Keep it to roughly one page.

#When should you write an architecture decision record?

Write one when the decision is architecturally significant: expensive to reverse, structural, or constraining on what the team can do later. Choosing a datastore or a service boundary qualifies. Naming a variable does not. If the reason is already visible in the diff, a good commit message is enough. Write the ADR when the reasoning lives in a conversation the diff cannot show.

#What tools are there for architecture decision records?

The common ones are Markdown-based and deliberately minimal: MADR provides a lean template, and adr-tools is a set of command-line tools that create, number, and supersede records in your repository. Both keep the records as plain files next to the code, which is the point of the format. For the smaller decisions that never reach a numbered file, an issue tracker with a comment thread does the job at the moment the decision is made.

#Where should decisions live if not in an ADR?

In the work that produced them. Most decisions are not architecturally significant enough to justify a numbered file, but they still shape the system: the retry semantics, the ruled-out approach, the constraint nobody documented. Recording them on the issue keeps them attached to the work, findable later, and readable by the next person or agent. See agentic coding ships the 80% for the version of this argument that involves coding agents.

#Do ADRs replace commit messages or a changelog?

No. An ADR is not a glorified changelog, and it does not replace good commit messages. A changelog records what changed; a commit message records what this change does; an ADR records why a significant structural choice was made and what it rules out. They answer different questions and the ADR is the most expensive of the three, which is why it should be reserved for decisions that are costly to reverse.

#The short version

An ADR is a one-page, append-only record of a significant technical decision: context, decision, consequences, stored with the code. Use it for the forks that are expensive to reverse. But most of what shapes a codebase is decided in smaller moments, in an issue, a review, or an agent session, and Git stores what those produced, not why. Record those where the work already lives, and let the ones that turn out to matter graduate into a real ADR.

See the full CLI verbs and the API on the developers page, or read the manifesto for why the tracker stays a tracker.