DECISIONS.md
Architecture decision log
Keep important product, model, architecture, data, protocol, safety, and operating decisions traceable to context, alternatives, evidence, consequences, owners, and review triggers.
Fillable structure
Replace prompts with project evidence.
Remove any field that does not apply. A smaller maintained file is more useful than generic documentation that agents and reviewers cannot trust.
- 01
Decision index
Make active, proposed, superseded, and rejected decisions easy to discover.
Identifier: Assign a stable ADR or decision number and short title
Status: Mark proposed, accepted, deprecated, superseded, or rejected
Ownership: Name decider, consulted reviewers, date, and affected systems
- 02
Decision record
Capture the decision in enough context to understand it later.
Context: Describe the problem, constraints, forces, and urgency
Decision: State what is being chosen and the scope of that commitment
Consequences: List benefits, costs, risks, follow-up work, and compatibility impact
- 03
Alternatives and evidence
Show why the choice was reasonable without pretending uncertainty disappeared.
Alternatives: List viable options, including keeping the current state
Evaluation: Compare options against explicit product, quality, safety, cost, and operating criteria
Evidence: Link prototypes, benchmarks, evals, incidents, primary sources, and stakeholder input
- 04
Review and supersession
Define when new evidence requires the decision to be revisited.
Review triggers: Name thresholds, incidents, provider changes, scale, cost, or regulatory events
Review date: Set a date when uncertainty or change rate makes scheduled review useful
Supersession: Link the replacement decision and migration or cleanup work without rewriting history
Related field guides
Next template
AGENTS.md · Repository agent instructions