著者注：すでに実務で Agent を使っている開発者に向けて、タスクを任せる前に用意すべきコンテキスト、参考資料、検証可能な受け入れ基準を整理し、引き続き人間の判断が必要な問題を区別します。
Agent を使うようになって成果物は確かに増えたものの、かえって人間の負担が大きくなった。2026 年 11 月 3 日、V2EX にある開発者がそんな状況を投稿しました。人間がループに入り、結果をチェックするだけでなく、タスクの脱線や設計上の問題も随時修正しなければならず、なかなか安心して任せられないというものです。投稿では、すでに得られている経験として、十分なコンテキストと参考資料を提供することで、Agent がタスクを理解しやすくなり、成果物の品質も高まることが挙げられています。ただし、「十分」とは具体的に何を指すのかについては、詳しく触れられていません。
この記事は、ありきたりな「プロンプトの書き方」の話ではありません。タスクを任せる前の準備に焦点を当て、曖昧な要件を目標、制約、参考資料、検証可能な完了基準に分解します。これにより、Agent が自らチェックできるようになり、人間は少数の重要なポイントで介入するだけで済みます。なお、準備の方法による効果の違いを定量化できる公開された比較データは、現時点ではありません。本文の事例はよくある状況をまとめたものなので、効果はご自身のタスクで検証してください。
この記事で得られること：再利用できる Agent 向けのタスク指示の構成と受け入れ基準の書き方がわかります。また、どの工程を Agent の自己チェックに任せられ、どこで人間の最終判断が必要なのかを見極められるようになります。
Agent のコンテキストと验收基準の要点
タスクの説明を書き始める前に、全体像を押さえておきましょう。Agent が意図から外れた作業をする原因の多くは、「何をするか」「どこまでやるか」「何に触れてはいけないか」について、あなたとの認識がずれていることです。次の表は、適切なタスク説明に含めたい5つの要素をまとめたものです。
| 要素 | 説明 | 解決できる問題 |
|---|---|---|
| 目標 | 何を、誰のために届けるのかを一文で明確にする | Agent が勝手に要件を広げたり、方向を誤ったりするのを防ぐ |
| 背景コンテキスト | プロジェクトの現状、関連モジュール、これまでに試したこと | 車輪の再発明や、既存の設計を覆すことを防ぐ |
| 制約 | 変更してはいけないファイル、必須の技術スタック、性能や互換性の要件 | 「動くけれど使えない」方案を防ぐ |
| 参考資料 | 既存コードの例、インターフェースのドキュメント、スタイルのサンプル | 出力のスタイルや構造を既存のプロジェクトに合わせる |
| 验收基準 | 一つずつ確認でき、できれば自動検証も可能な完了条件 | Agent に自己チェックさせ、あなたが一行ずつレビューする手間を減らす |
Agent の作業が意図から外れる典型例
元の投稿では具体的な事例は挙げられていませんが、ここではプログラミングやタスク実行を担う Agent で比較的よく見られるケースをまとめます。一見すると異なる問題ですが、根本的な原因は、タスク説明に必要な要素が欠けていることにある場合がほとんどです。
| 意図から外れた作業 | よくある根本原因 | 事前の対策 |
|---|---|---|
| 1つのバグを修正するついでに、モジュールの半分をリファクタリングする | 目標の境界が曖昧で、変更範囲が示されていない | 制約に「変更を許可するファイルや関数」を明記する |
| プロジェクトにない新たな依存関係を導入する | 既存の技術スタックを把握していない | コンテキストに既存の依存関係と、新規追加を禁止するルールを記載する |
| コードスタイルがプロジェクトの他の部分と一致しない | 参考となるサンプルがない | 同種の実装を1〜2件、参考資料として添える |
| 「完了した」と報告するが、重要なケースをカバーしていない | 完了基準が曖昧 | 验收基準を実行可能なチェック項目として書く |
| 技術的には実現可能だが、プロダクトの意図に合っていない | 設計上の判断が事前に説明されていない | 先に人が設計を判断し、実装を Agent に任せる |
最後のケースは特に注意が必要です。これはコンテキストが「足りない」ことによるものではなく、設計上のトレードオフそのものを人が判断する必要があります。この点は後ほど別途説明します。
Agentへのタスク指示書の作り方：5つのセクション
上記の5つの要素を文書にまとめれば、Agentが内容を理解し、照らし合わせて自己チェックできるタスク指示書になります。Markdownで管理し、プロジェクトのリポジトリに TASK.md などの名前で置くのがおすすめです。また、プロジェクト共通の制約は AGENTS.md などの説明ファイルに、個別のタスク目標はそれぞれのタスク指示書に記載する方法もあります。
第1セクション：Agentへのタスク目標の書き方
目標は「成果物は何か」「誰がどのような場面で使うか」を一文で明確にしましょう。「ログインモジュールを改善する」という説明では、Agentはパフォーマンスの改善、コードのリファクタリング、UIの刷新など、さまざまな解釈ができます。よりよい書き方は、「パスワードが間違っている場合にログインAPIが統一されたエラーコードを返し、フロントエンドがそれに応じたメッセージを表示できるようにする。ログイン成功時の処理は変更しない」です。
タスクが比較的大きい場合は、目標の下に「今回は何をしないか」を一文添えるのがおすすめです。明確な除外事項は、対象を説明すること以上に、Agentによる要件の拡大を防ぐのに役立ちます。
第2セクション：Agentに渡す背景情報
背景情報は、量よりもタスクとの関連性が重要です。リポジトリ全体をAgentに渡すだけでは、十分な情報を提供したことにはなりません。今回のタスクにどの部分が関係するのかを伝える必要があります。以下の順序で整理するのがおすすめです。
- 関連モジュール：
src/auth/以下のログイン処理と対応するテストファイルなど、タスクに直接関係するファイルやディレクトリを列挙します。 - 既存の設計上の判断：「エラーコードは
errorsモジュールで一元的に定義し、ビジネスロジックにハードコードしない」など、これまでの設計方針とその理由を伝えます。 - 試行済みの方法：以前に試して断念した方法があれば、その理由を明記し、Agentが同じ試行を繰り返さないようにします。
- 用語の説明：プロジェクト内の業務用語は、コードから正確に推測できるとは限らないため、説明します。
第3セクション：Agentへの制約条件リスト
制約は、「動くけれど使えない」という結果を減らすために重要です。よくある制約をチェックリストにまとめ、Agentが実行前と完了後にそれぞれ確認できるようにしましょう。
- 変更を許可する範囲と、データベースのマイグレーションスクリプトや公開インターフェースの定義など、変更を明確に禁止するファイル。
- 「サードパーティの依存関係を追加しない」「プロジェクトで既に使用しているログライブラリだけを使う」などの技術スタック上の制限。
- 「既存のインターフェースのシグネチャを変更しない」など、互換性やパフォーマンスに関する要件。
- 「公開インターフェースの変更が必要だと分かった場合は、作業を止めて理由を説明し、自己判断で変更しない」など、判断に迷う状況への対処方法。
最後の項目は特に重要です。「作業を止めて人に確認すべき」条件をAgentに明示しておけば、後から勝手な変更に気づいて対応するより、ずっと手間を減らせます。
第4セクション：Agentに渡す参考資料の選び方
参考資料は、Agentがゼロから考えるのではなく、既存のやり方を参考にするためのものです。特に効果的なのは、同じプロジェクト内の類似した実装です。たとえば「APIを新規追加する場合は、パラメータの検証やエラー処理を含め、src/user/ 以下の実装を参考にしてください」と伝えます。外部ドキュメントはタスクに関連する章だけを渡し、バージョンを明記しましょう。古いバージョンのインターフェースに基づいてAgentがコードを書くのを防げます。
Agentの受け入れ基準を検証可能にする書き方
受け入れ基準は、タスクの説明全体の中でも曖昧になりやすく、時間をかけて書く価値がある部分です。判断基準はシンプルです。Agentが自分で満たしているかどうかを検証できない受け入れ基準は、基準ではなく単なる願望です。
| 曖昧な書き方 | 検証可能な書き方 | 検証方法 |
|---|---|---|
| コードの品質を高くする | プロジェクト既存のlintチェックを通過し、新たな警告を出さない | Agentがチェックコマンドを実行し、結果を報告する |
| 機能が正常に動作する | パスワード誤り、アカウント不存在、ログイン成功の3つのケースをカバーする単体テストを追加し、すべて通過する | テストを実行し、結果の要約を記載する |
| ほかの機能に影響を与えない | 既存のテストスイートがすべて通過し、制約で変更を禁止されたファイルを変更していない | 全テストを実行し、変更ファイルの一覧を示す |
| ドキュメントを充実させる | APIドキュメントにエラーコードの説明を追加し、既存の項目と同じ形式にする | 参考サンプルと項目ごとに照らし合わせる |
| パフォーマンスを低下させない | クリティカルパスにデータベースクエリを追加しない | まとめの中でクエリ回数の変化を説明する |
受け入れ基準を書いたら、タスクの説明の末尾で、Agentに「受け入れ基準を一つずつ照らし合わせる」形式で完了状況を報告するよう求めましょう。各項目について、満たしているか、その根拠、満たしていない場合はその理由を明記します。こうすれば、結果を確認するときはこの対照表を見るだけで済み、すべての変更を最初から読む必要はありません。
Agentのコンテキストと受け入れ基準：クイックスタート
ここまでの内容を、すぐに実践できる手順にまとめます。追加のツールは不要で、Markdown文書が1つあれば始められます。
5ステップでAgentへのタスク指示を準備する
- 目標より先に受け入れ基準を書く：逆の順序で書くことで、「完了」がどのような状態かを明確にし、目標が大きくなりすぎるのを防げます。
- 背景となるコンテキストを補う：タスクに関係するモジュール、決定済みの事項、うまくいかなかった試みだけを簡潔に記載します。
- 制約と停止条件を列挙する：変更してはいけないものと、どのような場合に作業を止めて確認すべきかを明記します。
- 参考例を1〜2件選ぶ：プロジェクト内の類似実装を優先し、外部ドキュメントは関連する章だけを示します。
- 構造化された報告を求める：完了後は受け入れ基準に沿って項目ごとに報告し、変更したファイルの一覧と未解決の問題を添えてもらいます。
Agentへのタスク指示の例（ログインエラーの表示修正）
以下は、架空のシナリオに基づくタスク指示のひな形です。自分のタスクに合わせて内容を置き換えて使えます。
- 目標：ログインAPIがパスワードの誤りとアカウントの不存在に対して共通のエラーコードを返し、フロントエンドがそれに応じたメッセージを表示する。今回はログイン成功時の処理とページのスタイルは変更しない。
- 背景：エラーコードは
errorsモジュールで一元管理されている。以前はフロントエンドでエラーメッセージの文言を判定する方法を試したが、多言語対応の問題から断念した。 - 制約：変更できるのは
src/auth/と対応するテストのみ。依存関係は追加しない。共通APIの定義を変更する必要がある場合は、作業を止めて説明する。 - 参考資料：
src/user/にある登録APIのエラー処理。 - 受け入れ基準：3つのケースについて単体テストを追加し、すべてパスする。既存のテストもすべてパスする。lintの警告を新たに発生させない。APIドキュメントに2つのエラーコードの説明を追加する。
- 報告形式：受け入れ基準を一つずつ確認し、変更したファイルを列挙したうえで、残っている課題を説明する。
🚀 まずは試してみよう：同じタスク指示を異なるモデルにそれぞれ渡し、制約や作業を止める条件を最もよく守れるモデルを比較してみましょう。APIYI apiyi.com のような集約プラットフォームを使えば、共通のインターフェースと同じAPIキーで異なる提供元のモデルを切り替えられます。複数のアカウントを個別に登録・設定する手間が省け、自分の実際のタスクで比較テストを行いやすくなります。
異なる提供元のモデルで Agent の実装を相互レビューする
元の投稿の著者は、同じ提供元のモデルには似た盲点があるかもしれない、という懸念も挙げています。そのため、異なる提供元の Agent 同士でレビューさせたいものの、現状では Markdown 文書やコピー＆ペーストで情報をやり取りするしかなく、調整コストが高いという課題があります。この考え方は、本記事の方法と組み合わせられます。タスクの説明と受け入れ基準そのものが、相互レビューにおける最良の共通基盤になります。レビュー担当は意図のすべてを理解する必要はなく、同じ基準に照らして一つずつ疑問点を指摘すればよいのです。
手軽な方法として、異なるモデルにそれぞれ役割を割り当て、同じタスク説明を入力として渡すやり方があります。
| 役割 | 入力 | 担当 | 利用方法 |
|---|---|---|---|
| 実行者 | タスク説明 | 実装し、受け入れ基準に沿って自己チェックする | 普段使っているコーディング Agent |
| レビュー担当 A | タスク説明 + 変更内容の要約 | 受け入れ基準を一つずつ確認し、カバーされていないケースを指摘する | 別の提供元のモデル。APIYI の統一インターフェース経由で呼び出せる |
| レビュー担当 B | タスク説明 + 変更内容の要約 | 制約や停止条件に違反していないかを重点的に確認する | 3社目の提供元のモデル。同じインターフェースでモデル名を切り替えるだけで利用できる |
| 人間 | レビュー意見のまとめ | レビュー担当同士の意見が食い違う箇所と設計上の問題だけを扱う | なし |
小さなスクリプトを書いて「実行結果 → レビュー用モデルに送信 → 意見を集約」という流れをつなげれば、手動でのコピー＆ペーストの大部分を置き換えられます。APIYI は主要な SDK と互換性のある統一インターフェースを提供しているため、スクリプト内のモデル名を変えるだけで、別の提供元のモデルを呼び出せます。これにより、「異なる提供元の Agent を導入する」際に最も手間のかかる接続部分を簡素化できます。ただし、自動化するのはあくまで情報の受け渡しであり、最終判断は人間が行うべきです。
Agent のコンテキストで解決できる問題と、人による確認が必要な問題
十分なコンテキストを用意すれば、軌道修正の手間を大幅に減らせますが、人の介入をすべてなくせるわけではありません。元の投稿では「タスクが想定から外れること」と「設計上の問題」が並べて挙げられていますが、この2つは性質が異なります。前者は情報不足によることが多く、後者はトレードオフの判断が求められることが多いためです。
| 問題の種類 | コンテキストで解決できるか | 理由 | 人の役割 |
|---|---|---|---|
| 変更範囲の逸脱 | 基本的に可能 | 制約を明確にすれば、Agent が自分でチェックできる | 変更一覧を抜き取り確認する |
| スタイルやフォーマットの不統一 | 基本的に可能 | 参照用のサンプルがあれば、それにならうことができる | ときどき確認する |
| テストカバレッジの不足 | 大部分は可能 | 受け入れ基準にシナリオを明記すればよい | シナリオ一覧に漏れがないかレビューする |
| アーキテクチャや設計のトレードオフ | 難しい | 複数の妥当な案の間で価値判断が必要になる | 事前に決定し、タスクの説明に書き込む |
| プロダクトの意図とユーザー体験 | 難しい | ビジネス目標とユーザーへの理解に左右される | 事前に定義し、事後に受け入れ確認を行う |
| 受け入れ基準自体が正しいかどうか | できない | Agent は基準との照合しかできず、基準の前提を問い直せない | 必ず人が責任を持つ |
設計上の問題を完全に Agent に任せるのが難しいのは、通常、唯一の正解がないからです。たとえば「エラーコードを共通モジュールと業務モジュールのどちらに置くか」は、どちらの方法でも動作します。選択はチームの今後の拡張方針やメンテナンスの慣習によって変わりますが、こうした情報は人の判断の中にあることが多く、すべてを文章にするのは困難です。
そこで、より現実的な戦略は人の介入を前倒しすることです。タスクを始める前に設計上の意思決定を済ませ、制約に書き込んでおけば、Agent の実行中にずっと見守る必要はありません。実行後は、受け入れ基準との対照表と、レビュアー間で意見が分かれた点を確認するだけです。こうすることで、一連の作業における人の役割は、「最初から最後まで付き添う」ことから「最初に方向を定め、最後に受け入れ確認を行う」ことへと変わります。
よくある質問 FAQ
Q1: Agent の受け入れ基準とは何ですか？
受け入れ基準とは、「指定されたテストがすべて通る」「変更を禁止されたファイルを変更していない」など、タスクの完了時に満たすべき、ひとつずつ確認できる条件です。Agent が自己チェックできるほか、人も出力をすべて一行ずつ読まなくても、結果をすばやく判断できます。
Q2: コンテキストは多く渡すほどよいのでしょうか？
いいえ。関係のない情報は重要なポイントをわかりにくくし、Agent が本来触れるべきでない部分まで変更する原因にもなります。コンテキストは今回のタスクに合わせて、関連モジュール、すでに決まっていること、失敗した試み、必要な用語などを選びましょう。ある情報が役立つか迷ったら、APIYI apiyi.com で異なるモデルを呼び出し、簡潔版と詳細版のタスク説明をそれぞれ試して、どちらが意図から外れにくいかを確認できます。
Q3: 小さなタスクにも、これほど詳しいタスク説明を書く必要がありますか？
必要ありません。共通の制約やプロジェクトの背景は、プロジェクト単位の説明ファイルに書いて長期的に再利用できます。個々のタスクでは、目標、参考資料、受け入れ基準を補足するだけで十分です。数分で終わる小さな変更なら、通常は一文の目標と2〜3項目の受け入れ基準があれば足ります。
Q4: この方法はどのような Agent やタスクに適していますか？
主に、プログラミング向けの Agent や、明確な成果物があるタスク向けの Agent に適しています。たとえば、バグの修正、インターフェースの実装、ドキュメントの生成、データの整理などです。一方、探索的な要素が強く、目標自体がまだ定まっていないタスクでは、受け入れ基準を事前に明確にするのが難しいため、まず人と Agent で方向性を話し合ってから実行するほうが適しています。
Q5: コピー＆ペーストを繰り返さずに、異なるメーカーのモデルで相互レビューするにはどうすればよいですか？
実行結果とタスク説明をまとめてレビューモデルに送り、意見を集約する小さなスクリプトを作る方法があります。APIYI apiyi.com の統一インターフェースを使えば、スクリプト内のモデル名を切り替えるだけで異なるメーカーのモデルを呼び出せます。各社の SDK やアカウントに個別に対応する必要がなく、「実行＋複数モデルによるレビュー」のフローを手早く試作できます。
Q6: この方法にはどのような限界がありますか？
まず、設計上の判断を代わりに行うことはできません。アーキテクチャのトレードオフや製品の意図は、引き続き人が決める必要があります。また、受け入れ基準が間違っていると、Agent はその誤った基準を忠実に満たしてしまいます。さらに、現時点では準備方法の違いによる効果を定量化した公開データが不足しています。自分のタスクで小規模に比較し、軌道修正した回数を記録して参考にするとよいでしょう。
Agent のコンテキストと受け入れ基準の要点 Key Takeaways
- 方向がずれる原因の多くは情報不足：目標、制約、参考資料のいずれかが欠けるだけでも、手戻りにつながります。
- タスク説明に必要な5要素：目標、背景・コンテキスト、制約、参考資料、受け入れ基準のすべてが必要です。
- 受け入れ基準は検証可能に：Agent が自ら検証できない基準は、単なる願望にすぎません。
- 停止条件を設定する：どんなときに作業を止めて質問すべきかを明記すれば、事後の修正より手間が省けます。
- 設計上の判断は先に済ませる：アーキテクチャや製品に関するトレードオフは人が先に判断し、制約に書き込みます。
- クロスチェックには同じ基準を使う：APIYI の統一インターフェースから複数社のモデルを呼び出し、比較レビューできます。
まとめ
Agent を使った作業のサイクルで人が疲弊する大きな原因は、タスクを任せる時点で情報が不足し、作業をずっと見守りながら随時軌道修正しなければならないことです。事前準備のポイントは3つあります。
- 5つの項目でタスクを説明する：目標、背景、制約、参考資料、受け入れ基準を示し、何をどの水準まで行い、何に手を触れてはいけないのかを Agent に伝えます。
- 受け入れ基準を確認可能な項目にする：Agent に項目ごとの照合結果を報告させ、人は照合表と残された課題を確認します。
- コンテキストの提供で対応できる問題と、人が判断すべき問題を区別する：設計上のトレードオフは事前に決め、受け入れ基準そのものには人が責任を持ちます。
次の実際のタスクでは、まず受け入れ基準を書き、その後にほかの項目を補ってみましょう。作業途中で介入した回数も記録すれば、改善の目安になります。複数社のモデルによるクロスチェックを試している場合は、APIYI apiyi.com の統一インターフェースからさまざまなモデルを利用し、どの組み合わせが介入を最も減らせるか、実際のタスクで検証できます。
📚 参考資料
- V2EX ディスカッション – 人間の介入を減らし、Agent の自律的な作業と成果物の品質向上をどう実現するか：この記事のテーマの出典
- リンク：
v2ex.com/t/1254207 - 概要： Agent の作業ループに人間が関わることによる疲労、コンテキストの役割、複数ベンダーの Agent による相互レビューの構想について述べています
著者: APIYI 技術チーム
技術交流: Agent へのタスク指示や複数モデルの協調に関する実践経験について、APIYI のホームページ apiyi.com からお気軽にお問い合わせください
