Back to the Playbook
Define & DesignDD-09
How to record an architecture decision
Record one decision with its real consequences; supersede earlier decisions visibly instead of erasing their rationale.
Product statusAvailable now
Input3 required inputsSystem constraints and alternatives · Prior ADRs and stakeholder concerns · Initiative focus and approved Product Brain guidance
SkillsDraft an architecture decision record · Prepare task context · Review an artifact against agreed criteriaArchitect + Architect Agent
OutcomeArchitecture decision record: title and status, context, decision and alternatives, consequences and supersession links.Artifact: Architecture decision record
Owner
Architect
Human + Agent
Participants · Agents
EngineerProduct ManagerArchitect Agent
Trigger
One consequential architecture decision is needed.
Required context
ArchitectureSystem constraints and alternativesConfluencePrior ADRs and stakeholder concernsProduct BrainInitiative focus and approved Product Brain guidance
Optional context
CodeRelevant code and deployed behaviourProduct BrainNonfunctional requirements
Skills
Draft an architecture decision recordPrepare task contextReview an artifact against agreed criteria
Suggested conversation arc
- 1Frame the architecture choiceAgree the decision question and constraints, including interfaces, quality needs and prior decisions that may conflict.Skills: Prepare task context
- 2Draft the decision recordDescribe context, alternatives, proposed decision and positive/negative consequences in a short ADR. Keep the proposed status until stakeholders agree.Skills: Draft an architecture decision record
- 3Review architectural consequencesCheck consistency with the product brain and affected system boundaries; expose missing consequences and any prior decision that would be superseded.Skills: Review an artifact against agreed criteria
- 4Confirm decision and historical linksAgree accepted, revise or rejected. If replacing an older ADR, preserve it and explicitly link the superseding decision; source updates require confirmation.
Output
Architecture decision record: title and status, context, decision and alternatives, consequences and supersession links.
Artifacts
Creates: Architecture decision record
What good looks like
- One decision with explicit trade-offs and status.
- Accepted status is grounded in actual reviewer agreement.
- A superseded ADR is preserved and linked, never erased.
Quality gate
The Architect and the affected engineers agree accepted, revise or rejected.
Destination
ConfluenceGitHub
Usually next
People and agents work from the same Product Brain. The owner stays accountable. Assigned agents prepare and check. A named person approves at the gate.
Deep dives from the AI PM Lab
Articles that explain the thinking behind this Activity.
Choose the path that matches your role.
Set the Product AI direction with us, or test the shared Product Brain on real work with Jira and code.