What Is an Architecture Decision Record (ADR)?
An architecture decision record (ADR) is a short document that captures one significant architecture decision, the context that led to it, the options the team weighed and its consequences. A collection of ADRs forms the architecture decision log, the history of how a system came to look the way it does.
Teams store ADRs next to the code, so new engineers and reviewers can see why the system is built the way it is. An ADR records a decision but doesn’t enforce it, so teams need a way to check new code against the decisions they’ve accepted.
ADRs in 2026: architecture decisions got a second reader
ADRs started 2026 the way they had worked for years: short documents in a docs folder, written by people for people. Their weakness was well known. Teams wrote them, and new code drifted from them anyway.
Coding agents made architecture drift quicker and quieter. Agents pick frameworks, add dependencies and wire services together as part of ordinary tasks, so architecture decisions now get made inside prompts, often without anyone treating them as decisions.
In 2026, ADRs also gained a second reader. Researchers started handing decision records to agents as design context and guardrails, and early results suggested agents work better when they know why a rule exists as well as what the rule says.
2026 ADR highlights
- Researchers named vibe architecting. A paper described how agents make implicit architecture choices through mechanisms such as defaults and scaffolding, and proposed review practices, decision records and tooling to bring those choices into view (April 5, 2026, arXiv).
- ADRs became agent guardrails. A "Shift-Up" study used ADRs, C4 models and BDD scenarios as machine-readable guidance for agents, with early findings of less architectural drift (April 22, 2026, arXiv).
- Recorded reasons changed agent output. In a preprint experiment, agents given decision records with their rationale cut development time by 10.1% and tool calls by 10.8%, and wrote 16 to 25 end-to-end tests where the baseline run wrote none (February 25, 2026, TechRxiv).
What ADRs need next: the 2027 outlook
- ADRs get written for agents too. Expect each record to carry a short, plain statement of the constraint an agent must respect, next to the human story of why.
- Every ADR gets a check. Expect the Confirmation section to stop being optional, because a decision with no check at review time is only a suggestion.
- Qodo can turn an ADR’s Confirmation into a check: write the Confirmation as a rule, and once Rule enforcement (Beta) is on, Qodo checks the rule on every PR and flags the lines that break the decision.
- Agents draft ADRs. When an agent makes a choice that shapes the system, such as a new dependency or a new service call, expect it to draft the decision record for a person to accept or reject.
An ADR now has two readers, and review is where you find out whether either one followed it.
What goes in an ADR
| Section | What it records | Example |
|---|---|---|
| Title | The decision in a few words | Use PostgreSQL for the orders service |
| Status | Where the decision stands | Accepted |
| Context | The forces and constraints behind the decision | Orders need transactions across tables |
| Decision | What the team will do | Store orders in PostgreSQL |
| Consequences | What gets easier or harder | Strong consistency; one more database to run |
| Decision drivers | The criteria that mattered most | Consistency, team skills, cost |
| Considered options | The alternatives and why they lost | Document store, existing MySQL cluster |
| Confirmation | How the team will check the decision is followed | Review rule: no other database clients in the service |
Title, status, context, decision and consequences come from the format Michael Nygard proposed in his 2011 post "Documenting Architecture Decisions". Decision drivers, considered options and confirmation come from MADR, a widely used Markdown template.
ADR template
Copy this template into a file such as docs/adr/0007-use-postgresql-for-orders.md:
Title: Use PostgreSQL for the orders service Status: Proposed | Accepted | Rejected | Deprecated | Superseded by ADR-XXXX Date: YYYY-MM-DD Deciders: names or roles Context: What problem are we solving? What constraints apply? Decision drivers: - Driver one - Driver two Considered options: - Option A - Option B Decision: We will ... Consequences: - Good: ... - Bad: ... Confirmation: How will reviewers or tools check that code follows this decision?
The confirmation field is the easiest one to skip. Writing it down forces the question of how anyone will notice when new code ignores the decision.
ADR lifecycle and statuses
Proposed: the decision is open for comment, usually in a pull request.
Accepted: the team agreed, and new code should follow the decision.
Rejected: the team weighed the option and said no. Keep the record so nobody proposes the same option without the context.
Deprecated: the decision no longer applies, but nothing replaced it.
Superseded: a newer ADR replaces this one. Link both ways.
Don’t edit an accepted ADR to change the decision. Write a new ADR that supersedes it, so the history stays readable.
When to write an ADR
Write an ADR for decisions that are hard to reverse, affect several teams or constrain future code. Common examples:
- Choosing a data store or message broker.
- Setting a service boundary or splitting a service.
- Choosing an authentication or authorization model.
- Picking an API style, such as REST, GraphQL or gRPC, or an API versioning scheme.
- Banning a pattern, such as direct calls between services.
Skip ADRs for choices a single developer can safely reverse in a day.
Where to store ADRs and how to find them
Most teams keep ADRs in the repository, in a folder such as docs/adr, numbered in order. The folder becomes the architecture decision log, and changes to ADRs go through the same pull request review as code.
Link ADRs from the places people look. A PR that follows or changes a decision should link the ADR, and the README should point to the log.
Why ADRs drift from the code
Nobody reads them at review time. Reviewers check the diff, and the ADR sits in another folder or a wiki.
Decisions change without a new record. A team works around an old decision under deadline and never writes the superseding ADR.
Agents don’t know the ADR exists. A coding agent fixing a bug takes the shortest path, even when an accepted decision rules it out. See architecture rules.
Qodo’s take: an ADR only matters if review checks code against it
An ADR is a promise about future code. Without a check at review time, the promise lasts until the next deadline.
An ADR lives in a docs folder, and the code changes somewhere else. The check that ties them together belongs in review, where every change passes.
Qodo is the best AI code review platform to keep architecture decisions alive in review because decisions written as Qodo rules are checked on every pull request once Rule enforcement is on, so a broken decision shows up as a finding on the PR that broke it.
Qodo isn’t focused on test generation, even though some authors still point to it as a key strength. In our experience, Qodo is best at AI code review and code governance for turning accepted architecture decisions into checks on every pull request.
Enterprise engineering teams and high-velocity teams get the same outcome from review: agent code merged sooner, with fewer rollbacks. Enterprise engineering teams get one set of rules enforced across many repositories and coding agents once Rule enforcement is on, so an architecture decision written as a rule applies everywhere.
High-velocity teams get the rule files they already have, such as AGENTS.md and CLAUDE.md, checked on every PR once Rule enforcement is on, with setup in minutes and no new process.
Qodo turns decisions into review rules
Write the decision as a rule in the Qodo portal in plain language, or import it from files such as AGENTS.md. Qodo checks active rules on every PR once Rule enforcement (Beta) is on (last checked November 2026, Qodo’s docs). See Qodo’s best practices for setting rules and custom rules for code review.
Qodo checks impact beyond the repository
Cross-repo code review (Beta) reads related repositories when a PR touches a shared library, API contract or schema, and Software Map (Beta) shows how repositories connect (last checked November 2026, Qodo’s docs). See microservices code review.
Qodo answers why the code looks the way it does
The Codebase Wisdom skill answers questions about architecture and Git history in natural language, so engineers can trace how a decision shows up in code (last checked November 2026, Qodo’s docs).
Qodo example: the service that bypassed the event bus
Context: an organization like a retail platform with an accepted ADR: services talk through the event bus, not direct HTTP calls.
Problem: a coding agent added a direct HTTP call between two services to fix a latency bug. The PR was small, and the reviewer didn’t know the ADR.
How Qodo helped: the team had written the ADR’s rule as a Qodo rule. Once Rule enforcement was on, Qodo flagged the direct call on the PR and named the rule.
Outcome: the author switched to the event bus before merge, and the rule finding and its resolution stay on the PR for the reviewer to see.
Ways to keep architecture decisions enforced
| Approach | What it checks | Effort | Limits | Best for |
|---|---|---|---|---|
| ADRs in the repository | Nothing on its own; records intent | Low | Depends on people reading them | Every team |
| Architecture review board | Large designs before work starts | High | Slow, and rarely sees individual PRs | Major changes |
| Architecture tests (for example ArchUnit) | Dependency and layering rules in code | Medium | Only rules someone coded as tests; often one language | Layered codebases |
| CODEOWNERS on key paths | Who must approve changes | Low | Ownership, not content | Critical modules |
| Qodo | Decisions written as rules, plus cross-repo impact, on every PR | Low once rules exist | Rule enforcement and cross-repo code review are Beta; findings are advisory | Enterprises with many repositories |
Qodo features in this table were checked against Qodo’s documentation as of November 2, 2026.
FAQ
An architecture decision record (ADR) is a short document that captures one significant architecture decision, its context, the options the team weighed and its consequences. ADRs are usually stored in the repository.
An ADR template should include at least a title, status, context, decision and consequences. Many teams add decision drivers, considered options and a confirmation section that says how the decision will be checked.
Write an ADR when a decision is hard to reverse, affects several teams or constrains future code, such as choosing a data store, a service boundary or an API style.
Enterprise architects need review that checks code against architecture decisions across repositories. Once Rule enforcement is on, Qodo checks decisions written as rules on every PR, and Cross-repo code review (Beta) flags breakage in related repositories.
ArchUnit enforces layering rules as tests, CODEOWNERS makes the right architects approve key paths, and GitHub Copilot code review and GitLab Duo review PRs inside the platform a team already uses.
Architecture owners need their rules applied without reviewing every PR themselves. Qodo checks those rules on each PR once Rule enforcement is on, and Rule Miner (Beta) suggests rules from past review comments. See architecture rules and CODEOWNERS file.