In a piece republished from his blog with permission, Duncan Davidson argues that Architectural Decision Records (ADRs) are valuable for both human teams and coding agents. ADRs record significant design choices, their context, and the reasons behind them. Because agents often arrive with limited memory and only a narrow view of a codebase, ADRs let agents understand intent without having to excavate it from issue trackers, chat logs, or code archaeology.
Where ADRs can cause trouble
Davidson identifies two linked problems when agents rely on ADRs:
-
Agents can obey ADRs more rigidly than humans. He recounts an instance where an agent retained an outdated storage abstraction for a new feature simply because an ADR still described it as mandatory; rather than flagging the mismatch, the agent added another compatibility layer.
-
When agents are allowed to update ADRs, the opposite problem can emerge: preservation of deliberation. Clarifications and amendments accumulate, small implementation details get promoted into rules, cross-references are restated, and the prose becomes overlitigated and hard for humans to read.
Practical recommendations: brevity and explicit permissions
Davidson’s remedy is twofold:
-
Give agents explicit permission to question decisions that no longer fit the task, and monitor for signs they are overfitting to ADR text.
-
Keep ADRs succinct and human-readable; rely on Git for change history rather than maintaining amendment logs inside each ADR.
In his own projects he documents agent behavior in AGENTS.md. An excerpted set of conventions he uses includes:
- Store ADRs as Markdown files in docs/decisions. Treat accepted ADRs as binding; proposed ADRs are non-binding context; superseded ADRs are historical and do not govern current work.
- If a task conflicts with an accepted ADR, stop and discuss whether the task or the ADR should change, then propose the appropriate change. Propose new ADRs or updates when a change introduces or revises a durable product or architectural decision.
- Keep ADRs succinct: each ADR contains only its current text; Git history is the changelog, so do not keep amendment logs in ADR headers.
- When substantively changing an accepted ADR, add or update a single Updated: date line after Date:—its presence signals that history exists and Git has the details. A superseded ADR records a Superseded-On: date instead of Updated:, matching the Supersedes: line on the ADR that replaced it.
- State each rule once in the ADR that owns it and cross-reference it from other ADRs rather than restating it.
Adapt to your project
Davidson notes these instructions are evolving and different projects will need different conventions. Some teams will prefer immutable ADRs that are superseded rather than revised; in his projects he is comfortable letting Git carry the history. The essential principle is the same for all projects: each governing ADR should state the decision currently in force with enough rationale to apply it. An agent does not need the transcript of every argument—just the ruling that governs today and clear permission to stop when the ruling no longer fits.
Conclusion
ADRs provide durable context that benefits coding agents, but overly detailed or constantly amended records undermine readability and can lead agents to preserve obsolete rules. Keep ADRs clear and concise, document agent expectations (for example in AGENTS.md), and use Git as the changelog so agents and humans can work from the same, minimal set of governing rules.
