ADRs give AI agents the history your code can't tell
Are you already using ADRs (Architecture Decision Records)?
If not, you’re missing out on a big quality boost for your AI agents.
Why? Because to work well, an AI agent needs to know how you want things done.
What the existing docs already tell
If things are going well, a good chunk of that knowledge is already in the repo: that’s the existing state.
You find it in:
But all of that only tells the current state of things. That’s already great, but it’s missing: why it’s like this, why it isn’t some other way, the tradeoffs accepted along the way (there are always some).
In the end, what’s missing is the history that led to this state.
The role of ADRs
That’s exactly what ADRs are for.
The concept is dead simple: as soon as a decision is made and its “why” needs to be kept on record, it goes into a file at docs/adr/001-best-decision-ever.md, with the date, the context, the choice, the alternatives ruled out… and so on.
Useful for humans, essential for agents
For an AI, reading these files is instant. And it lets it understand the why behind the how, instead of revisiting a decision made three months earlier, like a goldfish in its bowl.
And that, among plenty of other things, contributes to a solid AI harness.
ADRs are part of the harness I set up on my clients’ projects.
Don’t bury them in a wiki
PS: whatever you do, don’t go bury these files in a Notion nobody wants anymore, except the CEOs who heard back in 2019 that it was a must-have.
ADRs have to live as close as possible to the code they document: in the repo!
Happy designing!