ADR — Architecture Decision Record

Load only when you have a structural decision to record. Default behaviour for any developer is no ADR.

When to write one

Yes:

• New pattern introduced into the codebase (not just used once — recurring).
• New runtime dependency (npm package, new Supabase extension, external service).
• Deliberate departure from an existing convention.
• Non-obvious schema choice (denormalisation, computed column, soft-delete strategy).

No:

• File naming, folder placement.
• A bug fix or refactor with no structural impact.
• Style decisions already captured by lint/prettier.

File naming — namespaced by session + ticket

Path: <WORKTREE_PATH>/adr/ADR-<SESSION_SHORT_ID>-<TASK-XXX>-<slug>.md

• <SESSION_SHORT_ID> is your session id — the prefix of your BRANCH_NAME before the / (e.g. BRANCH_NAME=58e4ec51/TASK-004 → 58e4ec51). It scopes the ADR to this session.
• <TASK-XXX> is the literal ticket id. Together with the session id it forms the namespace — there is no separate sequence number (e.g. ADR-58e4ec51-TASK-004-supabase-rls-strategy.md).
• <slug> is kebab-case, ASCII, ≤ 40 chars.
• One ADR per ticket is the common case. If the same ticket genuinely needs two ADRs, the distinct slugs keep them apart.

Why the session+ticket namespace: in a wave, N developers run in parallel on worktrees branched from the same base. A monotonically-incremented ADR-NNN-… scheme makes every worker independently pick the same next number (e.g. all land on ADR-003); different slugs hide the collision from git merge, so duplicate numbers land in $CLAUDE_PROJECT_DIR/adr/ silently. <TASK-XXX> removes the intra-wave collision; the <SESSION_SHORT_ID> prefix removes the cross-session one — ticket numbering restarts at TASK-001 each session, so two sessions both producing a TASK-004 would otherwise overwrite each other's ADR in the shared $CLAUDE_PROJECT_DIR/adr/.

Source-code reference

One comment at the most representative line of the change, pointing at the ADR you just wrote:

• TS/JS/CSS: // See adr/ADR-<SESSION_SHORT_ID>-<TASK-XXX>-<slug>.md
• Python/SQL/shell: # See adr/ADR-<SESSION_SHORT_ID>-<TASK-XXX>-<slug>.md

No need for more than one reference; reviewers follow the link.

Commit

The ADR + its reference comment go in the same commit as the code they describe (WORKFLOW step 3). Subject:

docs(TASK-XXX): ADR-<SESSION_SHORT_ID>-<TASK-XXX> <title>

Reviewers see the ADR alongside the implementation.

Template (≤ 25 lines)

# ADR-<SESSION_SHORT_ID>-<TASK-XXX> — <decision title>

- **Date**: YYYY-MM-DD
- **Ticket**: TASK-XXX
- **Session**: <SESSION_SHORT_ID>

## Context

2–4 lines on what made this decision necessary.

## Decision

1–3 lines on what was chosen.

## Consequences

- Up to 4 bullets: what this enables, costs, locks in.

## Alternatives considered

- Up to 3, one line each, with reason for rejection. If none were captured, write `- _Not captured at decision time._` — never invent.

Keep it short. An ADR longer than 25 lines is a sign that the decision either belongs in code comments or is actually several decisions that should be split.

Red Flags

• An ADR written for a naming, file-placement, or pure-style choice (no ADR is the default).
• A monotonic ADR-NNN-… filename instead of the ADR-<SESSION_SHORT_ID>-<TASK-XXX>-<slug> namespace parallel workers collide on the same number.
• An ADR file written outside the worktree, or committed separately from the code it describes.
• Alternatives considered invented after the fact instead of - _Not captured at decision time._.
• An ADR past 25 lines likely belongs in code comments or is several decisions.

Verification

• The change is a genuine structural decision (new pattern, dependency, convention departure, non-obvious schema) otherwise no ADR.
• Filename is <WORKTREE_PATH>/adr/ADR-<SESSION_SHORT_ID>-<TASK-XXX>-<slug>.md.
• Exactly one source-code reference comment points at the ADR.
• ADR + reference comment are in the same commit as the code, with the docs(TASK-XXX): subject.
• Body follows the template and is ≤ 25 lines.