AIエージェントはプロンプト次第で「10倍の差」が出る
GitHub Copilot・Cursor・Claude Code・Devin——AIエージェントによるコーディング支援が急速に普及し、「使っているかどうか」ではなく「うまく使えているかどうか」でエンジニアの生産性に大きな差が生まれる時代になりました。
しかし、「プロンプトを書いたけど思い通りのコードが出てこない」「何度もやり直しになってしまう」という経験を持つ人は多いはずです。AIエージェントが期待通りに動かない原因の大半は、LLM自体の限界ではなく、プロンプトの書き方にあります。
AIコーディングエージェントのプロンプトは、人間の同僚に仕様を伝えるより丁寧に書く必要があります。コンテキストが不足していれば、エージェントは「たぶんこういうことだろう」と補完して書き始め、意図とは異なるコードを生成します。この記事では、AIエージェントとのコーディングで実際に効果が出るプロンプトのコツを、具体例付きで解説します。
コツ1：「何を作るか」より「なぜ作るか」を先に伝える
最もよくある失敗パターンが、「実装してほしいもの」だけを伝えて目的を省くことです。
悪い例と良い例を比べてみます。
# 悪い例
ユーザー一覧のAPIエンドポイントを作って
# 良い例
管理画面からユーザーの検索・一覧表示を行うバックエンドAPIを作りたい。
対象は社内の管理者のみで、外部公開は不要。
ユーザー数は最大で数千件程度を想定している。
「なぜ作るか」「誰が使うか」「どの程度の規模か」を伝えることで、エージェントはページネーションの必要性・認証の要否・レスポンス設計の方向性を自分で判断できます。目的を省くと、パブリックAPIを想定した設計が出てきたり、ページネーションなしの実装になったりします。
コツ2：技術スタックと制約を明示する
AIエージェントは複数の言語・フレームワーク・パターンを知っています。明示しなければ、エージェントは「おそらくこれが多数派だろう」という選択をします。その選択があなたの環境と合わない場合、動かないコードが生成されます。
# 技術スタックの明示例
- 言語: Python 3.11
- フレームワーク: FastAPI 0.110
- DB: PostgreSQL 15、ORMはSQLAlchemy 2.0（非同期モード）
- 認証: JWTトークン（既存のauth.pyモジュールを使う）
- テスト: pytest + httpx
「既存のauth.pyモジュールを使う」という制約を書かない場合、エージェントは新しい認証ロジックをゼロから書くかもしれません。既存コードとの競合が起きて、修正コストが増大します。
既存コードベースがある場合は、関連するファイルやクラスの内容も一緒に渡すのが効果的です。Claude CodeやCursorのようなツールはファイルシステムにアクセスできますが、「このファイルを参照して」と明示的に指示することで精度が上がります。
コツ3：入力・出力・エラーケースを具体的に書く
「APIを作って」という指示は、エンジニアが同僚に「よきにはからって」と言うのと同じです。入力の形式・バリデーション条件・期待する出力・エラー時の挙動を明示することで、エージェントは迷わず実装できます。
# 入力・出力・エラーの明示例
エンドポイント: POST /api/users
リクエストボディ:
{
"email": "xxx@example.com", // 必須、RFC5322準拠
"name": "山田太郎", // 必須、1〜50文字
"role": "viewer" | "editor" // 必須、それ以外は400
}
正常時レスポンス: 201 Created + 作成したユーザーオブジェクト（パスワードフィールドは除外）
バリデーションエラー: 422 Unprocessable Entity + エラー詳細
メール重複時: 409 Conflict + "Email already exists"
特に重要なのが「エラーケースの明示」です。正常系だけ書いてエラー処理を省くと、エージェントは最低限のエラーハンドリングしか書かないか、try-exceptでまとめて握り潰すコードを生成することがあります。
コツ4：一度に頼みすぎない（タスク分割の技術）
AIエージェントに「このWebアプリ全体を作って」と依頼すると、長いコードは生成されますが、後半になるほど精度が下がる傾向があります。コンテキストウィンドウの限界に近づくにつれて、前半の仕様を忘れたような矛盾したコードが生成されることもあります。
効果的なアプローチはタスクを垂直に分割することです。
- まずUserモデルとDBマイグレーションだけ作って
- 次にUserリポジトリクラスを作って（手順1のモデルを参照）
- 次にユーザー登録のサービス層を作って（手順2のリポジトリを使う）
- 最後にAPIルーターとテストを作って
垂直分割にすることで、各ステップで生成されたコードを確認・修正してから次に進めます。エラーが出た場合もどのステップで問題が起きたか特定しやすく、デバッグコストが下がります。
コツ5：出力形式と品質基準を指定する
「良いコードを書いて」という指示では、エージェントは自分の基準で書きます。チームのコーディング規約・命名規則・テストカバレッジの方針を明示することで、レビューが必要な修正量を減らせます。
以下の基準でコードを書いてください:
- 型ヒントを必ずつける（Pythonの場合）
- 関数のdocstringはGoogle style
- 関数は1つのことだけをする（単一責任）
- ユニットテストをセットで書く（pytest、モックはpytest-mock）
- マジックナンバーは定数化する
- エラーメッセージは日本語にしない（ログ・例外メッセージは英語）
この指示を書くのは一度だけです。プロジェクトごとに「CLAUDE.md」や「AGENTS.md」といった設定ファイルに書いておけば、AIエージェントが毎回参照します。Claude CodeではリポジトリルートのCLAUDE.md、Cursorでは.cursorrulesファイルがこの役割を果たします。
コツ6：「確認してから進む」指示を使う
AIエージェントが自律的にコードを書き続けると、途中で間違った方向に進んでいても気づきにくくなります。重要な設計判断が必要な箇所では、エージェントに「実装前に方針を確認する」よう指示することが有効です。
実装を始める前に、以下を教えてください:
1. どのような設計アプローチを取りますか？
2. 既存のコードと競合する箇所はありますか？
3. テストはどこまで書きますか？
確認が取れたら実装を進めてください。
この「計画→承認→実行」のパターンは、特に影響範囲が広いリファクタリングや、既存コードの大きな変更を依頼するときに効果的です。
コツ7：失敗したときのフィードバックの伝え方
生成されたコードが期待と違った場合、「違う」「やり直し」だけ伝えると、エージェントは何が問題かを把握できず、同じような失敗を繰り返します。
効果的なフィードバックの構造は「何が問題か・なぜ問題か・こうしてほしい」の3点セットです。
# 効果的なフィードバック例
以下の問題があります:
1. SQLを直接書いているが、このプロジェクトはSQLAlchemyを使う方針です
2. エラーハンドリングがなく、DB接続失敗時に500エラーになる
3. N+1問題が発生しています（ループ内でクエリを発行している）
上記3点を修正して、SQLAlchemyのasync sessionを使った実装に書き直してください。
数字付きで箇条書きにすることで、エージェントが修正漏れを防ぎやすくなります。
まとめ：プロンプトテンプレートを作って再利用する
| コツ | ポイント |
|---|---|
| 目的を先に伝える | 「なぜ」「誰が使うか」「規模感」を書く |
| 技術スタックを明示 | バージョン・ライブラリ・既存モジュールを具体的に |
| 入出力・エラーを書く | 正常系だけでなくエラーケースも明示 |
| タスクを垂直分割 | 一度に全部頼まず、小さく確認しながら進める |
| 品質基準を指定 | 型ヒント・命名規則・テスト方針をファイルに書いておく |
| 計画を確認してから実行 | 設計判断が必要な箇所では承認フローを挟む |
| フィードバックは構造化 | 問題・理由・改善要求を番号付き箇条書きで伝える |
AIエージェントとの協働は、「AIに丸投げする」のではなく「AIという有能だが文脈を知らない同僚に、丁寧にブリーフィングする」という感覚に近いです。プロンプトに投資した時間は、手戻りの削減として何倍にもなって返ってきます。チームのベストプラクティスをAGENTS.mdやCLAUDE.mdに蓄積していくことが、組織全体の生産性向上につながります。