Architecture Decision Records: the complete guide (2026)
An architecture decision record (ADR) is a short document that captures one significant decision: what you decided, why, what you considered, and what it costs you later. One decision per file. Plain text, in the repo, next to the code it governs.
That's the whole idea. The reason ADRs are having a comeback in 2026 isn't nostalgia. It's that AI coding agents now write a lot of your code, and an agent that can't see why something was built a certain way will happily refactor the reason away.
Why ADRs are back
For years ADRs were a nice-to-have that most teams skipped. Then two things happened.
First, teams got bigger and more distributed. Past 50 engineers and a few squads, you can't "just ask" anymore. The person who knows why the payment service retries exactly three times has left, or is on holiday, or is in a different timezone. The decision lives in someone's head, or in a Slack thread that scrolled off three months ago.
Second, agents arrived. An AI agent refactoring "verbose" retry logic doesn't know that code was written that way after a Black Friday incident double-charged thousands of customers. The verbosity was the decision. Strip it and you reintroduce the bug. The agent had no way to see the reasoning, because the reasoning was never written down anywhere it could read.
ADRs fix the upstream problem: they put the reasoning somewhere durable, in plain text, where both a new hire and an agent can find it.
What goes in an ADR
Keep it short. If it takes more than ten minutes to write, the format is fighting you. The classic Michael Nygard structure is still the best starting point:
- Title - a short noun phrase. "Use Postgres for the event store."
- Status - proposed / accepted / superseded.
- Context - the forces in play. What's true right now that makes this a real decision and not an obvious one.
- Decision - what you're actually doing, stated plainly.
- Consequences - what gets easier, what gets harder, what you're now committed to. This is the part future-you actually needs.
A copy-paste ADR template
# ADR 0007: Use Postgres for the event store
- Status: Accepted
- Date: 2026-05-20
- Deciders: platform team
## Context
We need durable, ordered, queryable storage for domain events. We already run
Postgres in production and the team knows it well. Kafka was considered but adds
operational surface we don't have the headcount to own yet.
## Decision
Use a single Postgres table as the event store, with a monotonic sequence
column for ordering. Revisit if event volume exceeds ~10k/sec sustained.
## Consequences
- Easier: one less system to operate, transactional writes alongside state.
- Harder: we own partitioning/retention ourselves; no built-in fan-out.
- Committed: consumers read by sequence, so that column is now load-bearing.
Number them sequentially (0001, 0002...). Never delete one. When a decision
changes, write a new ADR that supersedes the old one and link them. The chain
of decisions is the value, not any single record.
ADR tools, compared
There's no dominant tool, which tells you the field is young. What exists:
| Tool | What it is | Good for |
|---|---|---|
adr-tools (Nygard) | Bash CLI, Nygard format | Solo / small repos, zero deps |
dotnet-adr | .NET global tool, templates | .NET shops |
| Log4Brains | Logs ADRs, publishes a static site | Teams that want a browsable archive |
| adr-manager | Web UI over Markdown in GitHub | Non-CLI contributors |
Just Markdown in /docs/adr | No tool at all | Most teams, honestly |
For a lot of teams, a folder of Markdown files and a numbering convention is enough to start. The tooling question only matters once you hit the real problem, which isn't writing ADRs.
The real problem: ADRs go stale
Here's what nobody tells you when they recommend ADRs. The hard part isn't the template. It's that decisions don't stay in the ADR file.
You write ADR 0007: use Postgres for the event store. Six weeks later someone
proposes Kafka again in a Slack thread, a different squad ships against the old
assumption, and a ticket in Jira quietly contradicts the ADR. Nobody updated
the file, because updating the file is friction and the decision happened
somewhere else.
So you end up with two sources of truth: the ADR that says one thing, and the actual current state of the org that says another. Both teams think they're right. Neither sees the conflict until it shows up as rework.
This is the gap we built Align to close. ADRs are the right instinct: write decisions down. The missing piece is keeping them connected to where decisions actually get made and changed (Slack, GitHub, Jira, Confluence, calls) and flagging when a new decision contradicts an existing one before it ships, not after.
Where to start
You don't need a tool to start. Today:
- Add a
docs/adr/folder to your main repo. - Drop the template above in as
0001-record-architecture-decisions.md(the first ADR is always "we're going to use ADRs"). - Write the next real decision your team makes as
0002.
Then, once you've got a handful and you're already feeling the "wait, didn't we decide this differently in Slack last month?" pain, that's the moment a decision graph earns its place. That's the problem Align exists for.
FAQ
What is an architecture decision record? A short document that captures one significant architecture decision: the context, the decision itself, and its consequences. One decision per file, in plain text, stored next to the code it governs.
What should an ADR contain? Title, status (proposed/accepted/superseded), context (the forces in play), the decision stated plainly, and the consequences (what gets easier, harder, and what you're now committed to).
Are ADRs still worth it in 2026? Yes, and more than before. AI coding agents will refactor away reasoning they can't see. ADRs put that reasoning somewhere durable that both new hires and agents can read.
What is the best ADR tool?
For most teams, plain Markdown files in docs/adr/ are enough to start. Adopt a
tool (adr-tools, Log4Brains, dotnet-adr) only when you feel a specific pain
Markdown can't solve. See ADR tools compared.
Why do ADRs go stale? Because decisions don't stay in the file. They change in Slack, GitHub and Jira, and nobody updates the ADR. Keeping ADRs connected to where decisions actually change is the problem Align solves.
Align captures engineering decisions across the tools your team already uses, links them into a queryable graph, and catches cross-team conflicts before they ship. See how it works.