Create ADR

Capture architectural decisions as durable, minimal records future-you (and future-Claude) can read instead of guessing from code.

Gate — write an ADR only if all three are true

1. Hard to reverse — changing your mind later costs meaningful effort (migration, rewrite, vendor lock-in).
2. Surprising without context — a future reader will look at the code and wonder "why did they do it this way?"
3. Real trade-off — there were genuine alternatives, and you picked one for specific reasons.

If any criterion is missing, say so and skip the ADR. Easy-to-reverse decisions get reversed; obvious decisions don't need recording; non-decisions ("we did the only thing that worked") aren't ADRs.

Cheap rejections prevent ADR sprawl. When in doubt, refuse and ask the user to confirm the decision really meets all three.

What qualifies

• Architectural shape — "monorepo," "event-sourced write model + projected read model"
• Integration patterns between modules/contexts — "Ordering and Billing communicate via events, not synchronous HTTP"
• Technology choices with lock-in — database, message bus, auth provider, deployment target. Not every library — only ones that take a quarter to swap.