Architecture decision records for coding agents

What metadata makes an ADR usable during agent work?

An agent-readable ADR needs enough structure to answer applicability without reading every paragraph. Give it a stable ID, title, status, owner, scope, affected capabilities, retrieval terms, supersession links and enforcement references. Scope can include repositories, paths, languages, frameworks, environments and data classifications. Status should distinguish proposed, accepted, deprecated, superseded, retired and rejected records so semantic similarity cannot accidentally promote an obsolete idea.

The prose still matters. Context and consequences explain why the rule exists, rejected alternatives prevent the same debate from returning, and review dates make drift visible. Structured metadata should route the agent to the record; it should not flatten the rationale into an opaque policy blob.

• Use one stable ID across Markdown, commits, pull requests and checks.
• Keep rejected and superseded records discoverable but inactive by default.
• Name the owner and the group that can approve an exception.
• Describe what would change the decision, not only what is true today.

How should an ADR connect to an implementation check?

A decision should link to the smallest check that demonstrates its enforceable consequence. That might be an architecture test, dependency rule, Semgrep policy, API-contract check or infrastructure policy. The link should work in both directions: the record should show how it is verified, and a failure should name the record, affected file and approved remediation. This preserves the distinction between rationale and mechanism while making the relationship auditable.

When no objective check exists, say so. A reviewer can still require citation and approval for a judgement-based decision, but the system should not call that enforcement. Honest classification is more useful than a larger catalogue of checks that cannot prove the claim they advertise.

What does a machine-readable ADR look like?

The structured part of an ADR should be boring and predictable. A record might include `id`, `title`, `status`, `owners`, `scope`, `decision`, `agent_instructions`, `enforcement`, `supersedes` and `exceptions`. The Markdown remains the human review surface; front matter or a companion object gives tools reliable fields to index. Keep the schema extensible, but do not make every field mandatory when a team cannot provide truthful data.

A good record also makes uncertainty explicit. A proposed decision is discoverable as a proposal but excluded from active guidance. A superseded decision remains useful for history but cannot outrank its successor. An enforcement mapping can be present with a warning if the rule is disabled. These distinctions help an agent produce an honest plan and help a reviewer see where governance is incomplete.

id: ADR-0042
status: accepted
scope:
  paths:
    - services/orders/**
agent_instructions:
  required:
    - Cite ADR-0042 in the pull request
enforcement:
  - rule: policies/no-direct-publish.yml

How should an ADR be reviewed before an agent uses it?

Review an ADR as an operational interface, not only as prose. Confirm that the status, owner and scope are explicit; that the decision can be distinguished from a proposal or historical record; and that its instructions do not contradict a newer accepted decision. Try a representative retrieval query against a clean repository checkout. The result should identify the record, explain why it applies and point to the exact source revision.

Then review the consequence boundary. Mark which statements are guidance and which have a linked architecture test, policy or CI check. A reviewer should be able to tell what a passing check establishes and what remains a judgement call. If an exception is allowed, name the approver, evidence and expiry path before the first exception is needed. This keeps the ADR useful to both agents and people without promising more certainty than the record can provide.

• Status, owner and scope validated in CI.
• Retrieval fixture returns the accepted record and excludes stale alternatives.
• Guidance and machine-checkable consequences labelled separately.
• Exception approval and expiry rules recorded before adoption.

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.