本文へスキップ
Edition · Tokyo

AIエージェントに実装を任せる前に書くべき指示テンプレート

AIエージェントに実装を任せる前に、何をどう書けば失敗しにくいかをテンプレート付きで解説します。

codeagent.jp編集部 情報確認 約2分
Tags
情報確認
更新性
長く使える
読了目安
約2分
更新管理

仕様・料金・提供範囲が変わりやすいテーマは、公開日・更新日・情報確認日を分けて管理します。 導入前には必ず記事末尾の一次情報と公式ドキュメントで最新状況を確認してください。

AIエージェントに実装を任せる前に書くべき指示テンプレート の16:9共有用サマリー画像。 AIエージェントへの依頼は、目的から検証方法までを先に固定すると余計な推測を減らせる 1. 必須項目: Goalで最終状態、Scopeで触るファイル範囲を指定する、Out of scopeでリファクタや公開操作を明確に禁じる、Verifyにnpm run check等の合格条件を書く 2. 悪い依頼: いい感じに直しては変更範囲が無制限になる、最新化してはAPI/料金/仕様確認の抜けを招く、全部任せるはレビュー不能な巨大diffを生みやすい 3. 使い方: テンプレをIssue本文やPRコメントにそのまま貼る、1回の依頼は1成果物と1検証コマンドに絞る、失敗した指示文は次回テンプレへ反映する
AIエージェントに実装を任せる前に書くべき指示テンプレート 資料 26-MY45 2026.04.24 設計・ワークフロー
共有用画像を開く シェア 約2分 / ai-agent / プロンプト設計

結論

AIエージェントに実装を任せる前に、最低限これを書いてください。

依頼フォーマット (最小)
目的:
背景:
変更してよい範囲:
変更してはいけない範囲:
期待する動作:
完了条件:
検証方法:
出力形式:

AIエージェントへの依頼で失敗する最大の理由は、モデル性能ではなく、作業範囲と完了条件が曖昧なことです。

「この機能を作って」ではなく、「どのファイルを見て、何を変えて、何を変えず、どうなったら完了か」まで指定するだけで、成功率は大きく変わります。

  1. 1
    目的と背景
    何を実現したいか、なぜ必要かを一文で固定する。
  2. 2
    変更範囲
    触ってよいファイルと触らない領域を分ける。
  3. 3
    期待動作
    ユーザーから見える結果を箇条書きにする。
  4. 4
    完了条件
    テスト、ビルド、説明まで含めて終わりを定義する。
AIエージェントへの依頼は、目的から完了条件までを順に埋めると崩れにくい。

悪い指示の例

❌ あいまいな依頼
ログイン機能を直して

この指示では、AIエージェントは次のことが分かりません。

  • 何が壊れているのか
  • どの画面の話なのか
  • 期待する動作は何か
  • 変更してよい範囲はどこか
  • テストはどうすればよいか
  • UI変更してよいのか
  • 認証ロジックを変えてよいのか

AIエージェントは曖昧な部分を推測します。推測が当たれば成功しますが、外れれば余計な変更が増えます。

良い指示の例

✅ 範囲と完了条件を明示した依頼
目的:
ログイン画面で、正しいメールアドレスとパスワードを入力してもログインできない問題を修正してください。
背景:
現在、/login でログインボタンを押すと 401 が返ります。
API側ではなく、フロントエンド側の送信パラメータ名が間違っている可能性があります。
変更してよい範囲:
- src/pages/login.tsx
- src/components/LoginForm.tsx
- 関連するテストファイル
変更してはいけない範囲:
- 認証APIの仕様変更
- DBスキーマ変更
- デザインの大幅変更
- 新しいライブラリ追加
期待する動作:
正しい認証情報を入力した場合、ログイン成功後に /dashboard に遷移すること。
間違った認証情報の場合、既存のエラーメッセージを表示すること。
完了条件:
- 既存テストが通る
- ログインフォームのテストを追加または更新する
- 変更内容を要約する
検証方法:
npm test
npm run build
出力形式:
1. 原因
2. 変更内容
3. 実行した検証
4. 残った懸念

この指示なら、AIエージェントは迷いにくくなります。

そのまま使えるテンプレート

依頼テンプレート (コピペ用)
目的:
{何を実現したいかを一文で書く}
背景:
{なぜ必要か、現在何が起きているかを書く}
対象読者/利用者:
{この機能を誰が使うかを書く}
変更してよい範囲:
- {ファイルまたはディレクトリ}
- {関連するテスト}
変更してはいけない範囲:
- {触ってほしくないファイル}
- {変更禁止の仕様}
- {追加してほしくないライブラリ}
期待する動作:
- {期待する動作1}
- {期待する動作2}
完了条件:
- {条件1}
- {条件2}
- {条件3}
検証方法:
- {テストコマンド}
- {ビルドコマンド}
- {手動確認手順}
制約:
- UIを大きく変えない
- 新しいライブラリを追加する場合は事前に理由を説明する
- セキュリティに関わる変更は勝手に進めない
出力形式:
1. 調査結果
2. 実装方針
3. 変更内容
4. 検証結果
5. 残った懸念

実装前に「調査だけ」を依頼する

いきなり実装させるより、最初は調査だけを依頼した方が安全です。

Step 1: 調査だけを依頼する
まず、この機能を実装するために必要な関連ファイルを調査してください。
まだファイルは変更しないでください。
出力:
- 関連ファイル一覧
- 現在の実装の流れ
- 変更が必要そうな箇所
- リスク
- 実装案

このステップを入れると、AIエージェントがどこを見ているか分かります。間違った方向に進んでいる場合も、実装前に止められます。

変更範囲を必ず指定する

AIエージェントにとって、変更範囲がない依頼は危険です。

悪い例:

❌ 範囲があいまい
認証まわりを改善して

良い例:

✅ 範囲を狭める
今回はログインフォームのバリデーションだけを修正してください。
認証API、DB、セッション管理、OAuth設定は変更しないでください。

変更範囲を狭くすると、作業の成功率が上がります。特に個人開発では、AIが良かれと思って大きな変更を加えた結果、自分で理解できないコードになることがあります。

完了条件を書く

AIエージェントにとっての「終わり」を決めます。

完了条件の書き方
完了条件:
- npm test が通る
- npm run build が通る
- 追加した機能の使い方をREADMEに1段落で追記する
- 変更したファイルと理由を箇条書きで説明する

完了条件がないと、AIエージェントは「コードを書いたら終わり」と判断しがちです。実務では、テスト、ビルド、説明まで含めて完了です。

渡してはいけないもの

次の情報は、原則として渡さないでください。

  • 本番APIキー
  • .env の中身
  • 秘密鍵
  • 個人情報
  • 本番DB接続情報
  • 顧客データ
  • 決済関連の秘密情報

Cursor Agent、Cline、Gemini CLI などは、公式ドキュメント上でもファイル編集やコマンド実行などの機能が説明されています。便利な分、権限設計が重要です。

チェックリスト

  • 目的を書いた
  • 背景を書いた
  • 変更してよい範囲を書いた
  • 変更してはいけない範囲を書いた
  • 完了条件を書いた
  • 検証方法を書いた
  • 触ってほしくない情報を除外した
  • まず調査だけ依頼するか検討した
  • 最終レビューは自分で行う前提にした

次に読む

出典

About the author
codeagent.jp編集部

Claude Code / Codex / MCP を個人開発サイト運用と公開MCPサーバー開発で試し、一次情報・検証ログ・失敗例をもとに整理します。

関連して読む