Architecture Decision Records

Architecture decision records preserve consequential choices whose alternatives and rationale may matter to future changes. They complement current documentation: code and tests describe what exists, while an ADR explains why a durable choice was made.

Create one numbered Markdown file per accepted or proposed decision, using a short descriptive name such as 0001-resource-identity.md. Include:

• status and date
• the decision and its scope
• relevant constraints and credible alternatives
• rationale and consequences
• links to superseded or superseding decisions when applicable

Do not use ADRs for routine implementation details, unmade decisions, work instructions, or completed-task history. Do not rewrite an accepted ADR when the decision changes; add a new ADR that supersedes it.