A Revival of ADRs
Ironically, AI coding tools have made traditional ADRs popular again.
I’ve always been a big fan of Architecture Decision Records (ADRs). For me, they’re the only form of living documentation that doesn’t become obsolete over time (partly because of their timestamps and append-only nature). They have saved me hours of repetitive discussions and freed up plenty of memory cells in my brain.
The challenge lies in choosing the right level of granularity when writing ADRs. Records that are too fine-grained quickly become messy, while overly broad ones are less useful. It takes some practice and discipline, but it’s totally worth it. If you haven’t started yet, begin writing ADRs today!
AI is Actually Reviving ADRs
As old-school and boring as ADRs might sound today, they are making a comeback thanks to the hottest trend in tech—AI-assisted and agentic coding. They are no longer just an input for human team members; they also serve as a communication protocol for artificial ones—AI assistants and agents.
With an ADR document at hand, you can easily convert it into formats like AGENTS.md, .cursorrules, or AI.md (whatever your AI tool uses). This saves you from defining rules from scratch and helps enforce clear constraints on the AI, reducing hallucinations and ensuring consistency across the codebase.
Good ideas don’t die easily, no matter how old they are. If you’ve stuck with ADRs this whole time, you’re about to reap the rewards.