Architecture decision records
Write ADRs as a durable record of why one architecturally significant choice
was made. Prefer a small factual record over a broad design guide.
Workflow
- Read repository instructions, existing ADRs, documentation tooling, and the
implementation affected by the decision.
- Decide whether the record is prospective or retrospective. Never present a
reconstructed decision as if it had been written when the choice was made.
- Identify one significant decision. Split independent, phased, or separately
reversible choices into separate records.
- Use the repository's established template. Without one, use Nygard's minimal
anatomy: status, context, decision, and consequences. Add alternatives when
they explain the choice; use MADR when option comparison needs more detail.
- For a retrospective ADR, inspect Git history first. Record relevant commit
hashes and dates, then verify every claim against current code, tests,
configuration, and authoritative platform documentation.
- Write context as forces and constraints, not a disguised solution. State the
decision assertively. Include material benefits, costs, risks, and limits.
- Use
Proposed, Accepted, Rejected, Deprecated, or Superseded by ADR-NNN. Preserve accepted and rejected records; supersede them with a new
ADR instead of rewriting history.
- Update the decision-log index and reciprocal supersession links. Render or
lint the documentation using the repository's native toolchain.
- Run the bundled validator and report unresolved evidence gaps honestly.
Quality rules
- Use monotonic identifiers and never reuse a removed number.
- Keep one decision per record and make the title describe that decision.
- Separate observed facts, the selected decision, and expected consequences.
- Include credible alternatives; do not create straw-man options.
- Do not assign net scores or weights unless the ADR defines a scoring model
and cites the measurements behind it.
- Distinguish verified history from inference and current policy from past fact.
- Keep secrets, personal data, and internal credentials out of evidence.
- Keep the record concise, standalone, linkable, and reviewable in a code diff.
Validation
python3 skills/architecture-decision-records/scripts/validate_adrs.py docs/adr \
--git-repo . --require-history
Omit --require-history for prospective records. Add the repository's own
renderer, link checker, or Markdown/ReST linter after this structural check.
Resources
- Read references/best-practices.md for the
standards landscape, lifecycle, evidence method, and review rubric.
- Copy assets/adr-template.md for Markdown projects.
- Copy assets/AdrTemplate.rst for TYPO3 or other ReST
documentation projects.
1---2name: architecture-decision-records3description: Creates and reviews architecture decision records (ADRs), decision logs, and supersession histories using established conventions and verifiable evidence. Use when users ask to write, reconstruct, audit, standardize, validate, or maintain ADRs, architecture decisions, decision logs, or ADR templates in Markdown or reStructuredText.4---56# Architecture decision records78Write ADRs as a durable record of why one architecturally significant choice9was made. Prefer a small factual record over a broad design guide.1011## Workflow12131. Read repository instructions, existing ADRs, documentation tooling, and the14 implementation affected by the decision.152. Decide whether the record is prospective or retrospective. Never present a16 reconstructed decision as if it had been written when the choice was made.173. Identify one significant decision. Split independent, phased, or separately18 reversible choices into separate records.194. Use the repository's established template. Without one, use Nygard's minimal20 anatomy: status, context, decision, and consequences. Add alternatives when21 they explain the choice; use MADR when option comparison needs more detail.225. For a retrospective ADR, inspect Git history first. Record relevant commit23 hashes and dates, then verify every claim against current code, tests,24 configuration, and authoritative platform documentation.256. Write context as forces and constraints, not a disguised solution. State the26 decision assertively. Include material benefits, costs, risks, and limits.277. Use `Proposed`, `Accepted`, `Rejected`, `Deprecated`, or `Superseded by28 ADR-NNN`. Preserve accepted and rejected records; supersede them with a new29 ADR instead of rewriting history.308. Update the decision-log index and reciprocal supersession links. Render or31 lint the documentation using the repository's native toolchain.329. Run the bundled validator and report unresolved evidence gaps honestly.3334## Quality rules3536- Use monotonic identifiers and never reuse a removed number.37- Keep one decision per record and make the title describe that decision.38- Separate observed facts, the selected decision, and expected consequences.39- Include credible alternatives; do not create straw-man options.40- Do not assign net scores or weights unless the ADR defines a scoring model41 and cites the measurements behind it.42- Distinguish verified history from inference and current policy from past fact.43- Keep secrets, personal data, and internal credentials out of evidence.44- Keep the record concise, standalone, linkable, and reviewable in a code diff.4546## Validation4748```bash49python3 skills/architecture-decision-records/scripts/validate_adrs.py docs/adr \50 --git-repo . --require-history51```5253Omit `--require-history` for prospective records. Add the repository's own54renderer, link checker, or Markdown/ReST linter after this structural check.5556## Resources5758- Read [references/best-practices.md](references/best-practices.md) for the59 standards landscape, lifecycle, evidence method, and review rubric.60- Copy [assets/adr-template.md](assets/adr-template.md) for Markdown projects.61- Copy [assets/AdrTemplate.rst](assets/AdrTemplate.rst) for TYPO3 or other ReST62 documentation projects.
dirnbauer