Introduction
Architecture Decision Records (ADRs) are short, structured documents that record key decisions made during the design or evolution of a software system. Introduced by Michael Nygard in 2011, they address a critical need: how do you justify and track architectural choices over time?
In a world of distributed teams and long-term projects, ADRs outshine static diagrams or Jira tickets. They capture the context, status, decisions, and consequences, making rationales accessible to everyone—juniors and seniors alike. Picture a new developer inheriting a monolith migrated to microservices: without ADRs, they're guessing; with them, they understand in 5 minutes why PostgreSQL was chosen over MongoDB.
Why adopt ADRs in 2026? Regulations like GDPR or SOC2 demand auditability, internal audits are routine, and CI/CD tools natively support docs (GitHub, GitLab). The payoff: 40% fewer recap meetings (per ThoughtWorks studies), faster onboarding, and resilient architecture despite turnover. This intermediate tutorial guides you step-by-step to implement them without burdening your workflows.
Prerequisites
- Intermediate knowledge of software architecture (patterns like MVC, microservices).
- Familiarity with Git and Markdown for version control.
- Experience with agile team management (Scrum/Kanban).
- Tools: Markdown editor (VS Code), Git repo (GitHub/GitLab).
What is an ADR? Theoretical Foundations
An ADR is a single Markdown file per decision, stored in a dedicated folder like docs/adr/. Unlike verbose wikis, it's immutable after publication: changes spawn a new ADR.
Analogy: Like a court ruling, it locks in the 'why now' without rewriting history. Standard statuses:
| Status | Meaning | Example |
|---|---|---|
| ------------ | ---------------------- | -------------------------- |
| Proposed | Under discussion | Migration to Kubernetes. |
| Accepted | Decision approved | Adopted by the team. |
| Deprecated | Replaced | By a v2. |
| Superseded | Overridden by another ADR. |
Key benefit: Git full-text search for 'Kubernetes' reveals the evolution of choices.
Standard ADR Structure
Use the MADR (Markdown ADR) template for consistency:
- Title: Sequentially numbered, e.g., "001-use-postgresql-for-user-data.md".
- Status: Proposed/Accepted/etc.
- Context: Business/technical problem (2-3 sentences).
- Decision: Chosen option + rejected alternatives.
- Consequences: Positive/negative impacts (perf, cost, complexity).
- Date: ISO 8601.
# 001 - Use PostgreSQL for User Data
## Status
Accepted
## Context
L'app gère 10k users/jour ; MongoDB scale mal en transactions ACID.
## Decision
Migrer vers PostgreSQL 15. Rejeté : Cassandra (trop complexe pour l'équipe).
## Consequences
+ ACID garanti, - Courbe d'apprentissage SQL.
Date: 2026-01-15
Case study: At Spotify, ADRs documented the shift to event sourcing, preventing regressions during refactors.
Creation Process and Workflow Integration
Step 1: Trigger. Any decision affecting architecture (DB, framework, infra) requires an ADR. Rule: if it impacts >2 devs, document it.
Step 2: Drafting. PM/Architect drafts using the GitHub template. Pull Request (PR) mandatory.
Step 3: Review. At least 2 reviewers (one tech, one product). Criteria: clarity, exhaustive alternatives.
Step 4: Merge & Numbering. Automated via GitHub Action (next number).
CI/CD Integration:
- Git hook: Validate template with
adr-tools(CLI). - Auto index:
adr index generatefor an overview.
GitHub Workflow Example:
git checkout -b adr/002-use-kafka.- Draft,
git commit -m 'adr: propose Kafka for events'. - PR → Merge → Status: Accepted.
Result: 100% traceable and searchable.
Advanced Management: Evolution and Maintenance
ADRs don't die: Supersede instead of deleting.
Complex Cases:
- Minor Changes: ADR #003-deprecate-jwt (references #001).
- Rollback: ADR #004-revert-to-rest (context: disappointing Kafka perf).
Advanced Tools:
- adr-tools: CLI for init/list/diff.
- GitHub Pages: Generate a static ADR site.
Health Metrics:
| Metric | Green Threshold | Action |
|---|---|---|
| -------------- | ----------------- | ----------- |
| ADRs/month | <5 | OK |
| % Accepted | >80% | Review OK |
| Avg Age | <2 years | Audit |
Netflix Case Study: 500+ ADRs track Chaos Engineering evolution, easing FedRAMP audits.
Essential Best Practices
- Keep it concise: Max 1 A4 page. Focus on facts, not opinions.
- Involve the team: Cross-functional reviews (devops, QA).
- Link to tickets:
[#JIRA-123]for traceability. - Automate: GitHub Action for numbering/status updates.
- Index: README.md with links + GitHub Wiki search.
Common Mistakes to Avoid
- Too verbose: Skip essays; list 2-3 alternatives max.
- No consequences: Without measurable impacts, ADRs lose value (e.g., +15% latency).
- Skipping review: Solo merges = bias; always use PRs.
- Deletion: Never delete; supersede for history.
Next Steps
- Read Michael Nygard's original manifesto.
- Install adr-tools for CLI.
- Explore the MADR template.
- Check out our Learni software architecture training for advanced patterns.