Full ADRs: context, options, consequences, detailed reasoning. 30 minutes to write well.
Decision frequency in AI development: multiple per hour.
The math doesn't work.
Here's what does: the 30-second decision record.
The Format
**What:** [The decision, one sentence] **Why:** [The reasoning, one sentence] **Owner:** [@person] **Date:** [Today]
That's it. Four fields. 30 seconds to fill out.
Example: What: Use PostgreSQL for primary database Why: Team familiarity, JSON support, proven at scale Owner: @mike Date: 2025-12-24
Why This Works
**Low friction.** 30 seconds doesn't compete with "real work." You'll actually do it.
**Captures the minimum.** What and why — the essentials someone needs to understand the decision.
**Creates accountability.** Owner field means someone can answer questions later.
**Enables retrieval.** Dates make it findable. Searchable format enables discovery.
**Scales.** You can capture many decisions this way. Full ADRs only work for a few.
When to Use Each
**30-second record:** Most decisions. The default.
**Full ADR:** Major decisions. Hard to reverse. Significant risk. Worth the investment.
The ratio might be 20:1. Twenty quick records for every full ADR.
That's fine. Most decisions don't need full treatment. All decisions need some record.
Making It Automatic
Build the trigger:
- Made a decision? → 30 seconds, write it down
- Moving to next task? → Did I record what I just decided?
- End of day? → Scan for undocumented decisions
The habit matters more than the format. Any format you'll actually use beats a perfect format you won't use.
The Compound Effect
Day 1: A few decision records. Not that useful yet.
Month 3: Dozens of records. Pattern starts to emerge. You can see how decisions connect.
Month 12: Hundreds of records. Searchable history. "When did we decide X? Why?" — answered instantly.
The value compounds. Early records feel like overhead. Later records are treasure.
Start now. 30 seconds at a time.