Architecture Decision Records
Workflow Protocol
- Determine the next ADR number by scanning
docs/internal/adr/for existing ADRs. - Run the decision-ledger read gate before drafting:
/trace-history --risk High --last 20. Include relevant prior decisions, or state that no relevant high-risk prior decision was found. - Gather context by reading related code and existing ADRs.
- Guide the user through the decision by asking clarifying questions if the title alone is insufficient.
- Generate the ADR following the template below.
- Save the ADR to
docs/internal/adr/ADR-[NNN]-[slug].md. - Update the Index Table in
docs/technical/DECISIONS.md.
When to write an ADR vs skip
| Write ADR | Skip ADR |
|---|---|
| New framework/database adoption | Minor version upgrades |
| API design patterns | Bug fixes |
| Security architecture | Implementation details |
| Integration patterns | Routine maintenance |
ADR lifecycle
Proposed → Accepted → Deprecated → Superseded
↓
Rejected
Template (MADR format — use this)
# ADR-NNN: [Title]
## Status
Accepted | Proposed | Deprecated | Superseded by ADR-NNN
## Context
[Problem statement, current situation, constraints, scale]
## Prior Decision Check
[Result of `/trace-history --risk High --last 20`; cite relevant prior entries
or state "No relevant prior high-risk decisions found."]
## Decision Drivers
- [Must/Should/Could requirement]
## Considered Options
### Option 1: [Name] — [one-line summary]
Pros: ... | Cons: ...
### Option 2: [Name]
Pros: ... | Cons: ...
## Decision
We will use **[Option N]** because [key rationale].
## Consequences
**Positive:** ...
**Negative:** ...
**Risks:** ... Mitigation: ...
## Related ADRs
- ADR-NNN: [relationship]
Quick examples
Lightweight ADR (for clear-cut decisions):
# ADR-0012: Adopt TypeScript for Frontend
**Status**: Accepted | **Date**: 2024-01-15 | **Deciders**: @alice, @bob
## Context
50+ React components with prop-type-mismatch bugs. PropTypes are runtime-only.
## Decision
TypeScript for all new frontend code. Migrate incrementally with `allowJs: true`.
## Consequences
Good: Compile-time errors, better IDE support.
Bad: Learning curve, initial slowdown.
Y-Statement (for concise formal record):
In the context of **building a microservices architecture**,
facing **need for centralized auth and rate limiting**,
we decided for **Kong Gateway**
and against **AWS API Gateway and custom Nginx**,
to achieve **vendor independence and plugin extensibility**,
accepting **we manage Kong infrastructure ourselves**.
File structure
docs/internal/adr/
├── ADR-0001-use-postgresql.md
└── ADR-0003-mongodb-deprecated.md # [SUPERSEDED by ADR-0020]
Index table (maintain in docs/technical/DECISIONS.md)
| ADR | Title | Status | Date |
|---|---|---|---|
| 0001 | Use PostgreSQL | Accepted | 2024-01-10 |
| 0003 | MongoDB for profiles | Deprecated | 2023-06-15 |
Key rules
- Never modify accepted ADRs — write a new one to supersede
- Write early — before implementation starts, not after
- Max 1-2 pages — if longer, decision scope is too broad
- State real cons — an ADR without honest tradeoffs has no value
- Update status — mark deprecated when superseded; link the new ADR
Automation
# Custom repo path:
# 1. Create docs/internal/adr/ADR-[NNN]-[slug].md
# 2. Append one summary row and one summary entry to docs/technical/DECISIONS.md
# 3. Do not overwrite docs/technical/DECISIONS.md; it is append-only