💡

Claude Codで実現する「対話駆動開発」 - Part 1: 実践編

2025/11/03に公開

 💡 はじめに：最も難しいフェーズをAIと協働するソフトウェア開発において、要件定義はシステムの成否を左右する最も重要なフェーズですが、同時に頭の中のアイデアを具体的な仕様に落とし込むという、最も困難なプロセスでもあります。
本記事では、GCP環境設計支援AIエージェントシステムの仕様書を作成する過程で、Claude Codeがどのように要件の曖昧さを解消し、最終的に5,000行超の包括的な仕様書を完成させたかを、解説します。

 🧩 1. プロジェクトの初期設定とAIへの問いかけ
 1.1 プロジェクトの出発点：漠然としたアイデア現在私はTerraformコード ↔ Excel設計書双方向変換ツール の実装を進めている最中です。しかし、このツールには「Terraformを書けるエンジニア」「インフラ設計・構築のことを理解しているエンジニア」じゃないと変換対象となるインプットコードやドキュメントを用意できない、という課題がありました。

解決したい課題： 設計経験が浅いエンジニアでも、AIエージェントの支援で高品質な設計書を作成できるようにしたい。

 1.2 Claude Codeへの最初のインプット私は、頭の中の構想を「バイブス」に任せて、以下のような大まかな初期要件をClaude Codeに投げかけました。
@README.md のツールによってExcelの設計書またはTerraformコードをもとに
様々な設計書を作成できるようになりました。

しかし、そもそもGoogle Cloudやインフラ設計に精通したエンジニアが
当社には少なく、Excelの設計書やTerraformコードを作成することが困難です。

この問題を解決するために、AIエージェントを活用して設計の支援を
できるようにしたいです。

AIエージェントは
  オーケストレータ
  設計支援サブエージェント
  設計指針参照サブエージェント
  Excel設計書作成サブエージェント
  Terraformコード作成サブエージェント
  システム構成図作成サブエージェント
  コスト計算サブエージェント
などで構成されます。

各エージェントは、このプロジェクトで作成した機能を含む、
さまざまなツールを使用してエージェントの役割を担います。

ツールには例えば次のようなものを用意します。
・既存のTerraform↔Excel変換ツール
・社内の設計指針を読み込み内容を参照するツール
・システム構成図作成ツール
・コスト計算ツール

前提として
・Google Cloud上で動作する
・AIエージェントにはADK及びAgent Engineを使用する
・RAGシステム構築にはVertex AI Searchを使用し、そのデータストアにはGCSを使用する

UIについて
最終的には、専用のフロントエンドAppを作成して、そこでユーザーが対話できるように
していきます。しかし、現時点ではまだプロトタイプレベルの構築段階なので、
このPythonを中心として作ったプロジェクト内でUIも動作させることとする。
最終形態を見越して、UIとバックエンドとして分離できるようにする。

このアイデアに対して、不足していたり、追加した方が良いエージェントや
ツールについて検討し、あなたのアイデアも必要に応じて追加し、
この構想を形にしてください。

検討結果と仕様はドキュメント化してください。私や、他のエンジニアに
レビューしてもらうために使用します。

もし不明点等があれば質問をしてください。
インタラクティブな活動を通じてこの構想を形にしていきましょう。

この時点のプロンプトの状態:
✅ 解決したい課題、技術スタックは明確。
❌ 具体的なユースケース、エージェント間の連携方法、UXの進め方が不明確。


 🗣️ 2. Claude Codeからの「システムの本質を問う質問」私の漠然とした要件に対し、Claude Codeは自律的に「不明点」を特定し、AskUserQuestionツールというClaude Codeの内部ツールを活用した構造化された質問を投げかけてきました。

後からClaude Code自身に確認したのですが、
プロンプト中のもし不明点等があれば質問をしてください。
インタラクティブな活動を通じてこの構想を形にしていきましょう。
というフレーズがこれが当記事のメインテーマである対話駆動による要件精緻化の決定的なトリガーとなったようです。

 質問1: 想定ユーザーClaude Codeはまず、このシステムが具体的には誰が使い、その人はどんな特性や特徴を持つのか？という最も根本的な部分を明確にしようとしました。
←  ☒ 想定ユーザー  ☐ MVPスコープ  ☐ 設計指針形式  ☐ UI形式  ✔ Submit  →

このシステムの主な利用者は誰を想定していますか？
❯ 1. 非エンジニア（企画・PM等）
     インフラの知識がほとんどない、要件定義や企画担当者
  2. 初級エンジニア
     基礎知識はあるが、GCP/Terraformの経験が浅いエンジニア
  3. 中級エンジニア
     ある程度の経験があり、設計レビューやベストプラクティス確認が目的
  4. 混在（全レベル）
     様々なスキルレベルのユーザーが利用する
  5. Type something.

Enter to select · Tab/Arrow keys to navigate · Esc to cancel

質問の威力： この質問により、システムの最重要指標である**「想定ユーザー」（例：初級エンジニア）が明確になりました。これにより、AIが提供すべき回答のレベル（詳細な技術解説の必要性）や、対話のトーン（親切な誘導）といったUX設計の根幹**が決定されました。

 質問2: MVPスコープ次に、私の持つ「設計支援」という漠然としたアイデアを、具体的な**「最小限の実用可能な機能」（MVPスコープ）**へと落とし込むための質問を投げかけました。
←  ☒ 想定ユーザー  ☒ MVPスコープ  ☐ 設計指針形式  ☐ UI形式  ✔ Submit  →

最初のMVP（最小実用製品）で実現したい主なユースケースは？
  1. [✔] 要件からExcel設計書生成
     自然言語の要件からExcel設計書を生成する対話型支援
❯ 2. [✔] 既存設計のレビュー
     作成済みのExcel/Terraformを社内指針に基づいてレビュー
  3. [ ] コスト最適化提案
     設計のコスト分析と最適化案の提示
  4. [ ] 設計Q&A
     GCP/Terraformの設計に関する質問応答
  5. [ ] Type something

Enter to select · Tab/Arrow keys to navigate · Esc to cancel
質問の威力： この質問で、MVPの核となる機能（要件からの設計書生成と既存設計のレビュー）が確定しました。これにより、後の設計書でPhase 5-7（MVP）とPhase 8以降の拡張という具体的な実装計画のスコープ分離が可能になりました。

 質問3: 設計指針形式続いて、核となる機能の一つである「RAGサブエージェント」が参照するインプットデータ（社内指針）の形式と状態について深掘りしました。
←  ☒ 想定ユーザー  ☒ MVPスコープ  ☐ 設計指針形式  ☐ UI形式  ✔ Submit  →

 社内の設計指針はどのような形式で管理されていますか？
❯ 1. Markdown/テキスト
     Markdown、テキストファイル、Confluenceなどのドキュメント
  2. Excel/スプレッドシート ✔
     Excelやスプレッドシートで管理されたルール集
  3. 未整備
     まだ体系化されておらず、これから整備する予定
  4. 混在
     複数の形式が混在している
  5. Type something.

Enter to select · Tab/Arrow keys to navigate · Esc to cancel
質問の威力： この質問により、RAGシステムが取り扱うデータの形式（Markdown/テキストとExcel/スプレッドシートの混在）が明確になりました。これは、後の設計書でRAGシステムのデータストア設計や、Vertex AI Searchのインデックス構成の基盤を確定させる上で不可欠な情報でした。

 質問4: UI形式最後に、システムの「顔」となるユーザーインターフェース（UI）の形式について、具体的な選択肢を提示して、初期開発の技術スタックを確定させようとしました。
←  ☒ 想定ユーザー  ☒ MVPスコープ  ☐ 設計指針形式  ☐ UI形式  ✔ Submit  →

プロトタイプUIはどのような形式を想定していますか？
  1. CLIチャット
     ターミナル上での対話型CLI（Claude Codeのような形式）
❯ 2. Webベースチャット
     Streamlit/Gradio等の軽量WebフレームワークでのチャットUI
  3. Jupyter Notebook
     Notebook形式での対話的な実行環境
  4. REST API + 簡易UI
     バックエンドAPIを先に作り、最小限のフロントエンド
  5. Type something.

Enter to select · Tab/Arrow keys to navigate · Esc to cancel
質問の威力： この質問により、プロトタイプの形式が 「Webベースチャット」に決定され、Streamlit/Gradioなどのフロントエンド技術の選定や、エージェントとのAPI連携戦略 といった技術仕様の方向性が明確になりました。

 📝 3. 要件精緻化から仕様書デリバリーまでClaude Codeは、これらの回答を基に、受け身ではなく能動的な提案と段階的な詳細化を通じて、実装可能レベルの仕様書を生成しました。

 3.1 構造の提案と承認Claude Codeはすぐに3つのドキュメント構造を提案し、私の承認を得てから作業を開始しました。

AI_AGENT_SYSTEM_SPEC.md：システム全体仕様、エージェント構成、ユースケース

TOOL_SPECIFICATIONS.md：全ツールの詳細API仕様、入出力定義

AGENT_INTERACTION_FLOW.md：エージェント間の対話フロー、ユーザージャーニー

 3.2 段階的な詳細化の実行Claude Codeは、大まかな要件を以下のレベルまで詳細化しました。


詳細化の対象
私の初期要件
Claude Codeが生成した詳細


ユーザージャーニー
「ゼロから設計したい」

10ステップの具体的なフロー（要件入力 \to 初期質問 \to RAG検索 \to 初期設計生成 \to ユーザー提示 \to ...）

エージェント設計
「オーケストレータエージェント」
各エージェントの責務、状態管理、サブエージェントとの連携方法をPythonクラス形式で詳細定義。

ツール仕様
「既存ツールを使う」

15個のツール全てに対して、tool_name, input_schema, output_schema, error_handling をJSON形式で定義。

RAGシステム
「Vertex AI Searchを使う」

3種類のデータストア（セキュリティ、ネットワーク、過去事例）のGCSパス、ドキュメント形式、検索クエリ生成戦略まで定義。


 3.3 最終成果物：実装可能レベルの包括的仕様書わずか約1時間の対話で、以下のドキュメントが完成しました。


ドキュメント
行数
備考


AI_AGENT_SYSTEM_SPEC.md
2,082行

10エージェント、15ツール、14週間の実装計画を含む

TOOL_SPECIFICATIONS.md
1,736行

全15ツールの詳細API仕様（入出力スキーマ、エラーハンドリング）

AGENT_INTERACTION_FLOW.md
1,459行
エージェント間のメッセージフロー、状態遷移図

合計
5,277行
実務で使用可能な包括的な仕様書


 3.4 即座のフィードバックループと設計見直し最も開発者体験（DX）が高かったのは、最新技術情報に対する柔軟な対応力です。
私が「Agent Engine Built-in Tools（セッション管理、VertexAISearchなど）の利用で設計が簡素化できる」という新しい情報をフィードバックした際：
Claude CodeはWeb検索を実施し、最新ドキュメント（3つのURL）で情報を確認。

「この理解で正しいか？」 と私に再確認。
承認後、約15分で全5,277行のドキュメントを一括更新し、v1.0 vs v2.0の変更点サマリーまで作成しました。
この 「情報収集 → 影響分析 → 設計見直し → 全体更新」 のサイクルが15分で完了することは、従来の手動プロセスではありえない速度です。

 🌟 4. 開発者体験（DX）としての評価
 4.1 驚異的な時間削減と品質向上

項目
従来の要件定義プロセス（手動）
Claude Codeとの対話プロセス


作業時間
8〜12時間 + 待ち時間
約1時間

時間削減
-
約90%

ドキュメント行数
500〜1,000行（簡易版）
5,277行（実装可能レベルの詳細版）

品質
見落とし、一貫性のばらつきあり
包括的かつ完全に一貫

最新技術反映
手動での調査、反映が必要
Web検索で自動反映


 4.2 理想的な開発パートナーの特性Claude Codeとの対話体験は、単なるツールの使用ではなく、「優秀な共同開発者」 とのペアプログラミングのようなものでした。


Claude Codeが提供した価値
従来の開発者が苦労していた点


的確な質問と具体例
自分が言語化できていない要件や、考慮漏れの観点（UX設計、ガバナンス）

段階的な深掘り
一度に全ての要件を考えようとして圧倒されること

能動的な提案
ドキュメント構造や実装方針を一から考える手間

即座のフィードバックループ
新技術の調査、影響分析、全ドキュメントの更新作業


 4.3 まとめ：AI協働時代の開発近年、Claude CodeやCodeXによる、アプリケーションコードの自動生成、仕様駆動開発などがどんどん進化し続けています。これらのツールに適切なプロンプトを与えることによって、更に仕様作成や要件や要求の定義活動さえも大幅に効率化できる余地があることが今回分かりました。
我々エンジニアには今まで以上に、
解決したい課題は何かを洞察する能力
そのためにはどのような解決方法があり得るかを考え抜くためのドメイン知識
最適なソリューションを設計するための技術に関する知識
それを適切な形で生成AIに伝えるプロンプトエンジニアリング力
ということが求められるようになっていくと強く感じます。

詳細化の対象	私の初期要件	Claude Codeが生成した詳細
ユーザージャーニー	「ゼロから設計したい」	10ステップの具体的なフロー（要件入力 $\to$ 初期質問 $\to$ RAG検索 $\to$ 初期設計生成 $\to$ ユーザー提示 $\to$ ...）
エージェント設計	「オーケストレータエージェント」	各エージェントの責務、状態管理、サブエージェントとの連携方法をPythonクラス形式で詳細定義。
ツール仕様	「既存ツールを使う」	15個のツール全てに対して、`tool_name`, `input_schema`, `output_schema`, `error_handling` をJSON形式で定義。
RAGシステム	「Vertex AI Searchを使う」	3種類のデータストア（セキュリティ、ネットワーク、過去事例）のGCSパス、ドキュメント形式、検索クエリ生成戦略まで定義。

ドキュメント	行数	備考
AI_AGENT_SYSTEM_SPEC.md	2,082行	10エージェント、15ツール、14週間の実装計画を含む
TOOL_SPECIFICATIONS.md	1,736行	全15ツールの詳細API仕様（入出力スキーマ、エラーハンドリング）
AGENT_INTERACTION_FLOW.md	1,459行	エージェント間のメッセージフロー、状態遷移図
合計	5,277行	実務で使用可能な包括的な仕様書

項目	従来の要件定義プロセス（手動）	Claude Codeとの対話プロセス
作業時間	8〜12時間 + 待ち時間	約1時間
時間削減	-	約90%
ドキュメント行数	500〜1,000行（簡易版）	5,277行（実装可能レベルの詳細版）
品質	見落とし、一貫性のばらつきあり	包括的かつ完全に一貫
最新技術反映	手動での調査、反映が必要	Web検索で自動反映

Claude Codeが提供した価値	従来の開発者が苦労していた点
的確な質問と具体例	自分が言語化できていない要件や、考慮漏れの観点（UX設計、ガバナンス）
段階的な深掘り	一度に全ての要件を考えようとして圧倒されること
能動的な提案	ドキュメント構造や実装方針を一から考える手間
即座のフィードバックループ	新技術の調査、影響分析、全ドキュメントの更新作業

💡 はじめに：最も難しいフェーズをAIと協働する

🧩 1. プロジェクトの初期設定とAIへの問いかけ

1.1 プロジェクトの出発点：漠然としたアイデア

1.2 Claude Codeへの最初のインプット

🗣️ 2. Claude Codeからの「システムの本質を問う質問」

質問1: 想定ユーザー

質問2: MVPスコープ

質問3: 設計指針形式

質問4: UI形式

📝 3. 要件精緻化から仕様書デリバリーまで

3.1 構造の提案と承認

3.2 段階的な詳細化の実行

3.3 最終成果物：実装可能レベルの包括的仕様書

3.4 即座のフィードバックループと設計見直し

🌟 4. 開発者体験（DX）としての評価

4.1 驚異的な時間削減と品質向上

4.2 理想的な開発パートナーの特性

4.3 まとめ：AI協働時代の開発

Discussion