この記事はシリーズ構成となっており▶️マークが現在の記事となります
プロローグ
AIは「新人」であり「Web開発」である - 成果を最大化する生成AIとの付き合い方
第1部 僕がAIを最高の相棒にするまで：ブログ運営改善プロジェクト全記録
第2部 PMP資格の学習教材を、AIを相棒にしてゼロから作り上げる
第3部 AIを相棒にしたシステム開発プロジェクト全記録
【第1回】AIとの「壁打ち」が、曖昧な要求を「勝てる仕様書」に変えるまで
【第2回】ゼロから始めるWebアプリ設計：AIと一緒にモダンなAWSアーキテクチャを描く
▶️【第3回】AIにコードを書かせる前に人間がすべきこと：高品質な成果物を生む「設計書」の作り方
【第4回】巨大なタスクを分解する技術：AIに「開発ロードマップ」を作らせてプロジェクト全体を見通す
【第5回】ログイン機能のセキュリティと利便性、その最適なバランス
【第6回】開発プロセスにおけるAIとの協働：ログイン機能設計のケーススタディ
【第7回】認証管理の弱点とボトルネック：AIは「見えないリスク」をどう可視化するか【第8回】1つの対話から無限のコンテンツを：AIとの開発プロセスを新人研修資料やインフォグラフィックに変える方法
テーマ: 詳細設計フェーズ
前回の記事はこちら: https://axis.migalo.co.jp/column/k029
① はじめに（導入）
AIを使えば、驚くほど高速にコードを生成できます。しかし、そのアウトプットは時として「気まぐれ」です。昨日と同じ指示でも今日は違うコードを生成したり、ある機能ではAという設計思想だったのに、別の機能ではBという思想で実装したり…。
このAIの「気まぐれ」に振り回されず、プロジェクト全体で一貫した、高品質なコードを生成させるにはどうすれば良いのでしょうか？その答えは、AIにコードを書かせる 「前」 にあります。
この記事では、AI駆動開発を成功させるための鍵となる 「ガードレール」 、すなわちAIに守らせるべきルールを定義した各種「設計書」の重要性に焦点を当てます。AIを単なるコード生成マシンではなく、優秀な開発パートナーへと育てるための具体的なプロセスを、実際の対話ログと共にご紹介します。
この記事を読めば、AIの能力を最大限に引き出し、プロジェクトの品質を担保するための具体的な方法論が学べるはずです。
② 課題・目的
第2回で、私たちはAIと共にモダンなAWSアーキテクチャという名の「地図」を手に入れました。しかし、地図があるだけでは目的地にはたどり着けません。実際に道を造るための、より詳細な「設計図」が必要です。
【この時点での課題】
・AIが生成するコードの品質やスタイルに一貫性がない。
・エラーの返し方やログの出力形式など、アプリケーションの共通ルールが未定義である。
・このままAIに実装を任せると、場当たり的で保守性の低いコードが量産されてしまう危険性がある。
AIは非常に優秀ですが、プロジェクト全体の思想や細かいルールを「察して」はくれません。明確な指示がなければ、その場その場で最適だと判断したコードを生成してしまいます。
そこで、今回の目的を以下のように設定しました。
目的: AIが高品質なコードを一貫して生成するための 「ガードレール」となる各種設計書を定義すること。
課題: AIとの対話を通じて、AI駆動開発に最適化されたプロジェクトのルールと構造を確立すること。
この課題を解決するため、AIとの対話を通じて、プロジェクトの「法律」とも言えるルール作りを進めていきました。
③ AIへの指示（プロンプト）
まず、今後の開発を見据え、プロジェクト全体のディレクトリ構成についてAIに相談することから始めました。
【プロンプト】 AI駆動開発で必要な資料を作成していくにあたりディレクトリ構成を定めたいです。 現在のディレクトリは下記です
root 10.要件定義書 20.システム構成図 30.開発ロードマップ …
現在の構成で改善案があれば指摘して下さい。 その内容を踏まえて、全体のディレクトリ構成を提案して下さい。
【プロンプトのポイント】
・現状と理想のギャップを問う: 現在のシンプルな構成を提示し、「改善案」を問いかけることで、AIに能動的な提案を促しています。
・目的を伝える: 「AI駆動開発で」というキーワードを入れることで、AIがその目的を達成するために最適な構成は何か、という視点で考えられるように誘導しています。
④ AIによる生成物（アウトプット）
このプロンプトに対し、Geminiはまず、人間にとって分かりやすい構成案を提示しました。しかし、私はAI駆動開発の成功には、より詳細な「指示書」が必要だと考え、対話を深めていきました。
【Geminiからの初期提案（抜粋）】 人間にとって分かりやすい論理的な構成です。 改善案としては、コードとドキュメントを分離し、docsディレクトリに集約することが考えられます。
【私からの追加指示（要約）】 ありがとう。その構成案を採用します。 ただ、AIにコーディングさせるにあたって、エラーハンドリングやログの設計書がないと、成果物にブレが生じると感じています。これらの設計書や、その他AI駆動開発に必要なドキュメントを追加した、より詳細なディレクトリ構成を再度提案してください。
この「壁打ち」を経て、AIは「なぜ」これらのドキュメントが必要かを理解し、AI駆動開発に最適化された、より詳細なディレクトリ構成と、そこに格納されるべき設計書のリストを提案しました。
【Geminiによる最終提案（抜粋）】 非常に重要なご指摘です。おっしゃる通り、「エラーハンドリング設計書」と「ログ設計書」は、AIに実装を依頼する上で不可欠と言えるドキュメントです。（中略） AI駆動開発を成功させる鍵は、人間が「判断」や「設計」を行い、その結果を曖昧さなくAIに伝えられるかにかかっています。
提案するディレクトリ構成:
(root)
├── docs/
│ ├── 03_design/ # 詳細設計
│ │ ├── api/
│ │ └── database/
│ ├── 05_guidelines/ # (新規) 規約・指針
│ │ ├── coding_standards.md
│ │ ├── error_handling_design.md
│ │ └── logging_design.md
│ └── 06_security/ # (新規) セキュリティ設計
│ └── security_design.md
├── frontend/
├── backend/
└── infrastructure/【生成物のポイント】
・対話による課題の深掘り: 人間からのフィードバック（「成果物にブレが生じる」）を受け、AIは当初の提案を修正し、より目的に合致したアウトプットを生成しました。
・「Why」の言語化: AIは単に構成案を提示するだけでなく、「なぜこれらの設計書がAI駆動開発に重要なのか」という理由まで明確に言語化してくれました。これは、チーム内での合意形成にも非常に役立ちます。
⑤ 考察・ポイント
今回の対話から、AIを優秀な開発パートナーに育てる上で、以下の3つの重要なポイントが見えてきました。
・人間は「ルールメーカー」に徹する AIに質の高い仕事をさせるための最も重要な仕事は、明確なルール（制約条件）を最初に定義することです。エラーハンドリング、ログ、コーディング規約といった「ガードレール」を人間が定めることで、AIはその範囲内で、一貫性のある高品質なコードを自律的に生成し始めます。
・AIは「超優秀な新人」である 生成AIは、最新の知識を持ち、驚異的なスピードでコードを書けますが、プロジェクト固有の「暗黙のルール」や「文化」は知りません。その点で、AIは「超優秀な新人」に似ています。だからこそ、私たちは「明確な指示書（設計書）」と「手本となるコード（サンプルコード）」を最初に示し、期待するアウトプットの基準を教える必要があるのです。
・設計書は「AIへのプロンプト」そのものである AI駆動開発において、詳細な設計書はもはや人間だけのものではありません。構造化された設計書（特にOpenAPIやデータベーススキーマ定義など）は、それ自体がAIへの最も正確で強力なプロンプトとなります。良い設計書を書くことが、良いアウトプットを得るための最短距離になるのです。
あなたのプロジェクトで試すには
あなたのチームのコーディング規約や、API設計のルールがあれば、それをAIに読み込ませてみましょう。そして、「これから〇〇の機能を実装します。この規約を守って、一貫性のあるコードを書いてください」と指示してみてください。最初に「ガードレール」を示すことが、AIの品質を安定させる鍵です。
⑥ まとめと次回予告
今回は、AIに高品質なコードを一貫して書かせるために、人間が事前に定義すべき「ガードレール」としての各種設計書の重要性について解説しました。AIを正しく導くためのルール作りこそ、これからのエンジニアに求められる重要なスキルと言えるでしょう。
さて、要件、アーキテクチャ、そして詳細設計という「準備」は整いました。しかし、この巨大な山を前にして、どこから登り始めるのか？ 次は、プロジェクトを具体的なタスクに落とし込み、開発をスタートさせる「計画」のフェーズです。
次回、 「第4回：巨大なタスクを分解する技術：AIに「開発ロードマップ」を作らせてプロジェクト全体を見通す」 では、この膨大なプロジェクトを、管理可能な小さなタスクにどう分解し、計画を立てていくかをAIと共に実践します。ご期待ください。
