writing-adrs

Document architecture decisions by creating immutable Architecture Decision Records that capture context, decision, and consequences. Accepted ADRs are frozen to preserve historical context, with new ADRs created for any supersession or changes.

Create an Architecture Decision Record when a problem-doc discussion crystallizes into a concrete decision requiring cross-referencing with problem docs and evolving architecture. Each ADR records a single, traceable decision rather than modifying living documents.

The standard Architecture Decision Record structure includes frontmatter conformance, context, decision, and consequences. Records are placed under docs/ADRs with the next available number and follow a prescribed template for one decision per ADR.

Accepted Architecture Decision Records are immutable and cannot be modified directly. To handle changes, create a new ADR that supersedes the previous one, preserving the original record while cross-referencing the supersession.

Yes, this approach to architecture governance supports cross-referencing other ADRs and updates living documents like docs/architecture.md. It provides lifecycle guidance to keep problem docs aligned with evolving architecture decisions.

Immutable ADRs cannot be edited after acceptance, meaning any change requires creating a new superseding ADR rather than modifying the original. This preserves history but increases document count and requires careful cross-referencing to maintain traceability.