Skip to Content
Docs08. コーディングエージェントコーディングエージェントへの依頼設計
初級coding-agentsprompt-design更新: 2026-07-05この記事の誤りを報告

この記事の音声は準備中です。

音声の一覧・再生リストへ

コーディングエージェントへの依頼設計

この記事の目的

コーディングエージェントコードベースを読み、ファイルを編集し、コマンドを実行して検証するループで開発タスクを遂行する Agent。コード補完と異なり「タスク単位の委任」を受けられる。へのタスクの依頼文を設計できるようになります。タスクの切り方・コンテキストの与え方・完了条件の指定を通じて、手戻りとレビュー不能な大量変更を減らすことが目標です。

なお本記事は、エージェントを使う側の依頼設計を扱います。エージェントを作る側のシステムプロンプト設計は Agent 向けプロンプト設計 を参照してください。

対象読者

  • コーディングエージェントを使い始めたが、期待と違う出力に手戻りが多い開発者
  • チームに依頼の書き方のガイドラインを整備したい人

前提知識

本文

概要

コーディングエージェントの成果は「モデルの能力 × 依頼の質」で決まります。同じツール・同じモデルでも、依頼の設計次第で「一発でレビュー可能な PR が出る」と「3 往復しても使えない」の差が生まれます。

依頼設計の中心は次のループを意識することです。

コーディングエージェントへの依頼設計: 概要の図コーディングエージェントへの依頼設計: 概要の図
コーディングエージェントへの依頼設計: 概要の図
図を元の大きさで表示

図の中をスクロールして読めます。キーボードでは図の領域へ Tab で移動し、矢印キーを使います。読み終わったら、この見出しをもう一度選ぶと閉じます。

コーディングエージェントへの依頼設計: 概要の図コーディングエージェントへの依頼設計: 概要の図

このループの各段階で人がどう関与するかは Human-in-the-Loop 設計 の一般論が当てはまります。

依頼の基本構造

効果的な依頼は次の 4 要素を含みます。

  1. 目的(なぜ) — 変更の背景。エージェントが途中の設計判断で迷ったときの判断基準になります
  2. 現状と文脈 — 関連ファイルのパス、エラーメッセージの全文、再現手順
  3. 制約 — 触ってはいけない領域、維持すべき互換性、使ってよい/いけないライブラリ
  4. 完了条件 — 「何が通れば完了か」。実行可能なコマンド(テスト・リント)で書くのが最良です
悪い例: 「ログイン周りのバグをいい感じに直して」

良い例: 「ログイン失敗時に 500 が返るバグを修正してください。
目的: 認証失敗は 401 を返すべき(API 規約 docs/api.md)。
現状: POST /login に誤ったパスワードを送ると 500。エラーログは以下(貼付)。
制約: 認証ミドルウェア(src/middleware/auth.ts)の公開インターフェースは変えない。
完了条件: tests/auth/login.test.ts に失敗ケースのテストを追加し、npm test が通ること」

タスク分割と粒度

粒度の基準は「1 依頼 = 人が 1 回でレビューできる変更量」です。エージェントは大きなタスクも最後まで走り切ってしまうため、分割しないと数千行の差分が届き、レビューがボトルネックになります。

  • 大きなタスクは「計画を出させて人が承認 → 段階ごとに実装」に分けます。多くのツールが計画(プラン)モードや実行前の方針提示をサポートしています
  • 探索と実装を分けるのも有効です。「まず現状の実装と影響範囲を調査して報告」→ 報告を確認 → 「この方針で実装」とすると、誤った前提での大量変更を防げます
  • 互いに独立したタスクは並列に依頼できます(クラウド実行型の得意領域)。依存があるタスクを並列にすると競合します

コンテキストの与え方

エージェントはリポジトリを探索できますが、探索には時間とトークンがかかり、誤ったファイルに辿り着くこともあります。依頼者が知っている具体情報は最初から渡すのが原則です。

  • ファイルパス・関数名・エラーメッセージ全文・再現手順を貼る(「関連コードを探して」より速く正確)
  • ただし、当たりが付いていないときは無理に指定しない。誤った指定はエージェントを誤導します。「〜の可能性があるが未確認」と確度を添えます
  • 恒常的な情報(実行コマンド・規約)は毎回書かず ルールファイル に置きます

検証と完了条件の設計

エージェントの出力品質を最も安定させるのは「自己検証の手段を渡すこと」です。

  • 完了条件を実行可能なコマンドで指定します(「npm test と npm run lint が通ること」)。エージェントは失敗すれば自分で修正を繰り返せます
  • テストがない領域の変更では「まず現状の挙動を固定するテストを書く → その後変更する」という依頼順にすると、退行を検知できます
  • 「テストが通ること」だけを完了条件にすると、テスト自体を書き換えて「通す」ことがあります。テストの変更を制約で禁止するか、テスト変更をレビューの重点にします

うまくいかないときの立て直し

実務での注意点

アンチパターン

  • 「いい感じに」型の曖昧依頼 — 期待と異なる方針で大量の変更が返ってきます。→ 完了条件と制約を先に書きます。書けないなら、まず探索タスク(調査依頼)に分けます
  • 巨大タスクの丸投げ — 数千行の差分はレビュー不能で、事実上マージできません。→ 計画承認と段階分割で「レビュー可能な単位」を維持します
  • エラーの要約だけを渡す — 依頼者の要約が誤診を招きます。→ エラーメッセージ・スタックトレースは全文を貼ります
  • 失敗した会話の上で延々と修正指示 — 汚染されたコンテキストが誤りを再生産します。→ 学びを抽出して新セッションでやり直します

チェックリスト

  • 完了条件を実行可能なコマンド(テスト・リント)で指定したか
  • 1 回のレビューで見きれる変更量になる依頼か(大きければ分割したか)
  • 制約(触らない領域・互換性・テスト変更の可否)を明示したか
  • 知っている具体情報(パス・エラー全文・再現手順)を渡したか
  • 恒常的な規約が依頼文ではなくルールファイルにあるか

関連トピック

参考資料

TODO・未確認事項

なし

ルールファイルと設定の設計コーディングエージェントの権限とセキュリティ