Architecture Decision Records
A short, timestamped note that captures why a technical decision was made — before everyone forgets.
What it is
About Architecture Decision Records
Architecture Decision Records (ADRs) are short, version-controlled documents (usually plain Markdown files stored alongside code) that capture a single architectural decision, its context, the options considered and the consequences of the choice. Popularised by Michael Nygard's original blog post and format, they give teams an auditable history of why a system is built the way it is, preventing decisions from being silently relitigated or forgotten as teams change. They're typically stored in a repo's docs and adr folder and numbered sequentially.
What you can do with it
Capabilities
Document the context, decision and consequences of significant architecture choices
Maintain a chronological, version-controlled history of why a system evolved the way it did
Give new team members fast onboarding context on past technical decisions
Support decision review and reversal by making trade-offs and alternatives explicit
Integrate ADR files directly into a codebase's existing Git and PR review workflow
How to learn it
Learning Resources
Michael Nygard's original 'Documenting Architecture Decisions' blog post (the format's origin)
The open-source 'adr-tools' CLI and templates on GitHub
Joel Parker Henderson's ADR templates repository (widely used reference)
Practise by writing an ADR for a real decision on a current project, using a standard template (Context, Decision, Status, Consequences)
Pro Tip
Write the ADR at the time you make the decision, not months later — the value is capturing the alternatives you rejected and why, which is exactly the detail that gets forgotten first.
Skills that use this tool
Roles that use this tool