レッスン3：コード生成タスクのプロンプト設計——ゼロショットで済まないパターン

このレッスンで学ぶこと

コード生成タスクに特化したプロンプト設計の勘所を押さえる
コンテキストの与え方（関連ファイル添付・リポジトリ全体検索・シンボル参照）の使い分けができる
コード生成の失敗パターン 5 種を識別し、対処できる
タスク分解の粒度（ワンショット vs 3〜5 ステップ分解）を判断できる
Spec-driven development と Vibe Coding を対比で理解し、場面に応じて使い分けられる

前回のレッスン 2 では、AI 駆動開発ツールを 5 カテゴリで整理し、選定軸 4 つを提示しました。今回は、いずれのツールを使う場合にも共通する「コード生成タスク特化のプロンプト設計」に踏み込みます。プロンプト設計の一般論（5 要素・Zero/Few-shot・Chain-of-Thought・JSON Schema など）は別の入門コースの領域なので、本コースではコード生成に特化した勘所に絞ります。

コンテキストの与え方——「AI が読める情報」の設計

AI 駆動開発でもっとも生産性に効くのは、「AI に何を読ませるか」の設計です。同じ AI モデルでも、コンテキストの与え方で出力の質が大きく変わります。主な与え方は次の 3 種類です。

リポジトリ全体検索

AI にリポジトリ全体を検索させ、関連コードを自分で見つけさせる方法です。Cursor・Windsurf・Claude Code・Coding Agent などは、内蔵の grep 相当機能や埋め込みベクトル検索で、リポジトリを自律的に走査します。「実装場所が分からない」「関連するテストを網羅したい」といったタスクで威力を発揮します。

一方、大規模リポジトリでは検索精度が落ちる場合もあります。「モノレポの中の特定パッケージだけを見てほしい」といった絞り込みは、明示的に指示するほうが安全です。

シンボル参照

関数名・クラス名・型名などのシンボルを直接指定して、AI にそのシンボルの実装や参照箇所を確認させる方法です。IDE の「定義へ移動」「参照を検索」機能を、AI が自動的に使う形です。Copilot・Cursor・JetBrains AI Assistant のように IDE との統合が深いツールで有効です。

flowchart LR
  A[コード生成タスク] --> Q{コンテキストの<br/>与え方}
  Q --> C1[関連ファイル添付<br/>明示的]
  Q --> C2[リポジトリ全体検索<br/>探索的]
  Q --> C3[シンボル参照<br/>ピンポイント]
  C1 --> R[高品質な出力]
  C2 --> R
  C3 --> R

💡 ポイント 「AI にお任せ」ではなく「AI が読めるように用意する」意識が生産性を左右します。同じ 10 分でも、コンテキスト設計に 3 分をかけた方が、結果として 7 分で終わることが多くあります。

失敗パターン 5 種——「なぜか動かない」の分類

コード生成が期待通りに進まないとき、原因は次の 5 種類に分けられます。それぞれ対処の方向が違うので、切り分けができると生産性が変わります。

1. API 幻覚——実在しないメソッドを呼び出す

AI が「もっともらしいがドキュメントに存在しない」メソッドや引数を書くパターンです。学習データが古い、あるいはライブラリの API を推測で埋めた結果として起こります。対処は、正しい API 仕様のドキュメントや型定義を AI に添付することです。「使うライブラリの型定義ファイルを見て」と明示すると激減します。

2. 依存関係の古さ——古いバージョンの書き方を採用する

AI の学習データにはカットオフ日があり、それ以降にリリースされたバージョンや、非推奨になった機能に気づけません。対処は、プロジェクトの package.json や requirements.txt などの依存宣言ファイルを添付し、「このバージョンで動く書き方をしてください」と指示することです。

3. テスト無視——既存テストを見ずに実装する

新しい実装を書かせたら、既存テストが軒並みコケる——というパターンです。AI が「実装のみに集中」して既存テストとの整合を確認しないと起きます。対処は、「関連するテストファイルも読んで、テストが通ることを確認しながら実装してください」と明示することです。CI で自動テストが動く体制も、事後的なガードとして有効です。

4. 規約違反——コーディング規約から外れた書き方をする

命名規則・インデント幅・エラーハンドリング方針・ログ出力形式などのコーディング規約を、AI が独自の判断で書いてしまうパターンです。対処は、AGENTS.md や CLAUDE.md などのルールファイルに規約を明記することです（レッスン 5 で詳しく扱います）。Linter・Formatter を CI に組み込む工程も並行して有効です。

5. 過剰リファクタ——頼んでいない変更まで手を入れる

「この関数を修正してほしい」と依頼したら、周辺 5 ファイルまで書き換えて返してくる——というパターンです。AI が「よかれと思って」広範囲を触ってしまう例です。対処は、「変更範囲を最小限にしてください」「指定したファイル以外は触らないでください」と明示することです。エージェント型のツールでは、変更対象ファイルを事前にホワイトリスト化するオプションも有効です。

⚠️ 注意 失敗パターンを「AI がバカだから」と切り捨てるのは早計です。多くの場合、コンテキストが不足しているか、指示が曖昧であることが根本原因です。失敗が続くときは「私はどんな情報を渡し、何を明確にしていたか」を振り返る癖が生産性を大きく左右します。

タスク分解の粒度——ワンショット vs 3〜5 ステップ分解

コード生成タスクをどの粒度で AI に渡すかは、成功率に直結します。目安は次の 2 通りです。

ワンショット生成——小さく明確なタスク

「この関数の引数バリデーションを追加してほしい」「この docstring を書いてほしい」「このエラーメッセージを英語に翻訳してほしい」といった、範囲が明確で 30〜100 行以内で完結するタスクは、ワンショットで指示すれば十分です。分解しても手間だけが増えます。

3〜5 ステップ分解——中〜大規模な変更

「認証機能を追加してほしい」「バッチ処理を非同期化してほしい」「決済プロバイダを差し替えてほしい」といった中〜大規模な変更は、事前に AI と対話して 3〜5 ステップに分解するほうが成功します。

分解の流れは次のようになります。

まず「このタスクの実装計画を、3〜5 ステップに分解してください」と AI に指示する
AI が提案した計画を、人間が読んで妥当性を判断する（この段階で穴があれば指摘）
ステップごとに実装を進め、各ステップの終わりで動作確認する
全ステップ完了後に、統合テストで最終確認する

この流れは「AI に主導権を渡しすぎず、人間が判断ゲートを持ち続ける」設計と言えます。Human-in-the-Loop の設計こそエンジニアの新しい仕事という中核メッセージが、ここで具体的な形になります。

Spec-driven Development と Vibe Coding の対比

同じコード生成タスクでも、進め方には対極的な 2 つのスタイルがあります。

flowchart LR
  V[Vibe Coding<br/>感覚で書く] --> V1[短時間で動く]
  V --> V2[保守性は<br/>後回し]
  S[Spec-driven<br/>仕様駆動] --> S1[時間はかかる]
  S --> S2[保守性が<br/>担保される]
  V -.向く.-> P1[プロトタイプ]
  V -.向く.-> P2[個人開発]
  S -.向く.-> P3[受託開発]
  S -.向く.-> P4[社内システム]
  S -.向く.-> P5[プロダクション運用]

Vibe Coding——感覚で書く

Andrej Karpathy が 2025 年 2 月に X で提唱した「Vibe Coding」は、「AI と対話しながら、感覚（vibe）でコードを書く新しいスタイル」を指します。厳密な仕様を書かず、動くところまで一気に走らせ、後から必要に応じて整える発想です。プロトタイピング・個人開発・技術検証では強力です。

Spec-driven Development——仕様駆動

Spec-driven development は、実装より先に仕様を書き、その仕様を AI と共有しながら実装を進めるスタイルです。仕様書は Markdown や AGENTS.md、あるいは Design Document のような形で用意します。受託開発・社内システム・プロダクション運用のコードでは、この進め方が長期的な保守性を担保します。

使い分けの判断軸

どちらのスタイルを取るかは、次の 3 つで判断できます。

コードの寿命：数日で捨てるなら Vibe、数年運用するなら Spec-driven
保守する主体：自分 1 人なら Vibe、チームで保守なら Spec-driven
失敗コスト：試行錯誤の一環なら Vibe、失敗が顧客に届くなら Spec-driven

「どちらが優れているか」ではなく「どちらが場面に合うか」で選ぶ発想が大切です。

📝 補足 Spec-driven development を「面倒な儀式」と感じるエンジニアも多くいます。しかし AI 駆動開発の時代では、仕様書は「人間が読むためだけの文書」ではなく「AI が精度高く実装するための入力」でもあります。仕様書の投資対効果は、AI 時代に大きく変わりつつあります。

まとめ

このレッスンでは、以下のことを学びました。

コンテキストの与え方 3 種類（関連ファイル添付・リポジトリ全体検索・シンボル参照）と使い分け
コード生成の失敗パターン 5 種（API 幻覚・依存関係の古さ・テスト無視・規約違反・過剰リファクタ）と対処
タスク分解の粒度（ワンショット vs 3〜5 ステップ分解）の判断軸
Vibe Coding と Spec-driven development の対比と、コードの寿命・保守主体・失敗コストで使い分ける視点
「AI にお任せ」ではなく「AI が読めるように用意する」意識が生産性を左右すること

次のレッスンでは、非同期委譲の主戦場である「エージェント型・自律型」に踏み込みます。Copilot Coding Agent・Copilot Workspace・Claude Code・Devin の使い分け、非同期委譲の運用設計を扱います。

確認クイズ

このレッスンの理解度をチェックしましょう。