| name | architecture-decision-record |
| description | Use when creating, reviewing, backfilling, superseding, or organizing architecture decision records (ADRs/MADR) for significant technical decisions; avoid trivial implementation notes and broad design documents |
Architecture Decision Record
Overview
Create and review architecture decision records (ADRs) using the project's local convention first and MADR (Markdown Architectural Decision Records) when no stronger local convention exists. ADRs capture one significant decision, why it mattered, what options were considered, what was chosen, what tradeoffs follow, and how the decision will be confirmed or revisited.
Use the project's existing ADR template and conventions first. Use this bundle when the project has no stronger local convention or when reviewing whether an ADR is complete and useful.
References
Load only the reference needed for the current task:
Use And Avoid
Use an ADR when the decision:
- Has architectural significance: structure, key qualities, major dependency, external interface, operating model, security posture, or cost/risk profile.
- Has real alternatives or meaningful tradeoffs.
- Will matter to future maintainers, reviewers, auditors, or adjacent teams.
- Needs agreement, implementation follow-through, or later revisiting.
Do not create an ADR for:
- Trivial implementation choices that are local, obvious, and cheap to reverse.
- A broad design document, RFC, policy, or architecture blueprint. Link those from the ADR instead.
- A decision already recorded clearly elsewhere, unless the user is asking to convert that record into the project's ADR log.
- A bundle of unrelated decisions. Split them.
Workflow
1. Classify The Task
Decide which flow applies:
- New ADR: draft and write a decision record.
- Review ADR: critique a draft or existing ADR for completeness, rationale, and MADR fit.
- Backfill ADR: document a past decision honestly, including what is known now versus what was known then.
- Supersede ADR: write a new ADR and update the old ADR status.
- Log setup: choose ADR directory, numbering, categories, and templates.
If the task is Review ADR:
- Load references/review-checklist.md.
- Inspect the supplied ADR and any local ADR conventions needed to review it.
- Do not choose a template, number, or destination unless the user asks to update or file the ADR.
- Separate template-conformance findings from decision-quality findings.
- Return findings first by severity, with concrete fixes. Then list what is already sound.
If the task is Log setup, load references/adr-log-conventions.md, discover the local documentation convention, and return the recommended directory, numbering, templates, and lifecycle rules before writing files.
For New ADR, Backfill ADR, and Supersede ADR, continue through the creation workflow below.
2. Check Significance And Scope
State the decision as one question. If the question actually contains multiple choices, split it before drafting.
Gather:
- Problem and context.
- Decision drivers: requirements, constraints, qualities, risks, stakeholders.
- Real options, including status quo only when it is a viable option.
- Decision-makers, consulted experts, and informed stakeholders.
- Evidence: tickets, RFCs, benchmarks, incidents, PRs, diagrams, production constraints.
Do not invent stakeholders, dates, ticket IDs, benchmark results, incident links, PRs, diagrams, or evidence. Inspect the repository or user-provided material when available. If required facts are missing, leave a clear placeholder or list an open question instead of manufacturing provenance.
For a backfill ADR, separate the original rationale from hindsight. Record what was known at decision time and put later evidence or changed assumptions in More Information.
3. Discover Local Convention
Use ../../shared/plan-location-discovery.md to find the right documentation area. Also inspect these ADR-specific locations:
docs/decisions/docs/adr/docs/ADRs/docs/architecture/decisions/decisions/
If existing ADRs or templates exist, preserve their directory, filename, heading, status, and metadata conventions unless the user explicitly asks to migrate them. If no convention exists, use docs/decisions/ and NNNN-title-with-dashes.md.
4. Choose ADR Size
Load references/section-chooser.md when deciding section depth.
- Minimal: use adr-template-minimal.md for low-complexity decisions with clear options.
- Standard: include metadata, drivers, consequences, and more information for normal engineering decisions.
- Canonical MADR full: use adr-template-madr-full.md when the user asks for the exact/full MADR template or the project wants the published MADR shape without local adaptation.
- Adapted full: use adr-template.md when the decision is controversial, high risk, multi-stakeholder, compliance-relevant, or likely to be revisited and local adaptation is acceptable.
- Experimental/time-boxed: include confirmation, success/kill criteria, fallback plan, and review date.
5. Draft Or Update
For a new ADR:
- Determine the next number by listing existing ADRs and matching the existing padding. Default to four digits.
- Copy the selected template.
- Fill required sections before optional sections.
- Use exact option names consistently in
Considered Options, Decision Outcome, and Pros and Cons.
- Link supporting evidence instead of embedding large design detail.
For a superseding ADR:
- Create a new ADR that explains why the earlier decision no longer holds.
- Update the old ADR status to
superseded by ADR-NNNN.
- Link both directions through status or
More Information.
6. Validate Before Finishing
Before returning the ADR or review, check:
- The ADR records one decision.
- The problem is relevant enough to record.
- All placeholders are removed or intentionally left as template guidance.
- The chosen option appears in the considered options.
- Options are real, comparable, and at the same abstraction level.
- Rationale ties back to drivers, constraints, or evidence.
- Consequences include at least one meaningful cost, risk, or tradeoff when the decision is accepted.
- Confirmation or revisit criteria exist for risky, experimental, compliance, or time-sensitive decisions.
- Cross-links, filenames, status values, and old superseded ADRs are consistent.
Statuses
| Status | Meaning |
|---|
| proposed | Decision is under discussion, not yet agreed upon |
| accepted | Decision has been agreed upon and should be followed |
| rejected | Decision was considered but not adopted |
| deprecated | Decision is no longer relevant or recommended |
| superseded by ADR-NNNN | Replaced by a newer decision; link to the successor ADR |
Use the local project's status vocabulary if it already exists.
Output Contract
When creating or updating an ADR, report:
- File path.
- Status and chosen option.
- Sections included and intentionally omitted.
- Validation performed.
- Open questions or follow-up actions.
When reviewing an ADR, report findings first by severity, with concrete fixes. Then list what is already sound.
Common Mistakes
- Writing the ADR after implementation as a foregone conclusion instead of honest rationale.
- Comparing fake alternatives, mismatched abstraction levels, or one option only.
- Stating the choice without explaining why it satisfies the drivers.
- Hiding negative consequences or operational costs.
- Using subjective, promotional, or blame-oriented language.
- Turning the ADR into a full design document instead of linking supporting artifacts.
- Forgetting consulted/informed stakeholders, confirmation, or revisit criteria for decisions that need them.
