ADR — Architecture Decision Record

Capture the why behind architectural decisions so future-you (and future-agents) don't reverse them without context.

Step 1: Gather Context

Identify:

• What decision was made (or needs to be made)
• What alternatives were considered
• What constraints drove the choice
• What the consequences are

If the user hasn't specified, ask one question: "What decision are you documenting?"

Step 2: Check Existing ADRs

mkdir -p .devkit/docs/adr
ls .devkit/docs/adr/ 2>/dev/null | grep -oE '^[0-9]+' | sort -n | tail -1

Add 1 to the highest number found, zero-padded to 4 digits. If no output, the directory is empty — start at 0001.

Step 3: Write the ADR

Create .devkit/docs/adr/NNNN-short-title.md:

# NNNN. Short Decision Title

**Date:** YYYY-MM-DD
**Status:** accepted | proposed | deprecated | superseded by [NNNN]

## Context

What is the issue? What forces are at play? 2-4 sentences max.

## Decision

What did we decide? State it directly. 1-3 sentences.

## Alternatives Considered

- **Alternative A** — why rejected (1 line)
- **Alternative B** — why rejected (1 line)

## Consequences

What follows from this decision? Both positive and negative. Bullet list.

Rules

• Keep it short. An ADR is a reference, not an essay. Under 200 words total.
• One decision per ADR. If there are two decisions, write two ADRs.
• Use plain language. No jargon that requires context to parse.
• Status is usually accepted. Use proposed only if the user hasn't decided yet.
• Never modify the substantive content of existing ADRs (Context, Decision, Alternatives, Consequences). When superseding, only update the old ADR's Status line to superseded by [MMMM].