adr

Architectural decision records (ADRs) capture design choices using the MADR format to ensure decisions are documented, traceable, and maintainable over time. Sequential numbering and status lifecycle tracking keep the project history clear.

The MADR format structures ADRs with explicit Context, Decision, and Consequences sections, along with status tracking and references. This guided workflow helps teams draft clear context and document the rationale behind major design choices.

To start an ADR, trigger the workflow for your design decision or dependency upgrade. The system guides you through drafting context, decision, and consequences, then saves the file sequentially under docs/adr/0001-<title>.md.

Create an ADR when making major architectural decisions, such as introducing new components or upgrading dependencies. Documenting these choices provides traceable records that explain why specific design paths were taken over alternatives.

To supersede an old architectural decision, create a new ADR with the next sequential number and update the status of the previous record. The append-only workflow ensures the history of design decisions remains documented and traceable.

ADRs use an explicit status lifecycle to track design decisions from proposal to acceptance. This status field, combined with sequential numbering and append-only records, ensures the full lifecycle of architectural choices is maintained.