I was building a small project with an AI coding agent when I realized my architecture documentation was failing both of us. The agent would start each session by reading through a growing pile of decision records, trying to reconstruct what was still true. I was doing the same thing every time I came back after a week away.
The documentation existed. Nobody was getting value from it.
ADRs Solve the Wrong Problem
Architecture Decision Records are append-only by convention. When a decision changes, you don't update the old record — you write a new one that supersedes it. This sounds principled. In practice, it means your docs/decisions/ directory grows forever and the only way to understand the current state of the architecture is to read 40 files and mentally diff them against each other.
The decisions that still matter? Maybe five of them. The other 35 are historical noise — half-abandoned ideas, constraints that evaporated when you switched libraries, debates that got resolved and then relitigated and then resolved again. Nobody reads them. I stopped reading them.
The directory becomes an archaeological site when what you actually needed was a sign on the door.
What You Actually Need Depends On What You're Doing
When do you actually reach for decision documentation?
When you're orienting to a project — coming back after two weeks, or handing context to someone else — you need the 5–10 decisions that explain why the code is shaped the way it is right now. Not the history. The current state.
When you're editing a specific file — you want the relevant context right there, not in a document you have to go find. If there's a non-obvious reason a function is structured a certain way, that reason belongs in a comment next to the function, not in a separate record you have to cross-reference.
When a decision changes — you want to update the record. Not append to it forever.
ADRs optimize for auditability at the expense of usability. That's the wrong tradeoff for a small team or a solo project.
Three Layers That Actually Work
DESIGN.md in the repo root. Three sections only: Architecture, Decisions, Constraints. Hard cap at 100 lines. When a decision changes, edit it in place. When the file fills up, curate — remove what's no longer load-bearing.
Here's what a few entries look like in practice:
## Decisions
- **Redis for score caching, not DB reads**: Scores change every 5 min via worker;
cache hit target is <50ms. DB fallback on miss.
- **Async SQLAlchemy throughout**: All DB access is async to avoid blocking the
event loop under concurrent probe runs. Do not add sync sessions.
- **No JWT / no OAuth**: API keys only. Email-verified at creation. Keeps auth
surface small and agent-friendly.
Each entry is one or two lines: the decision, and the reason it's still load-bearing. If you can't summarize it that briefly, it probably belongs in a comment in the code instead.
Inline comments. Local decision context belongs in the code, next to the thing it explains. # XXX: for non-obvious logic or important implementation notes. If a caching layer exists in a weird place, or a function is structured in a way that looks wrong but isn't — that reason lives in a comment, not in a document.
Git history. The actual audit trail. Commit messages explain why a change was made. git blame ties a decision to the exact code change that enacted it. The history is embedded in the thing it describes, not floating in a separate file that may or may not stay in sync.
The Cap Is the Whole Point
Without the 100-line limit, DESIGN.md becomes the same problem as an ADR directory, just collapsed into a single file. The cap is the forcing function. Every time the file gets full, you have to decide what's still worth front-and-centering versus what's just history. That act of deciding is where the value is. Accumulation is easy. Curation is the work.
What You're Giving Up
You can't reconstruct the full decision history from DESIGN.md alone. If you need to know exactly when a call was made and why, it won't be there.
But that's what git is for — and git is a better place for it. The history is tied to the actual code change, not a separate document written after the fact. git log -p tells you more about what happened and why than any ADR, as long as you write decent commit messages.
The Two-Minute Test
Here's what crystallized this for me: Claude Code reads DESIGN.md at the start of every session to orient itself before touching any code. An AI agent needs to understand the shape of a project fast, or it makes wrong turns. So does a human coming back after a week away. So does a new hire on day one.
If someone can read DESIGN.md and understand why the code is shaped the way it is in two minutes — not the history, not every tradeoff ever considered, just the decisions that still govern the code today — you've won.
That's the test. A directory full of ADRs rarely passes it.
TL;DR
- ADR directories are append-only and grow forever; after a year you're reading 40 files to find the 5 decisions that still matter.
-
DESIGN.mdwith a 100-line hard cap keeps only what's currently true — when it fills up, you're forced to decide what to keep. - Git history is your audit trail; it's already tied to the code, which is where it belongs.
Top comments (0)