Architecture Decision Records (ADRs)
Short records of why a technical decision was made: the context, the options considered and the consequences accepted, not just the choice itself.
- Documentation refresh initiative is active with measurable progress
- The team writes a decision record when it chooses an architecture or a major dependency
- Written onboarding path exists (new developer can self-serve key setup steps)
- ADRs are indexed and searchable
- Onboarding path has been validated by at least one new hire completing it solo
- Documentation refresh tracking (issues, PRs, completion percentage)
- ADR directory in repository with recent entries
- Written onboarding guide with step-by-step instructions
What It Is
Architecture Decision Records are short, structured documents that capture why a significant technical decision was made — not just what was decided, but the context, the options considered, and the consequences accepted. Each ADR is a snapshot of the reasoning that existed at a specific moment: why Postgres was chosen over MongoDB, why a monolith was split into services, why a particular authentication library was selected over its competitors. The record outlives the memory of the people who made the decision.
The standard ADR format is deliberately minimal. A title, a status (proposed, accepted, deprecated, superseded), a context section explaining the forces at play, a decision section stating what was chosen, and a consequences section describing what the decision makes easier and harder. The brevity is intentional: an ADR that takes an hour to write will be written. An ADR that takes a day will not. The goal is to make recording decisions cheaper than not recording them.
What makes ADRs valuable for AI-augmented development is their queryability. When an ADR is stored as a markdown file in the repository alongside the code it describes, it becomes part of the context an agent can read. An agent asked to refactor an authentication module can read the ADR that explains why HMAC was chosen over JWT, understand the security constraints that shaped the original design, and make a refactor that respects those constraints. Without the ADR, the agent is operating without institutional memory.
At L2, ADRs exist but are written inconsistently — some teams do it, others don't, and there is no enforcement or tooling. The value is already visible in the teams that practice it, but it has not been standardized organization-wide. The next step is making ADR creation a required part of the definition of done for significant architectural changes.
Why It Matters
- Decisions without ADRs get relitigated - teams that don't record why they chose Kafka over RabbitMQ will have the same argument again in 18 months when a new engineer joins who prefers RabbitMQ; the ADR closes the debate by making the reasoning visible
- Agents need the why, not just the what - code tells an agent what was built; ADRs tell it why, enabling context-aware suggestions that respect the constraints that shaped the original design
- ADRs surface hidden constraints - the consequences section forces authors to articulate what the decision makes harder, which is often the most valuable information for future engineers and agents
- Supersession chains explain evolution - when an ADR is marked "superseded by ADR-042," the history of how thinking evolved is preserved; agents can understand that the current approach is the third attempt, not the first
- Onboarding time drops measurably - engineers who can read the ADR history of a codebase reach informed independence faster than those who must reconstruct reasoning through code archaeology
Getting Started
-
Choose a location and format - store ADRs as markdown files in a
docs/decisions/directory at the repository root, numbered sequentially (0001-use-postgres.md). Use a standard template: Title, Status, Date, Context, Decision, Consequences. Commit the template to the repository. -
Write your first three ADRs retroactively - pick the three most-asked-about architectural decisions in your codebase and write ADRs for them now, even though the decisions are old. This demonstrates the format and immediately reduces the load on seniors who currently answer these questions repeatedly.
-
Add ADR creation to your definition of done - any PR that makes a significant architectural change (new service, new data store, new authentication mechanism, removal of a major dependency) must include or update an ADR. Add this to your PR template as a checkbox.
-
Link ADRs from code - add a comment near the relevant code pointing to the ADR:
// See docs/decisions/0007-hmac-auth.md for why HMAC was chosen here. This creates a bidirectional connection that agents and engineers can follow. -
Review ADRs in architecture reviews - when doing architecture review, open the relevant ADRs first. This normalizes reading them and surfaces ADRs that need to be marked superseded or deprecated.
-
Index ADRs for agent access - add a
docs/decisions/README.mdthat lists all ADRs with one-line summaries. This gives agents a navigable index without requiring them to read every ADR to find the relevant one.
Write ADRs at the moment of decision, not after implementation. The reasoning is sharpest when the options are freshest. An ADR written post-hoc often omits the alternatives that were seriously considered, which is exactly the information that matters most.
Common Pitfalls
Writing ADRs as post-hoc justifications. An ADR written after the decision has already been implemented and merged tends to omit the alternatives that were genuinely considered and the tradeoffs that were accepted. It becomes a document explaining why the decision was correct rather than a record of the reasoning process. The value of an ADR is highest when it captures genuine uncertainty and the factors that resolved it.
Storing ADRs in a wiki instead of the repository. ADRs in Confluence or Notion drift from the code they describe, become inaccessible to agents, and are not versioned with the codebase. An ADR that says "we use Postgres" in a Confluence page that hasn't been touched since 2021 is less trustworthy than the same ADR committed in the repository, where its date and authorship are part of the git history.
Treating every decision as ADR-worthy. ADRs for naming conventions, minor library choices, and formatting preferences create noise that dilutes the value of genuine architectural records. Reserve ADRs for decisions with significant and lasting consequences: choices that would take more than a sprint to reverse, choices that constrain the design space in important ways, choices that will be repeatedly questioned by new team members.
Forgetting to supersede outdated ADRs. An ADR that was accepted in 2020 and is now contradicted by current practice is more dangerous than no ADR — it tells agents and engineers the wrong thing with apparent authority. Every ADR that is reversed must be marked superseded with a pointer to the replacement. A quarterly ADR review is a reasonable forcing function.
Making the template too long. A six-section ADR template with required fields for stakeholders, risk assessment, and implementation plan will not be filled out. Engineers will skip it or write minimal content to satisfy the form. The template should take 15-30 minutes to complete for a decision that is worth recording. Complexity should come from the decision being complex, not from the template being thorough.
How Different Roles See It
Bob has 40 engineers and a codebase that is six years old. His senior engineers spend significant time in architecture review meetings re-explaining decisions that were made years ago. New engineers ask the same questions every quarter. When he tries to delegate architectural decisions to mid-level engineers, those engineers lack the context to make good choices independently — they don't know what was tried before or why the current approach was selected.
ADRs directly address Bob's scaling problem. If the reasoning behind major decisions is captured in the repository, junior and mid-level engineers can reach informed independence without consuming senior time. Bob should make ADR creation a required practice for all teams, track the ADR count as a proxy for documented architectural surface area, and celebrate the practice publicly — highlighting ADRs in architecture review as a model of how decisions should be made and recorded. Within six months, he should see a measurable reduction in the time seniors spend re-explaining historical decisions.
Sarah is focused on onboarding speed and knowledge transfer. Her best onboarders are the ones who pair with seniors for the first month — but that approach doesn't scale as the team grows, and it creates uneven experiences depending on which senior an engineer is paired with. She wants a way to give every new engineer access to the same institutional memory that seniors carry in their heads.
ADRs are the most direct path to structured institutional memory at Sarah's disposal. She should work with Victor to build an onboarding checklist that includes "read the ten most important ADRs in this codebase" as one of the first steps. She should measure which ADRs new engineers find most useful and use that signal to identify which folk traditions still need to be documented. Over time, she can track the correlation between teams with strong ADR coverage and onboarding-to-productivity time — this is the metric she can bring to Bob to justify investing engineering time in ADR quality.
Victor has been trying to give AI agents better context about the codebase, and he keeps running into the same problem: agents make suggestions that are technically correct but architecturally wrong. They suggest using a library that was explicitly rejected three years ago, or propose a pattern that was tried and abandoned. The code tells the agent what is there; it cannot tell the agent what was tried and rejected.
ADRs are the primary mechanism for feeding agents architectural memory. Victor should configure the team's agent setup to include the docs/decisions/ directory in the agent's context window by default — either through the CLAUDE.md file or through an MCP server that surfaces relevant ADRs based on the files being edited. When an agent is working on authentication code, it should automatically have access to the ADR explaining why the current authentication approach was chosen. Victor should measure the quality of agent suggestions before and after ADR context is added, and share the results with the team as a concrete demonstration that documentation quality directly affects agent output quality.
Further Reading
From the Field
Recent releases, projects, and discussions relevant to this maturity level.
Where does your team actually sit on this?
This guide describes one level of one area. Run the assessment to place your team across all 16 areas, see which gates you have passed, and get a report you can take to your stakeholders.
Knowledge Management