# Architecture Decision Records

Writes, names and places ADRs with context, decision and consequences.

- Repository: https://github.com/architecture-decision-record/architecture-decision-record (17377 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-10-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add architecture-decision-record/architecture-decision-record --skill architecture-decision-record-skill -g -a claude-code -y`
Codex: `npx skills add architecture-decision-record/architecture-decision-record --skill architecture-decision-record-skill -g -a codex -y`
Cursor: `npx skills add architecture-decision-record/architecture-decision-record --skill architecture-decision-record-skill -g -a cursor -y`
Gemini CLI: `npx skills add architecture-decision-record/architecture-decision-record --skill architecture-decision-record-skill -g -a gemini-cli -y`

## Description

Use when a user wants to create, write, name, place, or organize an Architecture Decision Record (ADR) in a software project, e.g. "write an ADR for choosing a database", "document this architecture decision", "set up an adr/ or decisions/ directory", "which ADR template should I use", "supersede an old ADR". Covers picking a template, naming the file, filling in context/decision/consequences, and deciding whether a decision even needs an ADR.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Architecture decision record (ADR) skill

Helps a developer or team create and maintain architecture decision records:
short documents that capture an important architecture decision, the context
that led to it, and its consequences.

This skill is general-purpose: it applies to any repository the user is
working in, not just this one. `reference/templates.md` and
`reference/writing-guide.md` are self-contained, no need to read the rest of
this repo to use them.

## 1. Decide if this decision deserves an ADR

Not every decision needs one. Recommend an ADR when the decision:

- Is architecturally significant (affects structure, external interfaces,
  quality attributes, or is expensive/risky to reverse).
- Needs to be understood by future developers who weren't in the room.
- Involved real trade-offs worth recording (not a one-line style choice
  already covered by a linter or style guide).

Skip an ADR when the decision is tiny, self-contained, single-developer,
already covered by policy/standards, or purely a temporary workaround/POC.

If the user is unsure, ask what the decision is and who needs to understand
"why" later, that usually settles it.

## 2. Find or create the ADR directory

Look for an existing convention first:

```sh
git ls-files | grep -iE '(^|/)(adr|adrs|decisions?)(/|$)'
```

- If one exists, follow its naming/format/numbering so far.
- If none exists, ask the user (or default to) a top-level `decisions/` or
  `adr/` directory. Some teams prefer `decisions/` because the word
  "architecture" and the abbreviation "ADR" put some contributors off,
  while "decisions" invites broader use (vendor, planning, scheduling
  decisions too).
- Some projects number files (`0001-choose-database.md`, adr-tools style);
  others don't. Match what's already there; otherwise unnumbered
  present-tense file names (see below) are simplest to start with.

## 3. Name the file

Convention used across this ecosystem:

The rest: https://github.com/architecture-decision-record/architecture-decision-record/blob/HEAD/skills/architecture-decision-record-skill/SKILL.md