create-adr

An architecture decision record (ADR) captures the context, trade-offs, and rationale behind major design choices. You need an ADR when a decision is hard to reverse, requires context, and needs traceability across code and design to prevent future guesswork.

To create an ADR, you generate a markdown file under docs/adr/ using a zero-padded, auto-incremented four-digit number with a slug-based filename. This ensures your architecture decisions are organized with consistent numbering for easy retrieval.

An architecture decision record should include a short, present-tense summary and optional sections like Status, Considered Options, and Consequences. These sections document boundary decisions, alternatives, and provide a quick-reference for future readers.

Yes, the ADR format supports optional sections specifically for Considered Options and Consequences. This allows you to document boundary decisions, include consideration of alternatives, and provide traceability for future maintenance.

The best way to document architectural rationale is using concise ADRs that explain what was decided and why. Recording decisions as durable notes with context and trade-offs prevents guesswork and confusion in future maintenance.