One Page ADRs: Repo First Architecture Decision Records Stay Current
An architecture decision record (ADR) is a short, append-only Markdown file stored with your code that captures a single architecturally significant decision, its rationale, and its consequences. The payoff is traceability: new hires, auditors, and your future self can see why the system looks the way it does instead of re-litigating settled arguments. Most teams store ADRs as numbered Markdown files in the repo and follow a strict rule: once a decision is accepted, you don’t edit it. You supersede it.
TL;DR:
ADRs should only be created for decisions that impact system structure, dependencies, or quality attributes, not for routine implementation details.
Write ADRs as a short, one-page Markdown file with essential fields like context, decision, alternatives, and consequences, stored in the code repository.
Maintain ADRs by respecting their status lifecycle, linking superseding records, and updating the last verified date to prevent outdated decisions.
Use numbered filenames in chronological order and incorporate ADRs into the normal development workflow, including reviews, linking, and automation.
Clearly assign ownership to each ADR, revisit decisions when dependencies change, and avoid editing accepted ADRs; instead, supersede them with new records.
Table of Contents
-
How Should You Store and Format Architecture Decision Records?
-
Editorial perspective: ADRs as a lightweight discipline that fits agile teams
When Should You Write an Architecture Decision Record?
Not every choice deserves a record. Writing one for every configuration tweak buries the decisions that actually matter, so the useful filter is “architecturally significant”: does this choice touch system structure, a major non-functional requirement, an interface boundary, or a third-party integration? AWS Prescriptive Guidance frames it the same way, tying ADR creation to decisions that affect structure, dependencies, or quality attributes rather than routine implementation detail.
Start the practice at the beginning of a workload, and if you’re joining a brownfield project, write retroactive ADRs for the decisions still shaping the system today, even if the context is reconstructed from memory or old tickets.
A few signals tell you it’s time to write one:
-
You’re choosing between multiple genuinely viable options, not just picking the obvious default.
-
The decision is expensive or slow to reverse, like a database engine or a message broker.
-
An external constraint, such as a vendor contract or a compliance requirement, is steering the choice.
-
You’re trading off performance against cost or scalability against simplicity.
A team picking between PostgreSQL and a managed NoSQL store for a new billing service is a textbook case. So is deciding whether authentication runs through an in-house identity service or a third-party provider.
What Should a Minimal ADR Template Include?
A one-page ADR beats a ten-page design doc that nobody rereads. Martin Fowler’s ADR format popularized the lightweight, Markdown-friendly version most teams still use today, and the fields below cover what a working ADR actually needs.
-
Title — a short, specific label (not “Database Decision,” but “Use PostgreSQL for Billing Service Persistence”).
-
Status — proposed, accepted, or superseded.
-
Date — when the decision was made.
-
Authors/Decision-makers — who owns this and who signed off.
-
Context/Problem — what forced the decision.
-
Decision — the actual choice, stated plainly.
-
Alternatives considered — brief pros and cons of what you didn’t pick.
-
Consequences/Implications — trade-offs, risks, and follow-up work.
-
Supersedes/Superseded-by — links to related ADRs.
-
Last verified — the date someone last confirmed the reasoning still holds.
Each field earns its place. Status and dates create an audit trail. Authors establish ownership. Alternatives prevent the “why didn’t we just use X” conversation from resurfacing every quarter. Keep the body brief and link out to longer design docs, RFCs, or benchmarks:
-
Link to spike results or proof-of-concept repos instead of pasting code.
-
Reference the ticket or PR that triggered the discussion.
-
Point to vendor documentation rather than summarizing it inline.
How Should You Store and Format Architecture Decision Records?
Write ADRs in Markdown and keep them in the repository, typically under doc/adr or docs/architecture, so they’re versioned, diffable, and sit next to the code they describe. Google Cloud’s ADR guidance recommends exactly this pattern, while acknowledging that some teams mirror key ADRs to a wiki for stakeholders who never open a repo. That mirror works fine as a read-only reflection, but the repo copy stays canonical. Wikis drift; Git history doesn’t.
Filenames follow monotonic numbering: 0001-choose-postgresql-for-billing.md, 0002-adopt-event-driven-order-processing.md, and so on. The number preserves chronological order even after files get renamed or moved, and it gives you a stable ID to reference in supersession links.
The workflow that keeps ADRs current mirrors your normal code review process:
-
Draft the ADR as a “proposed” status document.
-
Open a pull request so the team can comment on context and alternatives, not just the decision.
-
Merge only after the decision is genuinely accepted, then flip status to “accepted.”
-
Link the ADR’s file path in the PR or commit that implements it.
Light tooling helps without adding process. Command-line tools like adr-tools, a short shell script that generates numbered templates, or a CI check that fails a build if an ADR is missing required headers all keep the discipline from depending on memory alone.
How Do You Keep an ADR Log From Going Stale?
ADRs decay the same way any documentation does: quietly, until someone hits a wall trusting information that’s years out of date. The fix is a lifecycle discipline, not a bigger process.
-
Respect the status lifecycle. A decision starts proposed, becomes accepted, and eventually gets superseded. Microsoft’s Azure Well-Architected guidance treats the ADR log as append-only: once accepted, you don’t rewrite an ADR to reflect a new decision. You write a new one and mark the old as superseded.
-
Cross-link supersession in both directions. The new ADR references the old one, and the old one gets edited only to add a “superseded by” pointer, plus a link to the PR that implemented the change.
-
Assign a named owner to every ADR, and update that field during offboarding so decisions never orphan when someone leaves.
-
Set a verification cadence and explicit drift triggers. A dependency deprecation, a new compliance rule, or a traffic threshold crossed are all valid reasons to revisit an ADR’s “last verified” date.
-
Add an ADR check to release or PR checklists so drift gets caught during normal review instead of during an incident.
Pro Tip: Put “last verified” in the ADR header itself, not just in a changelog. A date sitting in the document a reader is already looking at gets checked; a date buried in Git history does not.
What Does a Short Architecture Decision Record Look Like?
A concise example beats an abstract description. Here’s a summary-level ADR for a common decision: choosing a local development database.
Title: Use SQLite for Local Development Database Status: Accepted Context: Developers need a fast, zero-config database for local testing; production runs PostgreSQL. Decision: Use SQLite locally, with a compatibility shim to catch dialect differences before code reaches staging. Alternatives: Running PostgreSQL in Docker locally (rejected: slower onboarding, extra resource use for a marginal fidelity gain). Consequences: Faster local setup, but the team must test PostgreSQL-specific features in staging before merge.
That’s the MADR/Nygard style: short, scannable, done in ten minutes. Reach for a longer form only when the decision involves multiple stakeholders, contested trade-offs, or regulatory exposure. Public ADR directories on GitHub are worth browsing for live examples of how mature teams structure and link theirs.
What Mistakes Quietly Kill an ADR Log?
Most dead ADR directories fail the same handful of ways.
-
Editing accepted ADRs instead of superseding them. Once a decision changes, the original context disappears if you overwrite the file. Fix it with a hard team policy: accepted means locked.
-
Orphaned ADRs with no owner. Nobody updates a record nobody’s responsible for. An owner field, checked during offboarding, prevents this.
-
Missing supersession links in one direction. A PR checklist item that requires updating both the old and new ADR closes this gap cheaply.
-
Reasoning rot from external change. A vendor pricing shift or a deprecated library can quietly invalidate a decision. Named drift triggers and a “last verified” date catch it.
-
Over-documentation. Long ADRs go unread. Keep them to one page and link out for depth.
Pro Tip: If an ADR takes longer to write than the meeting that produced the decision, it’s too long. Cut it back to context, decision, and consequences.
How Do ADRs Fit Into Everyday Engineering Workflows?
An ADR log only stays useful if it’s part of the workflow people already follow, not a separate ritual.
-
Add “link or create an ADR” as a checklist item on design docs and pull requests touching architecture.
-
Require new hires to skim the ADR index during onboarding, including who owns which decisions.
-
Pull relevant ADRs during incident response and audits. Knowing why a system was built a certain way speeds up root-cause analysis considerably.
-
Automate the boring parts: generate an index page from ADR files, build a small static site from the
doc/adrfolder, or add a CI check that fails a build if a new ADR is missing required headers.
None of this requires a governance committee. It requires the ADR folder to be as normal a stop in your workflow as the test suite.
Editorial perspective: ADRs as a lightweight discipline that fits agile teams
ADRs work because they don’t fight agile speed, they anchor it. Sprints move fast enough that decisions get made in Slack threads and forgotten by the next standup. The discipline of writing even a rough ADR forces someone to state the reasoning out loud, which catches bad assumptions before they become expensive. The trap is treating ADRs as bureaucratic overhead: the moment they require sign-off committees, teams stop writing them. Keep them short, keep them optional for trivial calls, and mandatory for the ones you’d hate to re-argue in six months.
Automate ADR Capture Without Adding Process Overhead
Writing ADRs consistently is less about willpower and more about capturing the decision the moment it happens, before context evaporates. Segua pulls that context straight from your meeting recordings and uploaded content, turning a design discussion into drafted documentation instead of a Slack thread nobody revisits. It also tracks contradictions and unanswered questions across your project, so a decision that quietly conflicts with an earlier one gets flagged instead of buried until it breaks something in production.
That traceability extends across Gantt charts, requirement specs, and project artifacts, which means an architectural decision made in one meeting stays linked to the tickets and documents it affects. If you’re weighing this against manually maintaining an ADR folder or relying on a notetaking tool that only transcribes, see how Segua compares to AI notetakers and project tools. Pro plans run $39 per month, and you can try a meeting for free to see how automated capture handles your next architecture discussion.
Sources
-
Maintain an architecture decision record (ADR) — Microsoft Learn
-
Architectural decision records process — AWS Prescriptive Guidance
FAQ
Can You Edit an Accepted ADR?
No. Once an ADR is accepted, leave it as is and write a new ADR that supersedes it, linking both records together to preserve the original reasoning.
Where Should ADRs Live in a Repository?
Store them as Markdown files under doc/adr or docs/architecture in the same repo as the code, so they’re versioned and easy to find alongside implementation.
How Many ADRs Should a Project Have?
There’s no fixed count. Write one for every architecturally significant decision, meaning anything touching structure, major non-functional requirements, or external dependencies, and skip routine implementation details.
What Fields Belong in an ADR?
At minimum: title, status, date, authors, context, decision, alternatives considered, consequences, and supersession links, plus a last verified date to catch drift.
Who Should Own an Architecture Decision Record?
Assign a named individual to each ADR at creation, and reassign ownership during offboarding so no decision is left without someone accountable for it.