AIエージェントを脱線させないプロンプト設計の実践ガイド

はじめに

DevinやGitHub Copilot AgentのようなAIエージェントは、設計・実装の一部を自動化し開発速度を大きく向上させます。しかし、明確なガードレールなしに指示を出すと、リポジトリの前提を誤解したり、想定外の実装に踏み込んだりして生産性が下がることも少なくありません。本記事では、AIエージェントが設計や開発タスクを脱線しないようにするためのプロンプトのコツを、READMEやdocsの整備、タスクのスライシング、issueの書き方といった観点で具体的に紹介します。

ガードレールとしてのREADME / docs整備と活用プロンプト

READMEを「行動ルール集」にする

プロジェクトのREADME.mdは、エージェントが最初に読む前提資料です。以下の観点を明文化しておくと、プロンプトから参照させやすくなります。

• リポジトリ構成（ドキュメント・アセット・コードの場所）
• コーディング規約や利用ライブラリの制約
• 実行すべきテストコマンドや静的解析
• 既存のdocsディレクトリの役割一覧

README整備チェックリスト

1. 「このREADMEを最初に読む理由」を冒頭に書く
2. 「エージェントが守るべきルール」セクションを箇条書きで設ける
3. docs配下の詳細資料へのリンクを一覧化する

プロンプト例：READMEのルールを遵守させる

まず `<repo>/README.md` の「エージェントが守るべきルール」を読み、要約を報告してください。以降のタスクはそのルールを前提に進め、違反しそうな場合は必ず相談してください。

docsディレクトリを「詳細仕様データベース」にする

READMEに書き切れない詳細仕様は docs/ 以下に整理します。AIエージェント向けには、以下のような構造が有効です。

docs/
├── guardrails.md        # エージェントの禁止事項・注意事項
├── coding/              # 技術スタック別の実装ガイド
├── workflows/           # CI/CD・デプロイ手順
└── tasks/               # 頻出タスクのハンドブック

各ドキュメントの先頭には「目的」「参照タイミング」「関連タスク」を明記し、エージェントがどの場面で参照すべきか迷わないようにします。

プロンプト例：docsから必要情報を取得させる

docs/guardrails.md を読み、今回のタスクに関連する禁止事項を3つリストアップしてください。該当しない場合は「該当なし」と回答し、その理由も添えてください。

タスクをスライスして脱線を防ぐ

大まかな作業を「思考→実装→検証」に分解する

エージェントは一度に大きなタスクを渡されると、前提確認を飛ばして実装に進みがちです。タスクを小さく切り、段階ごとにアウトプットを評価するプロンプトを用意しましょう。

1. 調査フェーズ: 仕様確認・影響範囲の洗い出し
2. 設計フェーズ: 実装方針・変更ファイルの草案
3. 実装フェーズ: 実際のコード変更
4. 検証フェーズ: テスト実行と結果報告

プロンプト例：段階的な成果物を約束させる

このissueでは次の4段階で進めます。各ステップでこちらの承認を得るまで次に進まないでください。
1. 影響範囲の調査結果を箇条書きで出す
2. 変更するファイルと要約を提案する
3. コードを実装する
4. テストコマンドを実行し結果を報告する
まずステップ1のアウトプットをお願いします。

このようにプロンプト内でスライスを明示すると、エージェントが独断で次の段階へ進むリスクを下げられます。

「想定より超えたタスク」を抑止するissueテンプレート

issueの骨子にガードレールを仕込む

issueテンプレートに以下のような項目を追加すると、エージェントがスコープ外に踏み込む前に制御しやすくなります。

## やらないこと / スコープ外
- [ ] （例）データベーススキーマの変更は行わない
- [ ] （例）UIデザインの刷新は行わない

## 完了の定義
- [ ] READMEの「エージェントが守るべきルール」を順守
- [ ] テストコマンド `npm test` を実行して結果を記載

プロンプト例：スコープ逸脱時の報告を義務化

このタスクでは「やらないこと」リストにある作業は実施禁止です。もし必要だと判断した場合は、その理由と代替案を説明し、必ず指示を待ってください。

プロンプト例：タスク完了報告フォーマットを固定

タスクが完了したら以下のフォーマットで報告してください。
- 実施したステップ
- 参照したドキュメント
- 実行したテストコマンドと結果
- スコープ外作業を検討した場合、その判断過程

報告フォーマットを固定すると、エージェントがスコープ外の成果物を突然出すことを防ぎやすくなります。

追加ガードレール：途中確認とリマインド

タスクの途中でエージェントにスコープを再確認させるリマインドを仕込むと、長い作業でも脱線を防げます。

作業を開始する前に、今回のタスクの目的とスコープ外項目を200字以内で要約してください。また作業中に疑問点があれば必ず質問し、自己判断で進めないでください。

また、進捗が長時間報告されない場合に備え、以下のようなチェックインも有効です。

30分ごとに進捗と次のアクションを報告してください。新しいアイデアが浮かんでも、スコープ外の場合は報告だけに留めて実装しないでください。

まとめ：すぐに使えるプロンプトの雛形

• READMEやdocsに「エージェント専用のルール」を明記し、プロンプトで参照を強制する
• タスクを調査→設計→実装→検証に分割し、承認を待つステップ制のプロンプトを使う
• issueテンプレートに「やらないこと」「完了の定義」を入れ、報告フォーマットを固定する
• 作業開始前と途中でスコープ確認を促すリマインドをプロンプトに含める

これらの工夫を組み合わせることで、AIエージェントがチームのプロセスに沿って安全かつ効率的にタスクを進められるようになります。現場の状況に合わせてテンプレートをカスタマイズし、継続的に改善していきましょう。