If the code tells the story, you don't need an ADR
22 Nov 20264 min read
An ADR (architecture decision record) is a small markdown file that says what you decided and why. I think on a small project of my own they're mostly not worth it. The code and the git history already tell the story.
This came from my feed reader, a .NET app built for myself. When I set it up I had an agent run one of Matt Pocock's skills, and by the end of the first night there were nine ADRs, from SQLite to deployment. The deployment one grew to 142 lines.
After that they sat in docs/adr, "on display" like the plans in The Hitchhiker's Guide to the Galaxy, in a locked filing cabinet behind a sign saying "Beware of the Leopard". I mostly never read them, but they were still basically driving decisions in the project. Five months later I deleted all nine in one commit.
They go stale when you move fast
When I'm moving fast I change the code and move on. Going back to update a markdown file is the first thing I skip, so they go stale pretty quickly.
Mine even disagreed with each other. ADR 0003 said the UI was Razor Pages, and ADR 0006 said Razor Slices had replaced them. If you only read 0003, and an agent might, you'd get the wrong idea about the code.
The code is always right about what the app does
It's the thing that actually runs, so it can't be out of date. Commit messages and PRs say when and why it changed, and they get written at the same time as the change, not months later.
In the year of our lord 2026, I can just ask an agent why the reader uses SQLite's WAL mode. It reads the history and gives me a better answer than a file I wrote in May. At least for me, a small little man doing whatever, that's enough.

I know commit messages have their own problem. But I have a short rule for how they should look, and the agents follow it every time, so the history doesn't end in "Haaaaaaaaands".
ADRs still help on a team
None of this is against ADRs, or Matt. His skill is actually careful about it. It says to only offer one when the decision is hard to reverse, would surprise someone later, and came from a real trade-off. Nine on the first night is probably on me, not the skill.
On a team I think they help for sure. Say someone is setting up a new project that's like one the company already has. They can read why the first one was built that way without having to ask around.
Write down what goes against AI defaults
This is the one I actually care about now. Agents kept bringing up stuff I'd already settled, like moving to Postgres. And every model I use writes scripts in Python unless you tell it not to, so if you want C#, that has to be written down somewhere.
But that doesn't need a whole file. Each decision got cut down to one line in AGENTS.md, the file agents read first:
## Decisions (do not re-litigate)
- SQLite: WAL mode, single file. Never propose Postgres.
- .NET 10 LTS: do not downgrade to .NET 8.mdIf an agent would get it wrong by default, it goes in there. Everything else is already in the code.