architecture-decision-record

Architecture Decision Record

Quick Start

Use this skill when a design conversation produces a decision that should be remembered by future readers.

When this toolkit is used as a submodule, do not write ADRs under toolkit/adr/. Run the command from the private repository root, or pass --output-root <private-repo-root>, so output goes to the consuming repository.

ADR filenames must use this format:

adr-<4-digits>-<slug>.md

Start at adr-0001. For new ADRs, inspect existing adr/adr-*.md files and any legacy adr/0001-*.md files, choose the next available 4-digit number, and preserve gaps unless the user explicitly asks to renumber.

python3 skills/architecture-decision-record/scripts/write-adr.py "Use Domain Events Between Ordering And Billing" \
  --status accepted \
  --summary "Billing outages must not stop customers from completing checkout." \
  --decision "Ordering and Billing will communicate through domain events instead of synchronous HTTP."

When running from a private lab repo that contains this toolkit as a submodule:

python3 toolkit/skills/architecture-decision-record/scripts/write-adr.py "Use Domain Events Between Ordering And Billing" \
  --status accepted \
  --summary "Billing outages must not stop customers from completing checkout." \
  --decision "Ordering and Billing will communicate through domain events instead of synchronous HTTP."

Each generated ADR is also added to adr/_adr-overview.md using a markdown table with name, status, description, and last_updated columns. Create _adr-overview.md when it does not exist. Keep rows sorted alphabetically by ADR title.

Status values use colored icons in the overview:

• proposed renders as 🟡 proposed
• accepted renders as 🟢 accepted
• deprecated renders as 🔴 deprecated
• superseded renders as ⚫ superseded

Create ADRs only when all three conditions are true:

1. The decision is hard to reverse.
2. The decision is surprising without context.
3. The decision is the result of a real trade-off.