Skip to content

ADR-000: ADR Format Standard

Status: Accepted Date: 2026-01-19

Context

Architecture Decision Records help teams understand why past decisions were made. Without consistent formatting, ADRs become hard to scan, compare, and maintain. Some ADRs balloon into design documents with code examples and implementation checklists, while others lack essential sections like alternatives considered.

The team needs a standard format that keeps ADRs focused on the "why" while ensuring they remain concise and actionable.

Decision

All ADRs must follow this format:

  1. Maximum 100 lines - If longer, split into multiple ADRs or move details to issues
  2. One decision per ADR - Each ADR documents exactly one architectural choice
  3. Required sections:
  4. Context (2-3 paragraphs max)
  5. Decision (1-2 sentences)
  6. Consequences (positive and negative bullet lists)
  7. Alternatives Considered (1 sentence rejection reason each)
  8. Excluded content (belongs in issues or design docs):
  9. Code examples or API signatures
  10. Implementation checklists
  11. Test cases
  12. Phased rollout plans
  13. Detailed cost calculations
  14. Enforceable decisions - Write decisions that can be deterministically verified:
  15. Use explicit prose requirements ("must use X", "Y owns Z")
  16. Avoid vague language ("should", "ideally", "consider")
  17. Link to issues for implementation details and examples

Consequences

Positive: - ADRs are quick to read and compare - Reviewers can focus on architectural reasoning, not implementation details - Consistent structure makes it easy to find information

Negative: - Some decisions require linking to external design documents - Contributors must learn the format before writing ADRs

Alternatives Considered

Free-form documentation

Rejected because: Inconsistent formats make ADRs hard to scan and maintain over time.

Detailed design documents

Rejected because: Design docs focus on "how" rather than "why", and become stale after implementation.