本記事は、現在進行中のプロジェクトから得られた途中経過の知見をまとめたものです。完了事例の報告ではなく、試行錯誤しながら見えてきたことの共有です。
はじめに
AWS上でCDK（TypeScript）による基盤設計・構築を進める中で、KiroとClaude Codeを組み合わせた仕様駆動開発を実践しています。本記事では、その中で見えてきた「AIに書かせる前に何を設計するか」という問いへの現時点の答えを共有します。
前提として、今回の取り組みは**AWS上での基盤構築（小規模）**であり、基本的にコードは自分では書かず、AIに生成させるスタイルで進めています。一般的な要件定義→設計→コード生成→構築→テストの流れに、AI固有の設計作業を加えた構成です。
Kiroとは、Claude Codeとは
KiroはAWSが提供するVS CodeベースのAIエージェント型IDE（2025年リリース）で、「仕様駆動開発（Spec-Driven Development）」を特徴とします。コードを書く前に、requirements（何を作るか）→design（どう設計するか）→tasks（実装タスクの分解）という3層の仕様書を整備し、それをもとにAIがコードを生成します。
Kiroは4つのコンポーネントで構成されています。
| コンポーネント | 役割 |
|---|---|
| Steering | プロジェクトルールをAIに常時注入するMarkdownファイル群 |
| Specs | 機能単位の仕様書（requirements / design / tasksの3点セット） |
| Skills | 繰り返し作業を定義した再利用可能なワークフロー |
| Hooks | ファイル保存・AI応答完了（agentStop）などのイベントで自動実行される品質チェック |
Claude CodeはAnthropicのCLIベースのAIエージェントで、本実践ではKiroの補完役として使います。Kiroが「設計してコードを生成する」のに対し、Claude Codeは「計画・多角的レビュー・人間向けドキュメント生成」を担当します。Task tool（サブエージェント）を使って複数AIエージェントを並列実行できるのが大きな特徴です。
仕様駆動開発フロー — 各フェーズの人間承認ゲート
各フェーズにAIによる多角的レビューと人間による承認ゲートを設けています。最大のリスクは「人間が確認できるタイミングに確認しないこと」。AIが自走できる環境を作るほど、人間が介入する設計が重要になります。
Steeringがすべてを決める
Steeringを一言で言うと、**「Kiroへの常時コンテキスト注入ファイル」**です。
Kiroはチャットセッションをまたいで記憶をリセットしますが、inclusion:always のSteeringだけは毎回自動で読み込まれます。Steeringに書いてあることはKiroが「常識」として保持し、書いていないことはセッションのたびにゼロから考え始めます。
実際にSteeringを整備する前は、Kiroが汎用的なAWS実装を生成し続け、ガバメントクラウド固有の制約（SCPブロック対象サービス・ISMAP関連設定）を毎回レビューで指摘する状況でした。Steeringに制約を明文化してからは、その種の指摘が大幅に減り、レビューの論点が本質的な設計判断にシフトしました。
記述例（WHEN/SHALL記法）
WHEN S3バケットを作成する場合 SHALL 暗号化（SSE-S3）を必ず有効にすること
本実践では .kiro/steering/ 配下に10ファイルを配置しています。
.kiro/steering/
├── product.md # プロダクト概要・目標（未確定事項は仮置き形式）
├── structure.md # リポジトリ構成・スタック分割（未確定事項は仮置き形式）
├── tech.md # 技術スタック・ガバメントクラウド固有制約
├── config-management.md # Config管理ルール
├── branch-strategy.md # ブランチ戦略・コード規約
├── security-controls.md # セキュリティ統制 ← 最上位優先
├── cdk-standards.md # CDK設計標準
├── ai-agent-boundaries.md # AIエージェントの権限境界
├── ops-change-constraints.md # 運用期変更制約
└── spec/operations.md # DR・障害対応フロー
Steeringの作成プロセスもポイントです。ゼロから書くのではなく、過去案件のコード・設計書から「暗黙知を形式知化する」というプロセスを経て作成しました。
Hooks（Kiro）とSkills（Kiro）で品質を自動化する
Hooks（Kiro） はイベント（agentStop・file-edit など）をトリガーに自動実行される品質チェックです。本実践では12本のHookを優先度別に設計しています。
.kiro/hooks/
├── cdk-nag-mandatory-gate.hook # P0: cdk-nagエラー強制ブロック
├── no-wildcard-iam-check.hook # P0: ワイルドカードIAM検出
├── secret-detection.hook # P0: シークレットハードコード検出
├── typescript-type-check.hook # P0: TypeScript型チェック
├── cdk-synth-check.hook # P1: CDK synthチェック
├── eslint-check.hook # P1: ESLintコードスタイル
├── nag-suppression-audit.hook # P1: NagSuppression増加監視
├── cdk-diff-post-task.hook # P2: Specタスク完了後のCDK diff確認
...（12本体制）
P0のHookは failOnError: true で即時ブロック。自動化できるチェックはAIに任せて、人間は本質的な判断に集中する設計です。
Skills（Kiro） は /security-baseline のようなスラッシュコマンドで呼び出す再利用可能なワークフローです。「誰が実行しても同じ品質になる」ことを意識してスキル化します。本実践ではデプロイ手順・セキュリティチェック・Runbook生成・コスト分析など16本を定義しています。
Claude Codeによる多角的レビューと指摘の取り込み方針
Steering・Spec・コードの各成果物に対して、Claude Codeのエージェントチームで多角的レビューを行います。
各エージェントは網羅性・プロジェクト固有化度・実装可能性・指摘の鋭さの4軸でスコアリングを行います。複数ペルソナが並列でレビューすると相互にトレードオフな指摘が出てきます（例：AWS専門エージェントの指摘がKiro特化エージェント的には「書きすぎ」になるなど）。スコアはあくまで材料であり、最終判断は人間が下します。
**指摘の取り込み方針（Must / Should / Could / Won't）**も設計しています。全件取り込むとドキュメントが肥大化し、全件スキップすると品質リスクが残るためです。
見送った指摘も「なぜ見送ったか」を記録することがトレーサビリティになります。
この多角的レビューから導き出されたKiroが動きやすい設計原則の例：
- Steeringファイルは1本100〜150行以内に保つ（長大だとコンテキストを圧迫）
- Steeringの仮置き項目をゼロにしてから実装に進む
- 常時適用と タスク固有の読み込みを使い分けてコンテキストを節約する
- スタック単位でSpecを独立させる
役割のシフトとコミュニケーション設計
Before: 設計もコードも、実装にかかる時間が最も多い
After: 制約と前提を与えれば、AIが自走して実装する
人間は「仕様の磨き込み / トレードオフ判断 / Steering設計 / レビュアー設計」に集中
作業カテゴリ別の変化の方向感をまとめると：
| カテゴリ | 変化 | 理由 |
|---|---|---|
| CDKコード実装（IaC） | 大きく削減見込み | パターン化・繰り返し構造が多く、仕様駆動との相性が特に高い |
| 設計書の初稿作成 | 大きく削減見込み | 仕様骨格・初稿をAIが生成し、人間はレビューに集中できる |
| Runbook等のドキュメント | 大きく削減見込み | 初稿・更新をAIが担い、初稿作成コストがほぼなくなる |
| テスト設計・実施 | ある程度削減見込み | テストケース自動生成は効果あり。観点設計は人間が担う |
| 調整・レビュー・最終判断 | 小幅な変化 | コミュニケーションや判断はAIに代替できない領域 |
重要なのは、AIが担う作業の割合が増えると、逆説的に「人間同士のコミュニケーション設計」の重要性が増すことです。コード生成はAIに委ねられますが、Steeringの整備・Hooksの設計・Specのレビューは従来以上に精緻な役割設計を必要とします。
AI駆動開発でのチーム構造は、従来の「人が増えるほど調整コストも増加する」モデルから変化する可能性があります。
Steeringというガードレールを全チームで共有することで、各マイクロチームが制約の中で自律的に判断・実行できます。人数が増えても調整コストが線形に増加しないチーム設計が目標です。
従来型開発からの追加検討項目
AI駆動開発を導入する際に従来型開発に追加で必要になった設計項目です。通常の開発では出てこない検討項目がほとんどです。
- Steeringファイルの設計・管理運営: 誰がいつ更新するか、更新ルールを「単独更新可 / 上長Approve必須 / 要相談」のように種別化して事前設計
- Hooksの品質ゲート設計: 設定するだけでは不十分。どのゲートで何をブロックするかの設計と、Day1でのチーム体験セレモニーの実施
- AI生成コード固有のレビュー設計: Hooks自動→CI自動→AI判断→人間→デプロイ後の5段階レビューフロー
- ガバナンスゲートの事前定義: Steering→Spec→コード→Hooks→デプロイ後検証の承認チェーン全体を開発前に合意
- AIツール利用ポリシーの事前合意: AIへのデータ送信可否基準をプロジェクト開始前にステークホルダーと合意
- 成果物形式の変更合意: Markdown形式・GitHub管理への移行は発注者との調整が必要
- チーム体制の見直し: Steering管理者・Skills/Hooks開発者などの新設ロールをPhase 1キックオフ時点で確定
-
ディレクトリ設計の原則変更: AIが参照する
.kiro/と人間が読むdocs/を明確に分離
今後の課題 — 大規模適用の壁
小規模での実践には手応えを感じつつも、大規模案件への適用では以下の課題があります。
まとめ
- Steeringの品質がAI出力品質を直接決定する
- 「書く人」から「設計し、レビューし、自動化する人」へ
- AI生成物は出発点であり完成形ではない。人間が裁定して品質が確定する
本記事の内容はGov-JAWS#7での登壇内容をベースにしています。試行錯誤中の知見であり、今後の実践で変わる部分もあると思いますが、同じような取り組みをされている方の参考になれば幸いです。