Architecture decision record

Writes a short, dated architecture decision record (ADR) with context, decision, options considered with trade-offs, consequences and status, stored next to the code. Use when a significant technical choice was made or is being made and should be recorded.

DocumentationPack: Documentation71 linesarchitecture-decision-record

Install

Run one command — it saves SKILL.md into your agent's skills folder. Restart the agent and the skill is picked up automatically.

Claude Code — macOS, Linux
mkdir -p ~/.claude/skills/architecture-decision-record && curl -fsSL https://anymodel.org/en/skills/docs/architecture-decision-record/SKILL.md -o ~/.claude/skills/architecture-decision-record/SKILL.md
Codex, Cursor — macOS, Linux
mkdir -p ~/.agents/skills/architecture-decision-record && curl -fsSL https://anymodel.org/en/skills/docs/architecture-decision-record/SKILL.md -o ~/.agents/skills/architecture-decision-record/SKILL.md
Claude Code — Windows PowerShell
New-Item -ItemType Directory -Force "$HOME\.claude\skills\architecture-decision-record" | Out-Null; Invoke-WebRequest https://anymodel.org/en/skills/docs/architecture-decision-record/SKILL.md -UseBasicParsing -OutFile "$HOME\.claude\skills\architecture-decision-record\SKILL.md"
Codex, Cursor — Windows PowerShell
New-Item -ItemType Directory -Force "$HOME\.agents\skills\architecture-decision-record" | Out-Null; Invoke-WebRequest https://anymodel.org/en/skills/docs/architecture-decision-record/SKILL.md -UseBasicParsing -OutFile "$HOME\.agents\skills\architecture-decision-record\SKILL.md"

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/docs/architecture-decision-record/SKILL.md

SKILL.md

Raw

Architecture Decision Record

An ADR explains why the code is the way it is, so a future reader does not have to guess or reverse the decision blindly. One decision per record. Short is a feature.

When to write one

Write an ADR when the choice is costly to reverse or will surprise a newcomer: a database, framework, queue, auth approach, API style, data model shape, build or deploy method, a deliberate rejection of the obvious option. Do not write one for routine implementation choices.

Workflow

  1. Find the existing convention. Look for docs/adr/, docs/decisions/, adr/, or files named like 0001-*.md. Follow its template, numbering and status vocabulary. If none exists, create docs/adr/ with 0001-<slug>.md and ask the user before introducing the folder.
  2. Gather the real context. Read the code and recent history related to the decision (git log on the files, issue or PR text if the user provides it). Ask the user for facts only they know: constraints, deadlines, team skills, budget, what was already tried. Do not invent the reasoning.
  3. List at least two real options, including "do nothing" or the status quo when it is genuine. For each, note honest advantages and drawbacks. Include the option that was rejected and the real reason.
  4. State the decision in one or two plain sentences in active voice: "We will use PostgreSQL for ...".
  5. Write consequences: what gets easier, what gets harder, new obligations (migrations, monitoring, training), and what would make us revisit the decision.
  6. Set the status and the date (today's date in YYYY-MM-DD). Link related ADRs.
  7. Keep it to about one page. Confirm facts with the user before finalizing, because an ADR with wrong rationale does lasting harm.

Template

# 0007. Use PostgreSQL for order storage

Date: 2026-03-14
Status: Accepted   (Proposed | Accepted | Deprecated | Superseded by 0012)

## Context
The situation and forces: requirements, constraints, scale, team skills, what
triggered the decision. Facts, not opinions.

## Decision
We will ...

## Options considered
1. PostgreSQL - relational, transactions, team knows it; needs a managed instance
2. SQLite - zero ops; single writer limits concurrent writes
3. Document store - flexible schema; weaker joins for reporting

## Consequences
- Good: ...
- Bad / costs: ...
- Revisit when: write volume exceeds ..., or the hosting plan changes.

Rules

  • Present tense for the decision, past tense for history. Write for someone reading in two years.
  • Do not rewrite accepted ADRs. If the decision changes, write a new ADR, mark the old one "Superseded by NNNN", and link both ways.
  • Record trade-offs honestly, including the downsides of the chosen option. Avoid selling it.
  • Numbers beat adjectives: "p95 under 200 ms at 50 requests per second" instead of "fast".
  • Do not include secrets, internal hostnames or personal data.
  • Store it in the repository next to the code it concerns, and commit it with or right after the change.

Pitfalls

  • Documenting a decision after the fact without telling the reader that it is retrospective; say so in the context.
  • A single option dressed up as a comparison. If there was no alternative, the decision may not need an ADR.
  • Mixing several decisions in one record.
  • Vague consequences such as "improves maintainability" with no concrete effect.
  • Leaving status as Proposed after the change shipped.

Report back

The path of the file written, the one-line decision, the options listed, and the facts you assumed that the user should confirm.

Source: AnyModel skills catalog · License: CC BY 4.0

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Documentation