Linking ADRs to Code
Bi-directional links between the decision record and the code that implements it.
Why
An ADR in docs/adr/ that nothing points to is an orphan; a code module with a non-obvious choice and no ADR link is a mystery. Bi-directional linking — the ADR mentions the file paths, and the code comments link back to the ADR number — means a reader can navigate from either direction. When an engineer opens a config file and sees '// see ADR-0012 for why ClickHouse here', they get the rationale in one click instead of reverse-engineering it from the code.
When
When the ADR is Accepted and the implementing code lands. Takes 2 min per link. Skip for decisions with no single clear code location.
How
1. In the ADR, add a "Implemented in" section listing the key file paths 2. In each key file, add a header comment: "// ADR-NNNN: <one-line decision summary>" 3. For config files (yaml/toml), use a comment field if the format supports it 4. Run a CI check that every ADR with an "Implemented in" section has the back-link present 5. When code is refactored/moved, update the ADR's file list in the same PR
Example
ADR-0012 "Implemented in":
- src/events/writer.ts
- infra/clickhouse/schema.sql
src/events/writer.ts:
// ADR-0012: event writes go to ClickHouse (supersedes Postgres ADR-0007)
export class EventWriter { ... }Common Problems
- ⚠Adding the back-link comment but forgetting to update it when the ADR is superseded — stale links are worse than no links.
Best Practices
- ✓Automate the bi-directional check in CI so a moved file fails the build until the ADR is updated.
- ✓Keep the code comment to one line; the full reasoning lives in the ADR, the comment is just a signpost.