Duncan Davidson Sets 1 Core Rule for ADRs in AGENTS.md Guidance

1 articles · Updated · O'Reilly Media · Oct 2

Davidson says coding agents should treat accepted Architectural Decision Records as binding current rules, while proposed ADRs are only context and superseded ones are historical.
In AGENTS.md guidance, he tells agents to stop and discuss conflicts between a task and an accepted ADR, then propose whether the task or the ADR should change.
The instructions aim to fix two recurring failures: agents rigidly enforcing obsolete decisions and bloating ADRs with amendment logs, repeated rules and excessive rationale.
His preferred format keeps ADRs succinct—one current text, a single Updated: date for substantive revisions, Superseded-On: for replaced records, and Git history as the changelog.
The broader point is that agents need durable project intent, not a full transcript of past debates, so each governing ADR should state only the decision in force today.