Adr

Architecture Decision Records

ADRs capture the why behind significant technical decisions so that future-you (or teammates) can understand the reasoning without re-deriving it.

When to record an ADR

Record one when:

• Choosing between real alternatives - at least two viable options existed and you picked one for reasons
• The decision is hard to reverse - switching later would cost significant effort
• Future-you would ask "why did we do this?" - the reasoning isn't obvious from the code
• Changing a previous decision - especially important to capture what changed and why

Don't record ADRs for: trivial choices (variable names, formatting), obvious decisions (use git for version control), or temporary experiments.

On project start

If docs/adr/ exists, skim the titles to understand past decisions. If you're about to recommend something that contradicts an existing ADR, flag it:

"Heads up: ADR 0003 chose X for Y reason. Are we revisiting that decision? If so I'll record a new ADR."

How to record

Step 1: Find or create the ADR directory

Look for existing ADRs in the project. Default location: docs/adr/. Create it if it doesn't exist.

Step 2: Determine the next number

Read existing ADR files to find the highest number, increment. Files follow this pattern:

NNNN-short-slug.md

Zero-padded to 4 digits. Start at 0001 if none exist. Slug should be lowercase, hyphen-separated, 3-6 words describing the decision.

Examples: 0001-use-postgres-over-dynamodb.md, 0002-monorepo-structure.md

Step 3: Write the ADR

# NNNN. Title of Decision

**Date**: YYYY-MM-DD

## Context

What is the situation? What problem are we solving? What constraints exist?
2-4 sentences. Enough background for someone unfamiliar to understand why
a decision was needed.

## Options Considered

- **Option A**: Brief description. Key trade-off.
- **Option B**: Brief description. Key trade-off.

## Decision

What did we decide and why? Be specific about the reasoning.
Reference concrete evidence (benchmarks, cost calculations,
compatibility requirements) when available.

## Consequences

- What becomes easier or possible
- What becomes harder or impossible
- What we'll need to watch out for
- Any follow-up work this creates

Writing rules

• Be concrete, not abstract. "Postgres handles our query patterns with 2ms p99 vs DynamoDB's 8ms" beats "the relational DB performed better."
• Capture reasoning, not just conclusion. The code shows what; the ADR captures why.
• Include numbers when you have them. Costs, latency, accuracy, memory usage.
• Keep it short. Half a page, not three pages. Link to detailed docs if needed.

Step 4: Summarize

After writing, tell the user:

• The file path
• A one-line summary of what was recorded
• Note it'll be committed with the next git commit

Proactive suggestions

When you notice a decision being made in conversation but the user hasn't asked for an ADR:

"This looks like a decision worth recording as an ADR. Want me to capture it in docs/adr/?"

One suggestion per decision. If they say no or ignore it, move on. Don't be pushy.