Delivery · Evolved from Architecture Decision Records
Architecture & Product Decision Records
Timestamped records of significant decisions with context, alternatives, and rationale. In AI-era practice, includes model, prompt, and dataset selection decisions with their evaluation basis.
Executive Guidance
How to hold this framework as a leader
Decision records exist to end the re-litigation of settled decisions and to create a durable audit trail. They are the single lowest-effort, highest-leverage governance habit an enterprise product team can adopt. Executives should require them for any decision with lasting architectural or product consequence.
Model, prompt, and dataset selection are decisions that expire. Every ADR in this class should specify the evaluation basis for selection and a review trigger — a date, a benchmark change, or a vendor event — that forces reconsideration.
When to Apply
- Decisions with long-term architectural or product consequence
- Model, vendor, or dataset selection for AI capabilities
- Any decision that establishes organizational precedent
AI-Era Notes
Model selection is a decision that expires. Every model ADR should include the eval basis for selection and a review trigger for re-evaluation as the model landscape changes.
Key Trade-off
Model selection ADRs age quickly; without review triggers, decisions calcify against a shifting landscape.
Operating Sequence
The order in which to install the framework
- 01Establish an ADR template with context, decision, alternatives, and consequences.
- 02Require an ADR for any decision that establishes precedent or is costly to reverse.
- 03For AI-related decisions, include model, version, eval basis, and review trigger.
- 04Store ADRs in a durable, indexed location accessible across teams.
- 05Review ADRs whose triggers have fired and produce a decision update record.
Key Artifacts
The documents this framework produces
ADR Template
Standard structure for decision records.
Owner: Product + Engineering
Decision Log Index
Indexed catalog of ADRs discoverable across teams.
Owner: Product Operations
Model Selection ADR
Specialization for model, prompt, or dataset decisions with review triggers.
Owner: Product + AI/ML
Operating Checklist
What "good" looks like when installed
Content
- Context describes the situation, not the decision.
- At least two alternatives are considered and documented.
- Consequences include both accepted trade-offs and known risks.
AI-Specific
- Model version and provider are recorded.
- Evaluation basis for selection is cited.
- Review trigger is defined and calendared.
Common Antipatterns
- ADRs written after the fact to justify a decision
- Missing model version and eval basis in AI-related decisions
Boardroom Questions
- Where is the durable record of the decisions that shape our product architecture?
- Which of our model-selection decisions are overdue for review?
- What decisions are we currently making without a record?