ContextQMD
Back to Ai

ADR Conventions (Reference)

skills/adr-skill/references/adr-conventions.md

2.1.103.6 KB
Original Source

ADR Conventions (Reference)

Directory

If the repo already has an ADR directory, keep it.

If the repo has no ADR directory, choose based on project size:

  • docs/decisions/ — MADR default, recommended for projects with existing docs/ structure.
  • adr/ — simpler alternative for smaller repos.

Detection order (used by scripts): contributing/decisions/, docs/decisions/, adr/, docs/adr/, docs/adrs/, decisions/.

Filename Conventions

Pattern: YYYY-MM-DD-title-with-dashes.md

  • YYYY-MM-DD is the ADR creation date (matches the date frontmatter field).
  • Title uses lowercase, dashes, present-tense imperative verb phrase.
  • Examples: 2025-06-15-choose-database.md, 2025-07-01-adopt-adrs.md
  • Multiple ADRs on the same date are fine — the slug suffix disambiguates them.

If a repo already uses slug-only filenames (no date prefix), follow that convention.

Minimal Sections

At minimum, every ADR must clearly include:

  1. Context: why the decision exists now, what constraints/drivers apply.
  2. Decision: what is chosen.
  3. Consequences: what becomes easier/harder, risks, costs, follow-ups.

For agent-first ADRs, also ensure:

  • Constraints are explicit and measurable
  • Non-goals are stated
  • Follow-up tasks are identified

Status Values

Track status in YAML front matter:

yaml
---
status: proposed
date: 2025-06-15
decision-makers: Alice, Bob
---

Common statuses:

StatusMeaning
proposedUnder discussion, not yet decided
acceptedDecision is active and should be followed
rejectedConsidered but explicitly not adopted
deprecatedWas accepted but no longer applies — explain replacement path
superseded by [title](link)Replaced by a newer ADR — always link both ways

YAML Front Matter Fields

FieldRequiredDescription
statusYesCurrent lifecycle state
dateYesDate of last status change (YYYY-MM-DD)
decision-makersYesPeople who own the decision
consultedNoSubject-matter experts consulted (two-way communication)
informedNoStakeholders kept up-to-date (one-way communication)

The consulted and informed fields follow the RACI model and are useful for audit trails in larger teams.

Mutability

  • Prefer appending new information with a date stamp over rewriting existing content.
  • If a decision is replaced, create a new ADR and explicitly supersede the old one.
  • Status changes and after-action notes are fine to edit in-place.

Categories (Large Projects)

For repos accumulating many ADRs, use subdirectories:

contributing/decisions/   # or docs/decisions/
  backend/
    2025-06-15-use-postgres.md
  frontend/
    2025-06-20-use-react.md
  infrastructure/
    2025-07-01-use-terraform.md

Date prefixes are local to each category. Choose a categorization scheme early (by architectural layer, by domain, by team) and document it in the index.

Alternative: use tags or a flat structure with a searchable index. Subdirectories are simpler and work with all tools.