Skip to main content
command CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/architecture-decision-record.md
Open on GitHub

What 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-record rewrite 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.md

Call it with /architecture-decision-record. For all projects use ~/.claude/commands/

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

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set19

The whole set →
migration-readiness migration-readiness reads your code, dependencies and infrastructure, then reports what stands in the way of moving a workload to AWS. Useful before a migration when the starting point is unclear. CX Codex +1 565installs wa-guardrails wa-guardrails generates preventive and detective Well-Architected controls: AWS Config rules, SCPs, permission boundaries, CloudWatch alarms and IaC policy checks. CX Codex +1 383installs aws-well-architected-framework-review aws-well-architected-framework-review is a Claude Code skill that assesses AWS workloads against the Well-Architected Framework. It examines code and IaC, then reports evidence-backed findings and remediation priorities. CX Codex +1 339installs wafr-facilitator wafr-facilitator prepares facilitators to lead conversational AWS Well-Architected reviews. It analyzes diagrams or IaC to generate tailored questions and red flags. CX Codex +1 331installs security-assessment security-assessment runs a targeted AWS Well-Architected review for the Security pillar. It audits IAM, encryption, detection, and compute controls. CX Codex +1 ★ 280repo stars operational-excellence This command reviews the Operational Excellence pillar of AWS Well-Architected and returns a report with a maturity scorecard. Use it to examine CI/CD, observability, and incident management. CX Codex +1 ★ 280repo stars reliability-improvement-plan reliability-improvement-plan is a Claude Code command that runs a Well-Architected review of the Reliability pillar, checking fault tolerance, recovery, scaling, and change management. CX Codex +1 ★ 280repo stars cost-optimization-review cost-optimization-review runs an AWS Well-Architected review focused on cost optimization and generates a savings report. CX Codex +1 ★ 280repo stars

Project sponsors

Companies that keep this analytics open