adr

To document architecture decisions for audits and onboarding, create sequentially numbered MADR files under docs/adr. Use the template sections for context, decision, and consequences to maintain consistent design review traceability.

The MADR format for architecture decision records is a standardized template that structures each file with context, decision, consequences, and references. This provides a clear, discoverable process for preserving decision rationale over time.

To track the status lifecycle of an architecture decision record, update the file with proposed, accepted, or deprecated statuses. Maintain an index file in the docs/adr directory to log these statuses and dates for full traceability.

You need to create an architecture decision record when introducing a new service design or making significant architecture choices. This justifies design decisions, links related records, and prevents knowledge gaps during team reviews.

The best way to structure an index for multiple architecture decision records is to maintain a dedicated index file in the docs/adr directory. This file sequentially tracks each record's title, status lifecycle, and date for auditability.

Writing architecture decision records using this approach requires no specific dependencies. You simply copy the MADR template into your docs/adr directory and fill in the context, decision, and consequences sections manually.