Architecture Decision Records
Writes, names and places ADRs with context, decision and consequences.
Install
npx skills add architecture-decision-record/architecture-decision-record --skill architecture-decision-record-skill -g -a claude-code -y- Repository
- architecture-decision-record/architecture-decision-record17.4k
- Category
- Engineering
- Updated
- 6d ago
- License
- See repository
- Context cost
- Lightabout 1,352 tokens
- Runs scripts
- No, instructions only
What it does
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.
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:
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/oradr/directory. Some teams preferdecisions/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:
