Architecture Decision Records (ADRs) are great. At 10 decisions, they're manageable. At 50, they're still useful. At 500+, they become a different problem entirely.
You don't need better documentation. You need better architecture for your documentation.
The Scaling Problem
ADRs follow a simple pattern: record the decision, the context, the consequences, and the alternatives. It works beautifully when you can keep all decisions in your head.
But organizations don't stay small.
- You can remember them all
- Finding one takes seconds
- Relationships are obvious
- You remember the important ones
- Finding one takes minutes
- Some relationships are unclear
- No one knows them all
- Finding the right one is hard
- Relationships are invisible
- Contradictions accumulate
What Breaks First
Discovery
"We must have decided this before... where is it?"
- Good titles (not 'Decision about the thing')
- Useful metadata (team, domain, date, status)
- Semantic understanding (finding related concepts)
Relationships
Decisions don't exist in isolation.
- What would break if you changed something
- Which decisions are foundational vs. derivative
- Where contradictions exist
Currency
Old decisions don't disappear. They accumulate.
- Outdated decisions that mislead
- Valid decisions that no one trusts
- Endless 'should we update the ADR?' discussions
Governance
At scale, decisions come from everywhere.
- The same decision gets made multiple ways
- Best practices don't propagate
- Inconsistency compounds
The Graph Solution
The fundamental problem: ADRs are documents. Organizations need systems.
Documents
Systems
Move from documents to nodes in a graph
- Each decision is a node
- Relationships are edges (depends on, conflicts with, supersedes)
- Metadata enables filtering and navigation
- Visualization shows structure
Metadata That Matters
At scale, metadata is how you find and filter decisions. Essential fields:
| Field | Purpose |
|---|---|
| Status | Draft, Active, Deprecated, Superseded |
| Domain | Auth, Data, API, Infrastructure |
| Scope | Team, Department, Organization |
| Impact | Low, Medium, High, Critical |
| Review Date | When to reconsider |
| Owner | Who maintains |
Good metadata enables:
- "Show me all active data decisions"
- "What high-impact decisions were made this quarter?"
- "Which decisions need review?"
The Relationship Types
Explicit relationships transform flat documents into navigable systems:
Depends On
"Decision A requires Decision B to be true."
- Breaking B might break A
- Implementing A requires B first
Conflicts With
"Decision A and Decision B cannot both be true."
- Contradictions become visible
- Resolution is required
Supersedes
"Decision A replaces Decision B."
- Old decisions remain for history
- New decisions become authoritative
Related To
"Decision A is relevant context for Decision B."
- Loose coupling
- Discovery enhancement
Lifecycle Management
Decisions age. Lifecycle states capture this:
Draft
- Under discussion
- Not yet authoritative
- May change
Proposed
- Ready for approval
- Seeking stakeholder input
- Timeboxed discussion
Active
- Authoritative
- Should be followed
- May have dependencies
Deprecated
- No longer recommended
- Existing uses tolerated
- New uses prohibited
Superseded
- Replaced by another
- Historical record only
- Points to replacement
The Review Cycle
Decisions don't stay valid forever. Build a review practice:
Triggered Reviews
- When dependencies change
- When constraints change
- When technology landscape shifts
Scheduled Reviews
- High-impact decisionsquarterly
- Medium-impactsemi-annually
- Low-impactannually
Governance Without Bureaucracy
At scale, you need governance. But heavyweight governance kills agility.
Lightweight Governance Model
Most decisions are team-local. Only escalate when necessary.
The Tooling Gap
Most ADR tooling: markdown files in a repo
At scale, you need purpose-built tooling or significant process overhead.
Visualization Matters
You can't understand 500 decisions from a list. You need views:
Graph View
- Decisions as nodes
- Relationships as edges
- Clusters by domain
Timeline View
- Decisions over time
- Evolution of architecture
- Drift detection
Impact View
- Dependencies downstream
- What would break
- Risk assessment
Dashboard View
- Decisions by status
- Review queue
- Health metrics
Getting There From Here
If you have 500 unstructured ADRs:
Triage
2-4 weeks- Categorize by status (active vs. dead)
- Identify high-impact decisions
- Tag by domain
Relationships
4-8 weeks- Map dependencies for critical decisions
- Identify obvious conflicts
- Link supersession chains
Governance
ongoing- Define decision types and processes
- Assign owners
- Establish review cycles
ADRs at scale require treating decisions as nodes in a graph, not files in a folder.
Build the system, and the documentation becomes navigable.