architecture-decision-record — Claude Code command: ADR backed by code
Runs the wa-builder skill in ADR mode: reads the codebase, weighs options against real code and writes an Architecture Decision Record with the trade-offs spelled out.
MIT-0 ★ 280 updated 2026-10-06
.claude/commands/architecture-decision-record.mdWhat architecture-decision-record does
Point the command at a decision and the agent goes through the code first: what exists today, which options are on the table, and where each one touches the repository.
The result is a structured Architecture Decision Record. You get the trade-offs of the chosen route and a migration path, plus the triggers that should reopen the decision later. Impact on the Well-Architected pillars is assessed alongside.
All of the reasoning lives in the wa-builder skill, in its “Mode: Architecture Decision Record” section. This file only invokes that mode, so nothing runs until the skill is in place. Drop the command at .claude/commands/architecture-decision-record.md and it answers to /architecture-decision-record.
What it helps with
- pin down why an architectural choice was made before the reasoning fades
- compare two migration routes using evidence from the code
- check a change against the Well-Architected pillars
- refresh an outdated ADR after the repository moved on
- set the conditions that should reopen a decision
Example prompts for the agent
/architecture-decision-record— record the move to a separate notifications service, work from what the code does today/architecture-decision-recordrewrite the queue ADR, we swapped brokers and the review triggers are stale- Weigh two storage layouts for the orders module and write it up as an ADR with a migration path.
How to install architecture-decision-record
Manually: put the files in place
.claude/commands/architecture-decision-record.mdCall it with /architecture-decision-record. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/architecture-decision-record.mdCall it with /prompts:architecture-decision-record. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/architecture-decision-record.prompt.mdManually: put the files in place
.gemini/commands/architecture-decision-record.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about architecture-decision-record
How do I install architecture-decision-record in Claude Code?
Copy the command file to .claude/commands/architecture-decision-record.md. It then shows up as /architecture-decision-record.
What does architecture-decision-record do?
It runs wa-builder in ADR mode. The agent inspects the codebase, compares options and produces a decision record covering trade-offs and a migration path, with review triggers attached.
Does the command work without the wa-builder skill?
No. It defers to the “Mode: Architecture Decision Record” section of wa-builder, so that skill has to be installed first.
Source text
architecture-decision-record.md · MIT-0
Run wa-builder in **ADR mode** to create or revise an Architecture Decision Record. Follow the wa-builder skill, "Mode: Architecture Decision Record" section. Analyze the codebase to understand current state, evaluate options with code evidence, assess WA pillar impact, and produce a structured ADR with trade-offs, migration path, and review triggers. <!-- Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: MIT-0 -->
© aws-samples · MIT-0 · aws-samples/sample-well-architected-skills-and-steering