Record architecture decisions
Context
We need to record the architectural decisions made on this project. Traditional documentation claims to always be current, creating maintenance burdens and unrealistic expectations.
Decision
We will use Architecture Decision Records, as described by Michael Nygard.
Why ADRs Work Better
ADRs capture why decisions were made at a specific time, not how to implement them. The reasoning usually outlasts the implementation. When decisions conflict or change, we can layer new ADRs on top rather than constantly updating old documentation.
ADRs also serve as context for AI coding agents. An agent can read the codebase to understand what code does, but not why one approach was chosen over alternatives. ADRs fill that gap — they're the cheapest way to transfer architectural judgment to something that rebuilds its context from scratch every session.
Documentation Guidelines
- Prefer ADRs for architectural decisions over detailed implementation guides
- Capture decisions, not implementations - code shows how things work
- Use clear status: Proposed → Accepted/Rejected → Superseded
- Focus on context and consequences that future developers need
What Needs an ADR
- Architectural patterns and technology choices
- Cross-cutting concerns like security or error handling
- Development methodology decisions
What Doesn't Need an ADR
- Implementation details visible in code
- Standard language idioms
- Simple tool choices that are easily changed
Consequences
Contributors understand the reasoning behind current architecture without maintaining complex documentation. Conflicting decisions tell the story of how the system evolved. Less pressure to keep everything current.
For tooling, see Nat Pryce's adr-tools.