Architecture Decision Records with Code References - Holding Architects Accountable
Architecture Decision Records with Code References
Architecture Decision Records (ADRs) are supposed to capture why a system is built a certain way. In practice, most ADRs are written once, never updated, and describe a system that no longer exists. The fix is simple: every ADR must reference the actual code that implements it.
The Problem with Abstract ADRs
A typical ADR says something like "We will use event sourcing for the order service because it provides better auditability." That sounds reasonable. But six months later, someone has replaced event sourcing with a simple CRUD pattern because it was too complex, and the ADR still claims the system uses event sourcing.
Nobody updated the document because nobody checks it. The ADR became fiction.
Code References Create Accountability
An ADR with code references looks different:
- Decision: Use event sourcing for order state management
- Implementation:
src/orders/event-store.ts(lines 12-85),src/orders/projections/directory - Test coverage:
tests/orders/event-store.test.ts - Last verified: 2026-03-15
Now the ADR is verifiable. Anyone can check whether those files still exist and still implement event sourcing. An AI agent can even automate this verification - scan the referenced files and flag ADRs whose code no longer matches the described pattern.
Architects Who Cannot Do Architecture
There is a related problem: architects who design systems on whiteboards but never verify their designs against reality. Code-referenced ADRs expose this gap immediately.
If the architect says "use CQRS" but the referenced code shows a standard MVC pattern, the disconnect is visible. The ADR becomes a tool for honest conversation rather than hand-waving.
Making It Practical
Keep ADRs in the same repository as the code they describe. Use a simple template:
- Context - What problem are we solving
- Decision - What we chose and why
- Code references - Specific files, functions, and line ranges
- Consequences - What this enables and constrains
- Verification date - When someone last confirmed the code matches
Run a monthly check - manually or with an AI agent - that walks through each ADR and verifies the references still hold. Delete or update ADRs that have drifted. This is documentation that earns its keep.
Fazm is an open source macOS AI agent. Open source on GitHub.