Claude CodeでAWS Well-Architectedレビューを自動化する

先日参加した AWS Summit で共有されたリポジトリがかなり良かったので、紹介とハンズオンをまとめます。
対象リポジトリ: aws-samples/sample-well-architected-skills-and-steering

要点

• AWS Well-Architected Framework(WA)を AIコーディングエージェントに教え込む ための、再利用可能な「Skills / Steering」集
• 1つの定義で13ツールに対応(Kiro / Claude Code / Cursor / Codex / Cline / Gemini CLI など)
• AWS認証情報もAPI呼び出しも不要。すべてローカルで完結する
• WA の 307ベストプラクティス / 57設問 / 27レンズ拡張 がリファレンスとして同梱されており、エージェントが必要な分だけ段階的にロードする
• 意図的にWA違反を仕込んだ サンプルIaC(CDK / Terraform) が付いていて、すぐ試せる
• この記事の後半で、Claude Code から脆弱な Terraform をレビューさせるハンズオン を用意しました

なぜこれが刺さるのか

個人的な所感ですが、WA レビューって、普段は「設計が一段落したあとの別フェーズ」になりがちですよね。チェックリストを開いて、ドキュメントを読み返して……となると、どうしても後回しになる。

一方で、いまの開発現場では「ドキュメントを読みにいく」より先に AIアシスタントに聞く という行動がデフォルトになりつつあります。だとすると、そのアシスタント自身が WA を理解していないと、ベストプラクティスはコードまで届かない、というのがこのプロジェクトの問題意識です。

このリポジトリは、WA のベストプラクティスを 「コードを書いているまさにその瞬間・その場所(IDE)」に埋め込む ことを狙っています。レビューを独立したゲートにするのではなく、設計・実装中に継続的・文脈依存でガイドが効く、という発想です。

個人的に特に注目すべきと感じた要素は次の3つでした。

• 単一の定義ソースで13ツールをカバーしている(アダプタで各ツールのネイティブ設定形式に変換)
• 認証情報が一切いらないので、検証のハードルが限りなく低い
• オープンな Agent Skills 仕様 に準拠している

何が入っているのか

ざっくり全体像はこんな構成です。

skills/ ツール非依存のステップbyステップ・プレイブック(11種)
steering/ 常時ロードされるコンテキスト(Kiro向け。他ツールはadapterで変換)
adapters/ 各ツール用の設定ファイル(CLAUDE.md / .clinerules / GEMINI.md ...)
examples/ WA違反を意図的に仕込んだサンプルIaC(CDK / Terraform)
assets/ 共有リファレンス(メトリクス閾値、インシデント調査パターンなど)
powers/ Kiro Powers(wa-reviewを1パッケージ化、自動アクティベート)
evals/ Bedrockを使った自動評価ランナー
install.sh ワンコマンドセットアップ(install.ps1 はWindows向け)

Skills(11種)

中核はこの「Skills」です。それぞれが自己完結したプレイブックで、どのエージェントでも手順どおりに実行できます。

対応ツール(13+)

skills/(プレイブック)と steering/(常時コンテキスト)という単一ソースを、adapters/ が各ツールのネイティブ形式に変換する、という構造です。

Kiro / Kiro CLI / Claude Code / Cursor / Codex / Windsurf / GitHub Copilot / Gemini CLI / Antigravity / Junie / Amp / OpenClaw / Cline / AWS DevOps Agent に対応。

たとえば Claude Code なら CLAUDE.md(常時ガイド)+ .claude/commands/*.md(スラッシュコマンド)、Cline なら .clinerules といった具合に、ツールごとの作法へ落とし込まれます。

エンジニア的に面白かったポイント

1. リファレンスを「段階的にロード」するトークン戦略

wa-review には 307ベストプラクティス(BP)/ 57設問 / 27レンズ拡張 がリファレンスとして同梱されています。これを全部一度に読み込むと、入力だけで 約50〜60万トークン に達してしまう。ほとんどのモデルのコンテキスト上限を軽く超えます。

そこでこのスキルは、1設問ずつロード → 評価 → 所見を書く → 次へ という逐次処理で進めるように指示されています。リファレンスファイルを同時にコンテキストに抱えない設計です。さらに用途に応じて、こんな戦略を選べます。

「まず Quick で当たりをつけ、弱いピラーだけフルレビュー」という二段構えにすると、57設問+レンズ(約60万トークン)を全部読むより大幅に節約できる、という運用が推奨されています。このあたりの「コンテキスト管理を仕組みとして設計している」点は、実務的だと感じました。

2. 効果がちゃんと測定されている

evals/ に、Amazon Bedrock を使った自動評価ランナー(LLM-as-judge)が同梱されています。同じプロンプトを「スキルあり/なし」でペア比較し、各アサーションを PASS/FAIL で採点する仕組みです。

リポジトリに載っている計測結果(Claude Opus 4.8 で生成・採点)では、平均で ベースライン85% → スキルあり99%(+15ポイント)。wa-review は 82%→100%、wa-builder は 61%→94% と、スキル投入の効果が定量化されています。「スキルありがなしより悪化することはない(改善か同等)」と明記されている点も、確認できて安心しました。

注: 上記の数値・コスト試算はリポジトリ記載のもの(2026年6月時点)です。モデルやプロバイダ、キャッシュ有無で実コストは変わります。

ハンズオン：Claude Code で「脆弱な Terraform」をレビューさせる

ここからは実際に手を動かすパートです。
ポイントは、AWSアカウントもデプロイも不要 なこと。リポジトリ同梱の「意図的に約17個のWA違反を仕込んだ Terraform サンプル」に対して、Claude Code の /wa-review を流し、ちゃんと違反を検出できるかを確認します。

前提

• macOS(Linux でも同様)
• git が使えること
• Claude Code がインストール済みでログイン済みであること
• (任意)terraform CLI — 構文確認をしたい場合のみ。レビュー自体には不要

Step 0. ゴールの確認

サンプル examples/insecure-serverless-app-terraform/ には、以下のような違反が仕込まれています(# WA-ISSUE: コメント付き)。

• Security(6): S3暗号化なし / パブリックアクセスブロックなし / Lambda IAMがワイルドカード / API GatewayにWAFなし / DBパスワードが平文default / SG が 0.0.0.0/0 で SSH(22)許可
• Reliability(4): RDSがSingle-AZ / SQSにDLQ(デッドレターキュー)なし / RDSバックアップ保持0 / Lambdaの失敗ハンドリングなし
• Cost(4): Lambdaメモリ3008MB過剰 / S3ライフサイクルなし / DynamoDBキャパシティ過剰 / Lambdaがx86(Gravitonでない)
• Performance(3): キャッシュ層なし / CloudFrontなし / 同期呼び出しのみ
• Operational Excellence(3): CloudWatchアラームなし / ログ保持ポリシーなし / デプロイ戦略なし
• Sustainability(2): 日次バッチ用に常時起動の t3.large / S3 Intelligent-Tieringなし

README いわく「良いツールなら約17個のうち最低12個は検出できるはず」とのこと。これを実際に確かめます。結論から言うと、今回は仕込み全項目 + α を検出しました(詳細は Step 5)。

Step 1. リポジトリを取得

cd ~/work # 任意の作業ディレクトリ
git clone https://github.com/aws-samples/sample-well-architected-skills-and-steering.git
cd sample-well-architected-skills-and-steering

Step 2. レビュー用の作業プロジェクトを用意

サンプルの Terraform を、独立した検証用ディレクトリにコピーします(元リポジトリを汚さないため)。

mkdir -p ~/work/wa-handson
cp -r examples/insecure-serverless-app-terraform/* ~/work/wa-handson/

Step 3. Claude Code 向けに WA スキルを導入

作業プロジェクトに、Claude Code 用の CLAUDE.md とスラッシュコマンドを入れます。install.sh を使うのが楽です。

# sample-well-architected-skills-and-steering ディレクトリ内で実行
./install.sh ~/work/wa-handson --tool claude-code

実行すると、作業プロジェクト配下に次のファイルが展開されます。

• CLAUDE.md … 6ピラーや設計原則を常時ロードするガイド
• .claude/commands/*.md … /wa-review など各スキルのスラッシュコマンド
• .claude/skills/*/SKILL.md … スキル本体+リファレンス

$ ./install.sh ~/work/wa-handson --tool claude-code
（中略）
Installation complete!

$ ls ~/work/wa-handson/.claude/commands/
architecture-decision-record.md operational-excellence.md security-assessment.md
cost-optimization-review.md performance-efficiency.md sustainability-optimization.md
migration-readiness.md reliability-improvement-plan.md wa-builder.md
wa-guardrails.md wa-review.md

導入ログを眺めていて気づいたのですが、.claude/skills/wa-review/references/lenses/ の下に 業界レンズが大量に同梱されていました。serverless / generative-ai / agentic-ai だけでなく、financial-services / healthcare / iot / games / telco / machine-learning / supply-chain / microsoft-workloads / SAP など数十種類。ヘルスケアや金融など、案件で扱う業界レンズが最初から入っているのは実務面で助かるところです。

別解(クローン不要):npx skills add aws-samples/sample-well-architected-skills-and-steering --skill wa-review でも導入できます。bootstrap.sh を curl で流す方法もあり。

Step 4. Claude Code でレビューを実行

必ず作業プロジェクト(wa-handson)のディレクトリで起動してください。スラッシュコマンドはカレント直下の .claude/ を見るため、別ディレクトリで起動すると /wa-review が候補に出ません(実際、最初にリポジトリのルートで起動して出ずにハマりました)。

cd ~/work/wa-handson
claude # Claude Code を起動

起動後、入力欄に /wa と打つと、/wa-review(project)がサジェストされます。ここが出れば導入成功です。

/wa-review /wa-builder が2つずつ出るのは、commands/(スラッシュコマンド)と skills/(SKILL.md)の両方から登録されているためです。どちらを選んでもOK。

/wa-review を選び、続けて依頼内容を入力します。今回はまず段階的アプローチで当たりをつけるため quick review を指定しました。

/wa-review

このディレクトリのTerraform（main.tf / variables.tf / outputs.tf）を対象に、
まず quick review でお願いします。business criticality は standard。

すると /wa-review は スコープ確認 → インフラ探索(discovery) を自動で進めます。今回はIaCが明確なのでスコープのプロンプトはスキップされ、main.tf から11リソースを棚卸ししたうえで、サーバーレスワークロードと判定して Serverless Applications レンズを自動適用してくれました。

discovery のあと、レビュー深さを対話で選べます(Full / Quick / Score only / ピラー限定)。これがまさに「トークン戦略を選べる」仕組みそのもの。今回は「2. Quick review」を選択しました。

補足:途中でファイル読み取り等の承認プロンプト(manual mode)が出ます。読み取り主体なので都度 Yes で進めてOKです。

Step 5. レビュー結果と答え合わせ

Quick review は数分でリスクアセスメントのサマリを返してきました。Critical 4 / High 7 / Medium 8 / Low 5 = 計24件、総合成熟度 1.7/5。

続けて full report をお願いします と依頼すると、PlantUML（コードから図を自動生成するツール）構成図・全57問アセスメント・ピラースコアカード・Critical所見・アイゼンハワーマトリクス（重要度と緊急度のマトリクス）・SMART目標つき改善計画まで、日本語のフルレポートが出力されました(全文はスクショ参照)。

ピラースコアカードがこちら。Security が 1/5 と最も低く、即時対応が必要な重大欠陥を複数含む、という評価です。

Critical 所見は、いずれも main.tf:82-97 のようにファイルパス+行番号の根拠つきで提示されます。ここが「一般論の指摘」と違うと感じた点で、そのまま修正箇所に飛べます。

そして改善計画は、アイゼンハワー・マトリクス(Do First / Plan / Delegate / Defer)で優先度分けされ、Quick Wins には SMART目標・想定オーナー・工数まで付いています。

答え合わせ:仕込み vs 検出

Step 0 の仕込みリストと突き合わせた結果が以下です。仕込み全項目を検出し、README の合格ライン(約17個中12個以上)を大きく超えました。

さらに、仕込みリストに無い指摘も自力で拾っていました。nodejs18.x が EOL 間近、RDS/EC2 がデフォルトVPC露出、RDS 暗号化未指定、など。加えて、転送時暗号化(RDS SSL強制)のようにコードから判断できないものは “Cannot Determine” と正直に返す——事実にないことを断定しない挙動も、安心して使える理由だと感じました。

⚠️ 注意点:今回、レビューは Production 基準で採点されました。プロンプトでは business criticality は standard と伝えたのですが、Claude はコード上の environment = "production" という値を優先したためです(挙動としては妥当)。standard 基準で採点させたい場合は、environment の値を変えるか、明示的に「コードの値に関わらず standard で評価して」と指示する必要があります。ここは実運用でスコアが厳しめに出る要因になり得るので、認識しておくと良いです。

Step 6. wa-guardrails で「検出 → 予防」へ

検証の締めに /wa-guardrails を実行し、検出した違反を二度と混入させないためのガードレールを生成させました。

/wa-guardrails
今回のレビューで検出した High/Critical（IAMワイルドカード・SG全開放・S3暗号化なし・認証なし）を
予防するガードレールを生成して。AWS Config rules・SCP・CIチェック（tfsec/checkov相当）を出して。

出力は guardrails/ 配下に 15コントロール(予防9 / 検知6) として生成され、単なるルール列挙ではなく実装レベルまで含まれていました。

• CI ゲート：checkov 設定 + 自作ポリシー(authorization="NONE" を弾く Python チェック)+ tfsec/trivy 代替ルール
• AWS Config rules：暗号化必須・パブリック公開禁止・SSH制限などのライブ検知(バックストップ)
• SCP(サービスコントロールポリシー / 組織全体に効く予防的な制御)/ 権限境界：組織横断の予防(暗号化なしRDS作成を Deny 等)、IAMワイルドカード対策の権限境界
• Rollout plan：初日から hard block せず、「Config検知 → checkov soft-fail → 権限境界 → SCP」の段階導入
• Verification：現行 main.tf を流すと C-1/C-2/C-3/H-1 で FAIL する = 回帰テストになる、という検証手順まで提示

特筆すべき点として、各強制ポイントの”限界”を隠さず明記していたところがあります。「SCP は IAM ポリシー本文や SG の CIDR を条件評価できないので、IAMワイルドカード(C-1)や SG全開放(C-2)の”予防”は SCP では不可能。CI + 権限境界で代替する」と、できないことをちゃんと書いてくる。ツールを過信させない作りになっていると感じました。

「レビューで見つけた指摘」を「仕組みで再発防止」に変換できるので、構築後の運用・MSPフェーズの品質担保と相性が良いです。

つまずきポイント

• /wa-review が候補に出ない → 起動ディレクトリを確認。.claude/commands/(および .claude/skills/)が直下にある wa-handson で claude を起動しているか。リポジトリのルートで起動すると出ません
• フルレビューが重い・長い → まず quick review、もしくは「security と reliability だけ」のようにピラー限定で
• スコアが想定より厳しい → コード上の environment 値が criticality に影響します(Step 5 の注意点参照)
• このサンプルは絶対にデプロイしないこと(README にも警告あり。検証・評価専用です)

実際の案件での具体的な活用方法

脆弱サンプルで挙動を掴んだら、次は実案件です。ここでは、顧客向けのインフラ設計・構築を Terraform で回す前提で、フェーズごとの使いどころを整理します。

1. 提案・見積フェーズ:構成の妥当性とトレードオフを先に固める

構成図を引く段階で architecture-decision-record と wa-builder が効きます。「なぜこの構成にしたか」をピラー影響つきの ADR として残しておくと、後工程での「これ何でこうしたんだっけ?」が激減します。

• wa-builder … 構成の可視化(構成図・決定木・改善ロードマップ)+ WAの観点整理
• architecture-decision-record … 「Single-AZ にした理由」「NAT Gateway ではなく VPC エンドポイントを選んだ理由」などを、コスト×信頼性のトレードオフとして明文化

見積の複数パターン(松竹梅)を出すときも、「この差分は主に信頼性ピラーのコスト」と WA の言葉で説明できると、顧客・社内レビューどちらにも通しやすくなります。

2. 設計・構築フェーズ:PR 前のセルフレビューに組み込む

environments/modules 構成のリポジトリに install.sh ... --tool claude-code を一発入れておき、PR を出す前に自分で /wa-review(まずは quick)を流す のがおすすめの運用です。

• まず quick review で全ピラーの当たりを取る
• 弱かったピラーだけ「security と reliability だけフルで」とピラー限定で深掘り
• 所見には必ず file:line の根拠が付くので、指摘を鵜呑みにせず自分で確認してから直せる

「レビューで先輩に言われる前に、自分で先回りして潰す」用途に向いています。SG の 0.0.0.0/0、IAM のワイルドカード、暗号化漏れ、バックアップ未設定あたりは機械的に拾ってくれるので、人間のレビューを本質的な設計議論に集中させられます。

3. チーム標準を steering / CLAUDE.md に足す

個人的に特に有用だと感じた点です。導入される CLAUDE.md(や Kiro の steering)は 自分たちのチーム規約を追記できる ので、汎用的な WA ガイドを「自チームの物差し」に育てられます。

たとえば以下のような規約を書き足しておくと、レビュー結果がチーム標準に沿ったものになります。

• tfvars を使わない
• IAM / SG ルールは standalone リソースで追記型(additive)にする
• 既存インフラは data 参照で扱う
• ディレクトリは environments / modules 構成に統一する

WA という「業界標準」の上に「チーム標準」を薄く重ねられるのが、実務での活用もイメージしやすく良いと思いました。

4. 顧客提出ドキュメントの裏付けに使う

詳細設計書に「WA 観点での考慮」を求められる案件は多いですが、/wa-review のレポート(ピラー別スコアカード + 根拠 + 優先度付き改善計画)は、そのまま設計書の WA セクションの下地になります。もちろんそのまま貼るのではなく、根拠を人間が確認・取捨選択したうえで清書する前提です。

5. 構築後の継続的統制:wa-guardrails でドリフトを防ぐ

構築して終わり、ではなく「その後もWA準拠を保つ」ためのガードレールを wa-guardrails で生成できます。

• AWS Config rules … 暗号化必須・パブリック公開禁止などの検知
• SCP … 組織レベルでの予防的統制
• CI チェック … PR 段階で tfsec / checkov 的な観点を機械化

「レビューで見つけた違反」を「二度と混入させない仕組み」に変換できるので、MSP・運用フェーズの品質担保でもそのまま活用できそうです。

6. 社内ナレッジ共有・勉強会のネタに

スキルの中身(SKILL.md)自体が、WA の設問→BP→根拠の探し方を体系立てた良質な教材です。勉強会等で「AIにWAレビューをやらせてみる」ハンズオンとして使うと、WA そのものの学習にもなります。evals/ で「スキルあり/なし」の差を自分たちのモデルで再現して見せると、導入の説明材料にもなります。

実運用の注意:出力はあくまで下書きです。特に顧客提出物や本番適用前は、file:line の根拠を必ず人間が確認し、案件固有の要件(コンプラ・SLA・既存構成の制約)と突き合わせてください。WA は「一般解」であって「その案件の最適解」ではないので、business criticality を正しく伝える(内部ツールなら standard、基幹なら critical)ことで過剰・過小な指摘を避けられます。

まとめ・所感

「WAレビューの自動化」というと大げさに聞こえますが、このリポジトリの本質は WAの知識をAIエージェントの“常識”として持たせる ことだと感じました。設計レビューを別フェーズにせず、コードを書きながら継続的にガイドが効く——という方向性は、IaC を日常的に書く立場としてかなり実感に合います。

特に良いと思ったのは、

• 単一ソース → 13ツール の設計で、チームのツールがバラバラでも同じ基準を共有できる
• トークン戦略を仕組みとして組み込んでいる(現実のコンテキスト制約に向き合っている)
• eval が同梱されていて、効果を自分の環境・モデルで再現・検証できる

の3点。普段の Terraform プロジェクトに install.sh ... --tool claude-code を一発打っておくだけで、/wa-review という共通の物差しが手に入る、というのは導入コストの低さも含めて試す価値があると思います。

今回の検証でも、脆弱サンプルの仕込み全項目 + α を根拠(file:line)つきで検出し、wa-guardrails で予防の仕組みまで生成できました。一方で、environment の値でスコアが左右されたり、出力はあくまで下書きで人間の確認が要る、という現実的な注意点も見えました。「検出してくれる」ではなく「先回りして潰す物差しを共通化する」ツールとして捉えると、実務での位置づけがしっくりきます。

まずは脆弱サンプルで挙動を掴んで、慣れたら自分の(本物の)プロジェクトに quick review → ピラー限定深掘り、という流れで使っていくのが良さそうです。

参考リンク

• リポジトリ
• AWS Well-Architected Framework
• Agent Skills 仕様
• skills.sh(AIエージェント向けスキルディレクトリ)