AIエージェントに実装を任せる前に書くべき指示テンプレート
AIエージェントに実装を任せる前に、何をどう書けば失敗しにくいかをテンプレート付きで解説します。
結論
AIエージェントに実装を任せる前に、最低限これを書いてください。
目的:背景:変更してよい範囲:変更してはいけない範囲:期待する動作:完了条件:検証方法:出力形式:AIエージェントへの依頼で失敗する最大の理由は、モデル性能ではなく、作業範囲と完了条件が曖昧なことです。
「この機能を作って」ではなく、「どのファイルを見て、何を変えて、何を変えず、どうなったら完了か」まで指定するだけで、成功率は大きく変わります。
悪い指示の例
ログイン機能を直してこの指示では、AIエージェントは次のことが分かりません。
- 何が壊れているのか
- どの画面の話なのか
- 期待する動作は何か
- 変更してよい範囲はどこか
- テストはどうすればよいか
- UI変更してよいのか
- 認証ロジックを変えてよいのか
AIエージェントは曖昧な部分を推測します。推測が当たれば成功しますが、外れれば余計な変更が増えます。
良い指示の例
目的:ログイン画面で、正しいメールアドレスとパスワードを入力してもログインできない問題を修正してください。
背景:現在、/login でログインボタンを押すと 401 が返ります。API側ではなく、フロントエンド側の送信パラメータ名が間違っている可能性があります。
変更してよい範囲:- src/pages/login.tsx- src/components/LoginForm.tsx- 関連するテストファイル
変更してはいけない範囲:- 認証APIの仕様変更- DBスキーマ変更- デザインの大幅変更- 新しいライブラリ追加
期待する動作:正しい認証情報を入力した場合、ログイン成功後に /dashboard に遷移すること。間違った認証情報の場合、既存のエラーメッセージを表示すること。
完了条件:- 既存テストが通る- ログインフォームのテストを追加または更新する- 変更内容を要約する
検証方法:npm testnpm run build
出力形式:1. 原因2. 変更内容3. 実行した検証4. 残った懸念この指示なら、AIエージェントは迷いにくくなります。
そのまま使えるテンプレート
目的:{何を実現したいかを一文で書く}
背景:{なぜ必要か、現在何が起きているかを書く}
対象読者/利用者:{この機能を誰が使うかを書く}
変更してよい範囲:- {ファイルまたはディレクトリ}- {関連するテスト}
変更してはいけない範囲:- {触ってほしくないファイル}- {変更禁止の仕様}- {追加してほしくないライブラリ}
期待する動作:- {期待する動作1}- {期待する動作2}
完了条件:- {条件1}- {条件2}- {条件3}
検証方法:- {テストコマンド}- {ビルドコマンド}- {手動確認手順}
制約:- UIを大きく変えない- 新しいライブラリを追加する場合は事前に理由を説明する- セキュリティに関わる変更は勝手に進めない
出力形式:1. 調査結果2. 実装方針3. 変更内容4. 検証結果5. 残った懸念実装前に「調査だけ」を依頼する
いきなり実装させるより、最初は調査だけを依頼した方が安全です。
まず、この機能を実装するために必要な関連ファイルを調査してください。まだファイルは変更しないでください。
出力:- 関連ファイル一覧- 現在の実装の流れ- 変更が必要そうな箇所- リスク- 実装案このステップを入れると、AIエージェントがどこを見ているか分かります。間違った方向に進んでいる場合も、実装前に止められます。
変更範囲を必ず指定する
AIエージェントにとって、変更範囲がない依頼は危険です。
悪い例:
認証まわりを改善して良い例:
今回はログインフォームのバリデーションだけを修正してください。認証API、DB、セッション管理、OAuth設定は変更しないでください。変更範囲を狭くすると、作業の成功率が上がります。特に個人開発では、AIが良かれと思って大きな変更を加えた結果、自分で理解できないコードになることがあります。
完了条件を書く
AIエージェントにとっての「終わり」を決めます。
完了条件:- npm test が通る- npm run build が通る- 追加した機能の使い方をREADMEに1段落で追記する- 変更したファイルと理由を箇条書きで説明する完了条件がないと、AIエージェントは「コードを書いたら終わり」と判断しがちです。実務では、テスト、ビルド、説明まで含めて完了です。
渡してはいけないもの
次の情報は、原則として渡さないでください。
- 本番APIキー
.envの中身- 秘密鍵
- 個人情報
- 本番DB接続情報
- 顧客データ
- 決済関連の秘密情報
Cursor Agent、Cline、Gemini CLI などは、公式ドキュメント上でもファイル編集やコマンド実行などの機能が説明されています。便利な分、権限設計が重要です。
チェックリスト
- 目的を書いた
- 背景を書いた
- 変更してよい範囲を書いた
- 変更してはいけない範囲を書いた
- 完了条件を書いた
- 検証方法を書いた
- 触ってほしくない情報を除外した
- まず調査だけ依頼するか検討した
- 最終レビューは自分で行う前提にした