ADRs — Architecture Decision Records — emerged from good intentions:
"Significant decisions should be documented. Future developers should understand why we built things this way. Document the decision, the context, the alternatives, the consequences."
Great in theory. But ADRs were designed for a slower world.
The Mismatch
A proper ADR takes 30+ minutes to write well: - Context: What's the situation? - Decision: What did we decide? - Consequences: What follows from this? - Alternatives: What else was considered? - Status: Proposed/accepted/superseded
In AI-native development, significant decisions happen multiple times per day.
If each ADR takes 30 minutes, and you make 5 significant decisions per day, that's 2.5 hours of documentation. Per day. Per person.
Nobody does that. So nobody documents. The ADR format doesn't fit the pace.
What's Actually Needed
The value of an ADR is: - **What** was decided - **Why** it was decided - **Who** can answer questions
Everything else is nice to have, not need to have.
The 30-Second Decision Record
Strip it down:
**What:** [The decision, one sentence] **Why:** [The reasoning, one sentence] **Who:** [@person] **When:** [Date]
Example: What: Use PostgreSQL for primary database Why: Team familiarity + JSON support + proven scale Who: @mike When: 2025-11-20
That's 30 seconds to write. Captures the essentials. Scales to many decisions per day.
When to Use What
**30-second record:** Default. Most decisions. Quick to create, enough to be useful.
**Lightweight ADR:** Significant decisions with real trade-offs. Maybe 10-15 minutes. Context, decision, key alternatives.
**Full ADR:** Rare. Major, hard-to-reverse decisions with substantial consequences. Worth the investment.
The ratio might be 20:1:0.1. Twenty quick records, one lightweight ADR, rarely a full ADR.
The Format Evolution
ADRs weren't wrong. They were right for their time.
When significant decisions happened weekly, a 30-minute documentation investment made sense.
When decisions happen hourly, the investment needs to shrink proportionally.
Don't abandon decision documentation. Evolve the format to match the pace.
Making It Stick
The key is making it easy enough that people actually do it.
**Low friction:** Template ready. Quick to fill out.
**Part of workflow:** Decision made → record created. Automatic.
**Findable:** All records in one place. Searchable.
**Referenced:** Point to records when questions arise. Demonstrate value.
If documentation feels like overhead, it won't happen. If it's quick and useful, it becomes habit.
ADRs were built for a slower world. Build something lighter for this one.