adr

An architecture decision record documents significant architectural choices to preserve system reasoning. You should create one during the research phase when selecting between competing approaches or when formal documentation is requested.

To document an architectural decision, create a numbered entry in docs/decisions/ that includes context, options, decision rationale, consequences, and related references to capture the full tradeoff analysis.

Manage the lifecycle of an architecture decision record by updating its status flow from Proposed to Accepted, or optionally to Deprecated or Superseded. Never delete ADRs to maintain historical context.

Architecture decision records should be stored as numbered files under the docs/decisions/ directory to ensure consistent placement and long-term retrieval for your engineering team.

No specific framework is needed to start writing architecture decision records. You can apply the structured format directly within your existing software engineering process and documentation workflow.

Preserving architectural decision rationale matters because it ensures your team retains the reasoning behind system design choices, not just the final implementation, preventing knowledge loss during personnel changes.