An architecture decision record answers the most expensive question a codebase ever asks: "why is it built this way?" The practice is sound — a small, dated record of the context, the call, and the consequences. The trouble is the substrate. An ADR is a markdown file checked into the repo, written the day the decision is made and never opened again. The code evolves, the decision quietly stops matching reality, and the ADR becomes archaeology. Draftlize keeps the record itself — but makes it something an AI coding agent reads before it touches the code, and one that flips to drift_detected the moment the decision it documents no longer holds.
An ADR in docs/adr/0007-use-event-sourcing.md is correct on the day you commit it and slowly diverges from the running system after that. The fix isn't a stricter review checklist — it's a substrate that knows which records still match the code and tells you when one doesn't.
| Draftlize | Markdown ADR in the repo | |
|---|---|---|
| The record itself | Typed card: context, decision, consequences, dependencies | A markdown template, filled by hand |
| Status field | Live — flips to drift_detected on its own | Hand-edited; usually still says "Accepted" |
| Decision changes — does the code know? | Dependent records flag drift automatically | No link; the file lies until someone notices |
| Can a coding agent use it? | Native read + write via MCP | Reads flat text if you point it there |
| Read before the code changes | The agent pulls the relevant ADRs first | Nobody opens docs/adr/ |
| Who keeps it honest | The substrate tracks it | A review checklist nobody enforces |
Michael Nygard proposed the architecture decision record in 2011 to capture why — the context and the trade-offs behind a structural call. The format is right. But an ADR is filed in docs/adr/ and the audience is a future engineer who never opens the folder. A record nobody reads back can't do the one job it has.
ADR-0007 says "we use event sourcing for the ledger." Eighteen months later half the ledger is CRUD again, decided in three pull requests and a Slack thread. The status still reads Accepted. The record now actively misleads the next person who trusts it — which is worse than no record at all.
Updating an ADR is a manual chore that competes with merging the PR, and the PR always wins. So the records freeze at the moment of writing while the system keeps moving, and the gap between docs/adr/ and main widens every sprint.
A standard ADR has five fields. Draftlize keeps all five — and turns the one that always lies, Status, into something the substrate maintains instead of something you forget to edit.
A short, addressable name. In Draftlize it's a card with a stable ID, citable as "per ADR-0007" from a spec, a thread, or an agent — a real link, not a filename you have to grep for.
In markdown, Status is hand-edited and stays Accepted forever. In Draftlize it's live: when an upstream decision moves, the implementation flips itself to drift_detected, so the record tells the truth without anyone updating it.
The forces in play when the call was made. Linked to the decisions it depends on, so when one of those changes, this record knows its premises shifted.
What you chose and what you ruled out. The alternatives are part of the card — so six months later nobody re-litigates an option you already closed.
What follows from the decision, good and bad. The dependent cards that inherit those consequences are linked — and they flag drift when this record changes underneath them.
Claude Code or Cursor, connected over MCP, pulls the relevant records before touching a module — so the decision behind "we use event sourcing here" is in context at the exact moment it matters, not buried in a folder nobody opens. The reader who never came back is now the reader who never skips a card.
When the agent makes a structural call mid-task, it can record a new ADR as a card — title, context, decision, consequences — without leaving the work to open a markdown file. The record gets written because writing it is one tool call, not a context switch.
Each record carries explicit dependencies. Change an upstream decision and every record built on it flips to drift_detected — the same way a build system invalidates everything downstream of a changed file. The gap between the decision and the code stops being something you discover in a post-mortem.
The ADR practice was never the problem. The problem is a record that can't tell when it's already wrong.Keep the five fields. Move them onto a substrate that maintains the one that lies.
An ADR is a short, dated record of one significant architectural decision — the context, the call, and the consequences. The practice was proposed by Michael Nygard in 2011 to capture why a system is built the way it is, so future engineers do not have to reverse-engineer the reasoning from the code.
Five fields: title, status, context, decision, and consequences. Title names the call, status tracks whether it is proposed, accepted, or superseded, context records the forces in play, decision states what was chosen and rejected, and consequences captures what it commits you to.
Because they are static markdown checked into the repo, written once and rarely reopened. As the code evolves the decision quietly stops matching reality, but the status field still reads "Accepted" — so the record actively misleads the next person who trusts it, which is worse than no record at all.
Draftlize keeps the same five fields but makes the record a card an AI coding agent reads before it touches the code and writes back when it makes a call. When an upstream decision moves, the implementation status flips itself to drift_detected — so the one field that always lies, status, stays honest without anyone editing it.
Spin up a project, port your existing ADRs in as cards, and connect your coding agent over MCP — so the records get read before the code changes, and flag drift the moment a decision moves.
Start free with $5One click creates a project with these exact sections as typed, linked cards. Answer them with the agent — and when a decision changes later, every dependent section flags stale instead of silently drifting. $5 free credit on signup, no card required.