adr

To write an architectural decision record, you must structure the document with a title, context, decision, and consequences. ADRs are typically stored in a dedicated directory like docs/adr to maintain traceability and governance across the codebase.

Nygard and MADR templates provide different structural approaches for decision records. Nygard offers a concise format focusing on context and consequences, while MADR provides a detailed structure with fields for rejected alternatives and compliance validation.

You need to create an architectural decision record when a structural choice has significant impact and warrants formal documentation. If a decision affects multiple components or requires durable traceability, formal ADR documentation captures the rationale for future reference.

To scaffold a new ADR file with correct numbering, place it in the docs/adr directory and increment the sequence number from the last existing record. The file status should default to Proposed until the decision is formally reviewed.

You can use existing ADR template preferences by detecting Nygard or MADR formats already present in the repository. Adapting recommendations to match your current template ensures structural consistency across all architectural decision documentation.

The required sections for a valid architectural decision record are a title, context, decision, and consequences. Enforcing these conventions ensures the ADR captures the complete rationale and impact, defaulting the file status to Proposed until reviewed.