Write an architecture decision record

Claude Code slash command (.claude/commands/adr.md). Creates a numbered ADR (context, options considered, decision, consequences) in docs/adr/ from a one-line topic, grounded in the current codebase.

License: CC0-1.0 · By waxmark · v1 · 2026-11-02

Share on X

Add a trust badge to your README

[![Waxmark](https://waxmark.app/api/badge/adr)](https://waxmark.app/items/adr/scan)
Report
---
description: Write a numbered architecture decision record for a design choice
argument-hint: <decision topic, e.g. "use Postgres row-level security for tenant isolation">
allowed-tools: Read, Grep, Glob, Write, Bash(ls *), Bash(git log *)
---

Write an architecture decision record for: $ARGUMENTS

Existing ADRs:
!`ls docs/adr 2>/dev/null || ls doc/adr 2>/dev/null || ls docs/decisions 2>/dev/null || echo "(none)"`

Procedure:
1. Choose the directory: the existing one above, or `docs/adr/` if none. Number = highest existing number + 1, zero-padded to 4 digits. Filename: `NNNN-<kebab-title>.md`. If an existing ADR covers the same topic, read it and write this one as a superseding record that links back.
2. Ground the context in the repo: Grep for the components the decision touches, read the relevant config or module entry points, and cite file paths. Do not invent constraints; if a constraint is assumed, label it.
3. Consider at least two real alternatives besides the chosen one. For each: how it would work here, what it costs, what it blocks. A rejected option described in one dismissive sentence is a sign the analysis is incomplete.
4. Write the record in the template. Status is `Proposed` unless the user says it is decided.
5. Show the path and the Decision and Consequences sections in the reply.

Template:

# NNNN. <Title in the imperative, e.g. "Use Postgres RLS for tenant isolation">

Date: <YYYY-MM-DD>
Status: Proposed | Accepted | Deprecated | Superseded by [NNNN](NNNN-....md)
Deciders: <roles or names if given>

## Context
What situation forces a decision. Current state with file references. Constraints (performance, compliance, team, deadline) and which are hard.

## Options considered
### Option A - <name>
How it works here. Pros. Cons. What it makes hard later.
### Option B - <name>
...
### Option C - <name>
...

## Decision
Which option and the two or three reasons that decided it. What we are explicitly giving up.

## Consequences
- Positive: ...
- Negative: ...
- Follow-up work: <tickets or tasks this creates>
- How we will know it was wrong: <observable signal and the revisit trigger>

## References
- Related ADRs, issues, docs, benchmarks.
Write an architecture decision record · Waxmark