design-architecture

Architecture Decision Records capture cross-cutting choices as immutable records using a stable template. They document context, decision, consequences, and alternatives to provide an auditable trail across multi-repo projects.

An ADR lifecycle tracks decisions through Proposed, Accepted, and Superseded states. This structured progression ensures architecture choices remain traceable and prevents re-litigation during rework or package updates.

You need an Architecture Decision Record when a data modeling choice spans multiple packages, requires traceable context, and should endure across rework. ADRs explain why hard-to-reverse decisions were made to prevent future re-litigation.

You link architecture decisions by referencing ADRs within specs, CLAUDE.md, or architecture documentation. This maintains traceability across packages and connects the immutable decision record to active project governance.

You should document the context, decision, consequences, and alternatives. Using a stable ADR template ensures the rationale for cross-cutting architecture choices is captured completely for future evaluation.

You can evaluate existing ADRs to assess the rationale, alternatives, and trade-offs of accepted architecture decisions. This review process leverages the structured record of context and consequences to validate past choices.