7月14日、Ibrahim Cesarが「How We Taught Kiro the AWS Well-Architected Framework」と題した記事を公開した。この記事では、AIコーディングエージェントにAWS Well-Architected Frameworkを体系的に適用させるためのスキル設計と、再現率15%から100%への改善プロセスについて詳しく紹介されている。
「レビューが網羅的に見える」という罠
AIコーディングエージェントはコードを書くのは得意だが、「組織のアーキテクチャ基準に沿ったコードを書く」のは別の話だ。何も設定せずにS3バケットを作らせれば、暗号化なし・バージョニングなし・オープンなバケットポリシーのものが返ってくる。間違いではない。ただ「あなたの世界での正解」を知らないだけだ。
Ibrahim Cesarは約1年間、Kiro（AWSが開発するAIコーディングエージェント）を日常的に使い続ける中で、より根深い問題に気づいた。
AIエージェントにWell-Architectedレビューを依頼すると、常に適用すべきベストプラクティスの15%しか指摘しない——にもかかわらず、レポートは網羅的に見える。
AWS Well-Architected Frameworkには6つの柱（運用上の優秀性、セキュリティ、信頼性、パフォーマンス効率、コスト最適化、サステナビリティ）にまたがる307個のベストプラクティスが存在する。標準的なMCPベースのアプローチでレビューを依頼すると、エージェントは「307すべてを評価せよ」と明示的に指示しても、20〜60個で止まる。レポートには見出し・表・重大度ラベル・具体的な推奨事項が並び、読んだ開発者は85%が欠落しているとは気づかない。
これは根拠の薄い安心感をチームに与え、不完全なアセスメントに基づく意思決定を招く。
問題の本質は「プロンプトの質」ではない
なぜ止まるのか。エージェントに「307のベストプラクティスをすべて評価せよ」という広範なタスクを与えると、20〜30個を挙げた時点で「一貫性のある完全そうなレポート」を書くのに十分な材料が揃う。モデルが持つ簡潔さへの傾向が、明示的な網羅性の指示に勝ってしまう。
CesarはAlan Pearlisのエピグラム集（Epigrams on Programming、1982年）から一節を引用して説明する。
「10個のデータ構造に対して10個の関数を持つより、1つのデータ構造に対して100個の関数を持つ方が良い」
エージェントに置き換えれば「断片を検索しながら進む多数のエージェントより、完全なデータセットをコンテキストに持つ1つのエージェントの方が良い」となる。エージェントが全データを持っていればベストプラクティスを見落とせない。検索しながら進めば「十分」になった時点で止まる。
解決策はより良いプロンプトではなく、エージェントアーキテクチャそのものの変更だ。
3層構造で再現率を100%に引き上げる
この問題を解決するために開発されたのが、オープンソースプロジェクト aws-samples/sample-well-architected-skills-and-steering の wa-review スキルだ。以下の3層構造で設計されている。
1. スコープ分解
307のベストプラクティスを1つのエージェントに渡すのではなく、Well-Architectedの6つの柱それぞれに対して並列でサブエージェントを起動する。各サブエージェントは自分の柱のリファレンスファイル（約150〜580KB）だけをロードし、その柱内の30〜55のベストプラクティスを評価する。スコープを狭くすることで、そのスコープ内での網羅性を担保する。
並列処理も重要で、元記事によれば全体の所要時間は最も遅い柱（約11分）で頭打ちになり、6柱の合計時間（約66分）にはならない。
2. 構造化された出力フォーマット
各サブエージェントはナラティブな要約ではなく、ベストプラクティス1行につき1行のmarkdownテーブル（BP ID | ステータス | 重大度 | 根拠 | 推奨事項）を返すよう要求される。5段落ではなく50行。これにより出力時にモデルが分析を圧縮するのを防ぐ。
3. アセンブリの契約
6つのサブエージェントのレポートを受け取るトップレベルのエージェントには、300行超をフィルタリングなしで連結した「Full BP Ledger」を生成することが明示的に要求される。短いナラティブに「要約」することを禁じるルールが設けられている。
この3層により、再現率は15%から100%、F1スコアは0.26から0.96に向上した。これらの数値は実際の claude -p CLIを使った18回の実行で計測された、元記事記載の数値だ。
| 構成 | 平均F1 | 再現率 |
|---|---|---|
| スキルあり（wa-review v2.2） | 0.960 | 1.00 |
| スキルなし（素のClaude Code CLI） | 0.264 | 0.15 |
評価ハーネス（evals/cli_effectiveness/）もリポジトリに同梱されており、誰でも再現できる。
スキルは「ドキュメント」ではなく「エンコードされたエージェント戦略」
Cesarが強調するのは、このスキルファイルはWell-Architected Frameworkの知識を書いたドキュメントではないという点だ。
- どのタスクを分岐させるか（モノリシックなレビューではなく、柱ごとのサブエージェント）
- どの構造で返すか（ナラティブではなくベストプラクティス単位のテーブル）
- アセンブラが何をすべきか（すべての引用を保持し、圧縮しない）
静的なドキュメントはエージェントにベストプラクティスの「知識」を与える。スキルファイルはベストプラクティスについて「どう推論するか」を変える。だからこそ、設計対象外のモデルや未テストのランタイムでも機能する。
プロジェクトは現在5つのコアスキル（wa-review、wa-builder、wa-guardrailsほか）、27のレンズ拡張（サーバーレス、GenAI、機械学習、SaaS等）、14のサポートツール（Kiro、Claude Code、Cursor、GitHub Copilot等）を含む。GitHubスター数は記事公開時点で約219に達している（スター数はリアルタイムで変動するため、現在の数値はリポジトリで確認されたい）。
詳細はHow We Taught Kiro the AWS Well-Architected Frameworkを参照していただきたい。
