/adr: architecture decision record writer
A Claude Code slash command that writes a numbered Architecture Decision Record (context, decision, alternatives, consequences) in docs/adr, using the repository's code and your notes as evidence.
Skill in Engineering by AISkillHub Library
What it does
Decisions like "use Postgres row-level security for tenancy" or "move from REST polling to webhooks" are easy to make and hard to reconstruct a year later. `/adr` writes them down in a short, consistent format, based on the widely used Michael Nygard ADR structure with an added alternatives section.
**What it does** - Finds your ADR folder (`docs/adr`, `docs/decisions`, `adr`, `doc/adr`) or creates `docs/adr/`. - Picks the next number from existing files and creates `NNNN-kebab-title.md`. - Matches the format of existing ADRs if there are any; otherwise uses: Title, Status, Date, Context, Decision, Alternatives considered, Consequences. - Grounds the Context section in the code: it looks up the modules, configs or dependencies involved and references them by path. - Lists consequences in both directions: what gets easier and what gets harder or riskier. - When an ADR replaces an earlier one, it marks the old one "Superseded by ADR-NNNN" and links both ways. - Asks you for anything only a person knows: constraints, who decided, rejected options and why.
**What it will not do** It does not make the decision for you or present a proposal as accepted. New ADRs default to status `Proposed` unless you say otherwise. It does not invent costs, benchmarks or quotes.
**Example** `/adr use SQS instead of Redis lists for background jobs; we lost jobs during the Redis failover last month` Creates `docs/adr/0007-use-sqs-for-background-jobs.md` with the context pulled from `config/queue.php` and the job classes, two alternatives, and consequences including the per-message size limit that large job payloads must now design around.
How to use it
1. Save the file below as `.claude/commands/adr.md`. 2. Run `/adr <decision and any context you have>`. 3. Answer Claude's follow-up questions (usually two or three). 4. Review the new file, change the status to `Accepted` when the team agrees, and commit it with the change it describes.
Files
Save each file at the path shown, relative to your project root.