AI coding agents should cite architectural decisions with a stable decision ID, the repository revision containing the record, its lifecycle status and the files or plan steps it influenced. Citations belong in the plan and pull request, should resolve to human-reviewed source material, and should be validated for existence, currency and applicability.
A citation is evidence of considered authority
A citation does not prove that the implementation is correct. It proves a narrower and still valuable fact: the agent or author identified a particular decision as relevant. Reviewers can then inspect the source, compare it with the patch and spot missing or misapplied constraints.
Free-form statements such as ‘followed the architecture docs’ are hard to audit. Stable IDs and repository revisions make the reference durable even when titles change or a later record supersedes the original.
What to include
Keep the machine-readable citation small enough to generate consistently while preserving enough context to validate it.
- Decision ID and canonical repository path or URI.
- Commit or version used during planning.
- Lifecycle status observed by the agent.
- Affected files, symbols or plan steps.
- A short applicability reason, not a rewritten version of the decision.
architecture_decisions:
- id: ADR-0042
revision: 8b91e2a
applies_to:
- src/events/publisher.ts
reason: event publication pathValidate citations in two directions
First validate declared citations: the record exists, was active at the stated revision and actually covers the cited scope. Then identify likely applicable decisions that were not cited. The second check may be advisory when applicability involves judgement, but it should still be visible to reviewers.
Do not let the agent cite a generated summary as the authority. A concise MCP response is useful context, but its citation should resolve to the underlying Git-reviewed decision.
Place citations where decisions are made
Cite decisions in the pre-implementation plan so conflicts appear before code generation. Repeat the final set in pull-request metadata because scope may change during implementation. Code comments should be reserved for constraints a future reader must understand locally; duplicating every citation throughout the source creates stale noise.