To make architecture decision records useful to coding agents, keep them in the repository, validate their structure and lifecycle, index the language developers use in tasks, return stable citations, and connect machine-checkable consequences to deterministic CI checks.
Traditional ADRs already solve the right human problem
An ADR captures a significant choice, its context, rationale and consequences. A collection forms a decision log. That is exactly the historical knowledge an agent lacks when it begins a fresh task.
The gap is operational. A directory of prose may be obvious to an architect and invisible to an agent working from a narrow prompt. The record needs a reliable discovery and lifecycle layer.
Add machine-readable consistency without losing Markdown
Retain readable Markdown as the reviewed artifact, then validate required fields, identifiers, statuses and relationships. Validation prevents a record from looking authoritative while omitting the decision or pointing to a nonexistent predecessor.
Typed metadata also lets tools filter accepted records, follow supersession and distinguish a requirement from an architectural choice without asking a model to infer document type.
Design discovery around questions
Titles and tags should include domain language that appears in implementation tasks. A record titled only 'ADR-014 persistence policy' is less discoverable than one that also names account deletion, restoration and retention. Related records let an agent move from the product rule to the affected architecture.
Do not convert every ADR into a gate
Many decisions are informative or judgement-based. Enforcement should be opt-in and explicit. Where a consequence can be checked objectively, attach a declared constraint and report exactly what the check covers. Where it cannot, retain the record as cited review context.