# Adr

> Record significant project decisions as Architecture Decision Records (ADRs). Use whenever a decision would be expensive to reverse or important to remember — choosing a library/framework/database, an API or schema shape, an architectural pattern, a security or auth approach, a build/deploy choice, or dropping/replacing a technology. Also use when the user says "ADR", "record this decision", or "why did we choose X". Captures date, deciders, context, the decision, and consequences.

- Skill: `soukupl/adr` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add soukupl/adr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/soukupl/adr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: soukupl (https://skillmd.com/u/soukupl)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/soukupl/adr

---


# Architecture Decision Records (ADRs)

Significant decisions get written down at the project level, with **date and who decided**, so the
reasoning survives the people and the calendar. This is mandatory for big decisions — see the trigger
list below — not optional.

## What counts as "big" (write an ADR)

- Choosing/replacing/dropping a library, framework, database, or major dependency.
- API contract, data schema, or public interface shape.
- An architectural pattern or boundary (how modules/services are split, sync vs async, etc.).
- Security, auth, privacy, or compliance approach.
- Build, packaging, hosting, or deployment strategy.
- Any decision that is costly to reverse or that a future maintainer will ask "why?" about.

Small, easily-reversed choices do **not** need an ADR — keep them in code review or project memory.
When unsure whether a decision is big enough, ask the user briefly rather than skipping it.

## Where they live

`docs/adr/NNNN-kebab-title.md` at the repo root (create `docs/adr/` if missing). Four-digit
sequential number, starting at `0001`. Keep `docs/adr/README.md` as an index (a one-line link per
ADR); add the new entry when you create one.

## Creating an ADR

1. Find the next number: highest existing `NNNN` in `docs/adr/` + 1 (start at `0001`).
2. Copy `template.md` (next to this SKILL.md) to `docs/adr/NNNN-<short-kebab-title>.md`.
3. Fill every field:
   - **Date** — today's actual date, `YYYY-MM-DD`. Never guess it.
   - **Deciders** — who actually made the call. Ask the user who to credit if unclear; you may seed
     it from `git config user.name` / the user's identity, but don't invent names. List everyone
     involved, not just the author.
   - **Status** — `Proposed` until agreed, then `Accepted`. Later ADRs may set an old one to
     `Superseded by ADR-NNNN` (never delete or rewrite a decided ADR — supersede it).
   - **Context**, **Decision**, **Consequences**, **Alternatives considered** — see the template.
4. Add the one-line entry to `docs/adr/README.md`.
5. Keep it short: half a page. The value is the *why* and the *trade-offs*, not prose volume.

## Relationship to other skills

- `keep-architecture` links to ADRs for the "why" behind the structure — cross-reference them.
- A one-line pointer in project memory ("Decisions") is fine, but the ADR is the source of truth.