An agent-readable architectural decision should combine human-readable rationale with machine-readable identity, lifecycle, ownership, scope, relationships, required behaviour and enforcement references. Keep the structured fields small and validated; preserve the full context, alternatives and consequences in readable prose reviewed through Git.
Structure the parts machines must resolve
Agents can read prose, but governance workflows need unambiguous fields for status, scope and relationships. A schema lets tools exclude superseded records, match repository paths and validate stable citations without asking a model to reinterpret every document.
Do not reduce the decision to metadata. Rationale, rejected alternatives and consequences remain essential for human judgement and for agents facing a case the schema did not anticipate.
A practical decision shape
Use front matter or a structured companion file if decisions live as Markdown. Validate identifiers and enums in CI, and treat changes to scope or status as reviewable architectural changes.
---
id: ADR-0042
status: accepted
owners: [platform-architecture]
scope:
paths: ["src/events/**"]
capabilities: [domain-event-publication]
requires:
- use the transactional outbox
prohibits:
- direct broker publication
enforcement:
- policies/adr-0042.yml
supersedes: []
---Separate instructions from enforceable claims
A required behaviour can guide an agent even when no deterministic check exists. Mark enforcement references explicitly rather than implying that every sentence is machine-enforced. Each rule should state its engine, scope and failure meaning.
Keep agent instructions concise and derive them from the accepted record. Duplicated prompt files should point back to the stable decision ID so later updates do not leave conflicting versions of authority.
Validate lifecycle and relationships
Stable IDs, accepted statuses and valid links matter more than a large field catalogue. Check that supersession targets exist, prevent mutually active replacements, and retain rejected or retired records for historical discovery. Schema evolution should remain backwards compatible or provide an explicit migration.
- Required: ID, title, status, date and decision prose.
- Recommended: owners, scope, consequences and relationships.
- Optional: agent instructions, enforcement references and evidence requirements.