作業記録からAIエージェントの失敗をたどる:原因を指示・ツール・判断に分ける振り返り方

まず作業記録に何を残すか

振り返りに必要な材料は次の5つです。

1. 最初に渡した指示(システム側の指示や添付資料を含む)
2. ツール呼び出しごとの名前と引数
3. ツールが返した結果(エラーを含む)
4. エージェントの途中の発言や計画
5. 最終成果物と、人が直した箇所

OpenAIの公式ドキュメントでは、トレースにモデル呼び出し、ツール呼び出しとその出力、ハンドオフ、ガードレールなどが記録され、デバッグに使えると説明されています。(OpenAI: Integrations and observability) MCPの仕様も、クライアントは監査のためにツール利用を記録することが望ましい(SHOULD)としています。これは2025-06-18版の仕様ページで確認した記述で、版が変われば変わる可能性があります。(MCP Tools仕様)

お使いの環境が上の項目を残さない場合は、まず残す設定から始めてください。Claude Codeにはフックという仕組みがあり、ライフサイクルの決まった時点でシェルコマンドを自動実行できます。記録の自動化にも使える仕組みですが、どのイベントでどう記録するかは各自の公式リファレンスで確認してください。(Claude Code hooks guide)

なお、記録には顧客情報やAPIキーが混ざります。共有や貼り付けの前に、ダミーの値へ置き換えてください。

三つの層の見分け方

• 指示、問い：目的・範囲・完了条件・禁止事項は書いてあったか、典型的な兆候：指示に書かれていない部分でエージェントが埋めた/指示同士が矛盾、主な直し先：依頼文、完了条件、止まる条件
• ツール、問い：ツールは正しい情報を、誤解しにくい形で返したか、典型的な兆候：検索が複数件を黙って返す、引数の意味が曖昧、エラーが成功に見える、主な直し先：ツールの説明、引数、戻り値、権限
• 判断、問い：指示とツール結果が十分なのに、選択を誤ったか、典型的な兆候：結果に「不一致」とあるのに進めた、不要な操作をした、主な直し先：確認ポイント、実行権限の絞り込み、タスク分割

判定の順番は「指示 → ツール → 判断」です。判断のせいにするのは最後にします。理由は、判断層に置くと「モデルが悪かった」で終わりやすく、直す手が減るからです。

迷ったときは次の問いを使います。

• 同じ指示と同じツール結果だけを渡された有能な新人は、同じ間違いをしたか。したなら指示かツール側です。
• 正しい情報が記録上すでに出ていたか。出ていたのに使われなければ判断層です。
• 一つの失敗に複数の層が関わることもあります。その場合は「主因」と「寄与」に分け、対策は主因から先に作ります。

振り返りの手順

1. 失敗を一文で定義する。 「返信案に別の顧客の注文番号が入った」のように、事実だけを書きます。
2. 最初にずれた行を探す。 最終結果から逆にたどり、「ここまでは正しく、ここから違う」という境目を見つけます。
3. その行の直前の入力を確認する。 指示にあったか、直前のツール結果にあったかを見ます。
4. 三層に仮置きし、根拠の行を書く。 根拠が書けない分類は採用しません。
5. 対策を一つずつ作る。 対策は「次に何が変わるか」が言える形にします。
6. 同じ入力で再実行して確認する。 直した結果は、実際に再実行して初めて分かります。

振り返りシート

コピーして使えます。

【失敗の事実】(一文・評価語なし)
【境目の行】(記録の何番目か/何をしたか)
【その時点で渡っていた情報】
 - 指示:
 - ツール結果:
【分類】 主因: 指示 / ツール / 判断   寄与:
【根拠】(記録の該当箇所を書き写す)
【対策】
 - 指示:
 - ツール:
 - 人の確認:
【再実行の結果】(未実施なら「未」)

記入例(説明用の例)

以下は仕組みを示すために作った架空の例で、実際の実行結果ではありません。「問い合わせメールへの返信案を作る。顧客台帳ツールで注文状況を調べる」という作業を想定しています。

【失敗の事実】返信案に、別の顧客(同じ姓)の注文番号が書かれた
【境目の行】手順3: 台帳検索(姓="佐藤")を実行し、先頭の1件で返信案を作成
【その時点で渡っていた情報】
 - 指示:「注文状況を調べて返信案を作る」。顧客の特定方法の記載なし
 - ツール結果: 3件がヒット。件数の表示はなく、結果が並ぶだけ
【分類】 主因: ツール  寄与: 指示、判断
【根拠】検索結果に件数や「複数該当」の表示がない/指示に照合キーがない/先頭の1件を選んだ
【対策】
 - 指示:「照合は注文番号かメールアドレスで行い、一意に決まらなければ作業を止めて質問する」
 - ツール: 複数該当のときは「複数該当」と明示して返す
 - 人の確認: 返信案の送信前に、宛名と注文番号の対応を人が確認する
【再実行の結果】未

この例でツールを主因にしたのは、複数該当が結果から読み取れなかったためです。結果が明示されていれば、判断層の問題として扱う余地が大きくなります。MCPの仕様では、ツール実行の失敗はプロトコルエラーとは別に、結果内のisError: trueで表すことになっています。「失敗や曖昧さを結果として返す」設計は、仕様上もツール側で扱う項目です。(MCP Tools仕様)

分類をAIに手伝わせる依頼文

長い記録は、AIに一次分類をさせると速くなります。ただし、エージェントが後から述べる「なぜそうしたか」は記録とは別の推測かもしれないため、必ず記録の行を根拠として引かせ、最終判断は人が行います。

以下は、AIエージェントの作業記録(個人情報はダミーに置換済み)です。
1. 失敗の「境目」と思われる行を特定してください。
2. その原因を「指示/ツール/判断」のいずれかに分類し、主因と寄与を分けてください。
3. 分類ごとに、記録から引用した根拠を示してください。根拠がない場合は「記録からは不明」と書いてください。
4. 対策案を、指示の修正文・ツールの修正点・人の確認点に分けて出してください。
推測で記録にない事実を補わないでください。

【指示】…
【作業記録】…

出力を受け取ったら、人が確認する点は三つです。引用が記録に実在するか、境目の行が本当に最初のずれか、対策が別の失敗を生まないか、です。

対策を選ぶときの目安

• 指示層が主因なら、禁止事項よりも「完了条件」と「迷ったら止まる条件」を足すほうが効きやすいです。
• ツール層が主因なら、依頼文で補う前にツールの説明、引数、戻り値を直します。Anthropicの例のように、誤用しにくい形に変えるのが筋です。
• 判断層が主因なら、プロンプトで念押しするより、取り消せない操作の前に人の確認を置く、権限を絞るなど、構造で防ぎます。MCPの仕様でも、ツール呼び出しを拒否できる人がいること(human in the loop)が望ましいとされています。

振り返りは、直したあとに同じ入力で再実行して初めて完了です。シートの最終欄を「未」のままにしないことを、運用ルールにしてください。