Architecture decision records

Purpose

Code tells you how a system works. ADRs tell you why it works that way, preventing future maintainers (and AI agents) from suggesting "improvements" that were already tried and discarded.

When to Use

• Finalizing a major design decision (e.g., "Choosing Postgres over MongoDB", "Using custom event bus over Redis")
• Reversing or superseding a previous decision
• A reviewer or agent proposes a change that contradicts an existing constraint

Inputs

• The decision, the alternatives considered, and the constraints that drove it
• The ADR directory (conventionally docs/adr/)

Workflow

1. Check for an existing ADR first — the decision may already be recorded or superseded:

   ls docs/adr/                          # existing records
   rg -ln "<topic keyword>" docs/adr/    # is this decision already covered?
   

2. Create the record at docs/adr/YYYY-MM-DD-<short-title>.md — date-prefixed for ordering, kebab-case title.

3. Fill the structure — keep it under 300 words; focus on constraints, not theory:

   # <Decision title>
   
   ## Status
   Accepted | Superseded by <newer ADR filename>
   
   ## Context
   What is the problem? What constraints apply?
   
   ## Decision
   What are we doing?
   
   ## Consequences
   What trade-offs are we accepting? What becomes harder?
   

4. Handle supersession explicitly. When reversing a decision, do NOT edit history: write a new ADR, mark the old one "Superseded by" with a link to the new file, and state what changed.

5. Link from where the decision bites — a one-line pointer near the affected module or in the architecture doc, so the why is discoverable from the how.

Output

• A dated ADR file with Status / Context / Decision / Consequences
• Superseded ADRs updated with forward links — never deleted or rewritten

Verification

• File saved under docs/adr/ with a date-prefixed kebab-case name
• Status, Context, Decision, and Consequences sections all present; body under ~300 words
• Consequences state real trade-offs, not just benefits
• Superseded decisions marked and forward-linked, not edited or removed
• Decision discoverable from the affected code or architecture doc

Failure Modes

• Retroactive rewriting — editing an old ADR to match a new decision destroys the historical why; supersede instead.
• Theory essays — pages of architecture philosophy nobody reads; constraints fit in 300 words.
• Consequence-free records — a Decision without trade-offs is advocacy, not a record.
• Orphaned ADRs — records nobody can find from the code they govern.