# Adr

> Record Architecture Decision Records (ADRs) when significant technical decisions are made. MUST trigger when switching, migrating, or replacing libraries, SDKs, frameworks, databases, or infrastructure. MUST trigger when making decisions that shape how the system works going forward: deployment strategies, service boundaries, data flow patterns, auth models, API design. Also trigger when choosing between alternatives, making trade-offs, or changing a previous approach. Common signals: "let's go with X", "we should use Y", "I've decided to", "switching from X to Y", "the trade-off is", "pros and cons of", "why did we choose X?", or "document this decision". Even if the user doesn't say "ADR", if a decision is being made that future-them would want to remember the reasoning for, this skill applies. Record the ADR proactively, don't wait to be asked.

- Skill: `jessedegans/adr` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jessedegans/adr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jessedegans/adr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: jessedegans (https://skillmd.com/u/jessedegans)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jessedegans/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

```markdown
# 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.