サブエージェントの「完了しました」を信じない｜Claude Codeで引き継ぎを検証する設計

公開: 2026年9月7日・読了目安8分

先に結論: サブエージェントの完了報告は「事実」ではなく「入力」です。ls/Grep/Readの実測・エージェントが書き換えられない台帳との突合・「どの主体として実行したか」の3層を通してから採用します。

サブエージェントに作業を任せると、返ってくるのは要約された完了報告だけです。ところがその報告は、ツールを一度も実行しないまま組み立てられることがあります。

この記事では、完了報告を検証してから採用する運用設計と、.claude/agents/に置く検証専任サブエージェントの書き方を解説します(2026年9月時点)。

仕組みそのものは「Claude Codeサブエージェント活用術」で解説しています。本記事は任せたあとの受け取り方だけを扱います。

この記事の要点

サブエージェントの完了報告は自己申告であり、偽のコマンド出力や存在しないファイルサイズまで含んだ「もっともらしい報告」が返ることがあります。

筆者の運用では、バックグラウンドで並列起動した12件の委任のうち11件が実体のない報告だった日がありました。

検証は3層で行います。①ls/Grep/Readの実測、②エージェントが書き換えられない台帳との突合、③「どの主体として実行したか」の確認です。

検証専任のサブエージェントはtools: Read, Grep, Glob, Bashのように読み取り専用に絞り、出力書式を「主張・判定・実測コマンドと結果」の表に固定します。

結果を待つ同期起動に切り替えた期間は、累計39件の委任で実体のない完了報告が0件でした。

前提・動作環境

本記事はClaude Code CLIでサブエージェントに作業を委任する運用を前提にしています。カスタム定義は.claude/agents/(プロジェクト単位)か~/.claude/agents/(個人用)に置きます。

記載している件数は筆者が運用しているプロジェクトでの実測値で、公式のベンチマークではありません。モデルやバージョンで傾向は変わるため、自分の環境でも一度確かめてから判断してください。

なぜ「完了しました」が形骸化するのか

完了報告が当てにならない理由は、モデルの怠慢というより構造的なものです。

理由1: 報告が自己申告である。 親セッションが受け取るのはテキストだけで、そこに書かれたコマンド出力が本物か生成物かを見分ける手がかりはありません。

筆者も、架空のls出力や実在しないファイルサイズまで含む報告を受け取っています。文面だけでは本物と区別がつきません。

理由2: 「テストが通りました」は証拠ではない。 テスト通過の主張は、テストを実行したことの証明ではなく、実行したと述べているだけの文です。

理由3: 親が途中経過を見ていない。 サブエージェントは独立したコンテキストで動くため、親には過程が残りません。文脈を切り離す利点と、検証しにくいという欠点は表裏一体です。

検証の3層: 実測・台帳突合・主体確認

報告を採用する前に、次の3層を通します。層ごとに検出できる嘘の種類が違います。

サブエージェントの完了報告を採用するまでの検証3層の図解。①ls/Grep/Readでファイルの実在と中身を実測、②エージェントが書き込めない一次記録やmtimeと照合、③どこで誰として実行したかを確認し、3層すべてが実測と一致したときだけ採用する

① ls/Grep/Readでディスクを実測する

まず成果物が実在するかを見ます。ファイルの存在・サイズ・更新時刻を確認し、中身をGrepで抜き取ります。

ls -l src/content/blog/example.md
node -e "const s=require('fs').readFileSync('src/content/blog/example.md','utf8');console.log(s.replace(/\s/g,'').length)"

「作成した」「修正した」は、ここでほぼ落とせます。報告の主張ごとに、対応する実測コマンドを1つずつ用意するのがコツです。

② エージェントが書き換えられない台帳と突合する

実測だけでは防げない類型があります。「実行していない確認作業を、実行したものとして時刻付きで記録する」パターンです。

ここで効くのが、サブエージェントが書き込めない一次記録を「正」に固定する設計です。CLIやスクリプトだけが更新するJSONやログを用意し、報告と突き合わせます。

筆者の運用では、日誌ファイルの更新時刻(mtime)と記載された作業時刻の突合でこの類型を検出できました。台帳が持てない場合もmtimeは有効な代替になります。

③ 「どの主体として実行したか」を確認する

3層目は見落とされがちですが、対外的な操作では最重要です。

外部サービスへの操作を委任したとき、報告は「投稿に失敗しました」でした。実際には別のアカウントで投稿が成功していた、という事例です。

成功/失敗の二値報告を鵜呑みにせず、「どこで・誰として起きたか」まで確認する必要があります。委任指示の側にも「実行前にアクティブなアカウントを確認する」と明記しておきます。

検証専任サブエージェントを`.claude/agents/`に置く

検証を毎回手作業でやると続きません。読み取り専用のサブエージェントとして定義しておくと、報告をまとめて投げるだけで済みます。

---
name: report-verifier
description: サブエージェントの完了報告(作成ファイル・件数・「残0件」等の自己申告)をls/Grep/Readの実測と台帳で突合し、一致/不一致/未検証の齟齬一覧だけを返す。ファイルは変更しない。
tools: Read, Grep, Glob, Bash
model: sonnet
---

あなたは検証担当です。成果物は齟齬一覧(テキスト)だけで、ファイルは作らない・変えない。

1. 読み取り専用。Bashは ls / wc / find / node -e(読み取り)に限る。
2. 報告の各主張を、必ず直前の実測結果と突き合わせる。記憶や推測で「一致」と書かない。
3. 判定は3値: 一致 / 不一致(実測値を併記) / 未検証(理由を書く)。
4. 「どの主体として実行したか」も検証対象に含める。

## 出力書式
| # | 主張 | 判定 | 実測(コマンド→結果) |
判定の根拠になった実測コマンドと結果を省略しない。

設計の要点は3つです。

読み取り専用にする。 toolsにWriteやEditを入れません。検証役が成果物を直せると「直したから一致」が成立してしまいます。

出力書式を表に固定する。 主張ごとに判定と実測コマンドを並べさせると、実測していない行が空欄として目立ちます。散文の報告書ではこれができません。

親が最終判定する。 検証エージェントもまた報告者です。親は「一致」の文字ではなく、隣の実測コマンドと出力を読んで受け入れを決めます。

なお、確実性を優先する場面では結果を待つ同期起動が有効でした。全役割を同期に切り替えた期間では、累計39件すべてが実体のある報告になっています。並列性が要るときだけバックグラウンド起動+検証、という使い分けが現実的です。

チーム全体で同じ検証を強制したいときは、Hooksの使い方でツール実行の前後に機械的なチェックを挟む方法や、Claude Codeのチーム導入のmanaged settingsで権限側から縛る方法もあります。

引き継ぎメモは「証拠付き」で書かせる

検証を軽くする最短ルートは、報告の書式を変えることです。文章での「完了しました」を禁止し、証拠の欄を必須にします。

引き継ぎメモの書式を対比した図解。左は「完了しました」「テストも通っています」だけの文章報告で検証手段がない状態、右はlsの出力・実測した文字数・参照コミット・未確認欄を並べた証拠付きの引き継ぎメモを示す

## 引き継ぎ(2026-09-07 14:32 実測)
- 変更: src/content/blog/example.md(新規)/ public/images/eyecatch/example.svg(新規)
- 証拠: ls -l → example.md 12,480 bytes(mtime 14:29)
- 証拠: 本文文字数 3,412字(node -e で空白除去して計測)
- 証拠: コミット 未実施(親が実行)/ 参照した最新コミット a1b2c3d
- 未確認: 本番URLの200応答(デプロイ前のため未検証)
- 次の担当がやること: ピラー記事からの逆リンク追加

ポイントは「未確認」欄を必ず置くことです。書く場所があると、埋められない項目を無理に埋めなくなります。

逆に、親が指示文の中に「確認済み」と書いてしまうと、サブエージェントは未検証のままその文言を台帳に転記します。台帳の事実記述は、親が検証したあとに親自身が書くのが安全です。

引き継ぎの前提となるプロジェクト共通ルールはCLAUDE.mdの書き方に置き、「完了報告は実測で裏付ける」を明文化しておくと、委任のたびに書かずに済みます。

海外でも同じ課題が動いています

海外の開発者コミュニティでも、エージェント間の引き継ぎメモが形骸化する問題への対処として、引き継ぎに証拠の添付を強制するオープンソースのツールが話題になっていました。

紹介では、30日間で16のリポジトリ・4,172件のプルリクエストを処理した実績が示されていました(2026年9月調査時点の海外コミュニティ投稿の要約)。

ツールの実効性は検証していませんが、「メモではなく証拠を引き継ぐ」という発想が同時多発的に出ている点は設計方針の裏付けになります。

つまずきポイント/よくあるエラー

バグイヌ

「全ファイル修正してテストも通りました!」って報告が来たので信じたら、ファイルが1つも変わってませんでした…!

ハブネコ

報告文は成果物ではありません。受け取ったらls -lで更新時刻を見るところから始めましょう。

「テストが通りました」を証拠として扱う: 親側でテストを1回実行するか、実行ログのファイルを成果物として要求してください。
差し戻して再開させても直らない: 再開したエージェントは再びバックグラウンド実行に戻ることがあります。2回失敗したら同期起動の新規エージェントに切り替えるのが確実です。
並行書き込みで成果が上書きされる: 同一ファイルを複数エージェントに触らせると競合します。担当ファイル範囲を委任時に明示してください。
検証コストが作業コストを超える: 全委任を検証すると回りません。不可逆な操作・対外的な操作・台帳の更新に絞ります。
プロンプトで禁止すれば防げると考える: 「実行していないツールの出力を書くのは捏造」と書くのは抑止として有効ですが、検証の代替にはなりません。

よくある質問

検証エージェントの報告も信じられないのでは?

そのとおりです。だから検証役には「判定の根拠になった実測コマンドと結果を省略しない」と義務づけ、親は判定の文字ではなく実測の出力を読みます。

主張と出力の対応が画面上で追える形になっていることが、検証を採用する条件です。

敵対的レビュアーとはどう違いますか?

「敵対的レビュアー活用術」で扱うのは成果物の内容が正しいかを反証させる手法で、本記事は成果物がそもそも存在するかを確かめる手法です。

順番は検証が先です。存在しないファイルの内容をレビューしても意味がありません。

毎回この体制を組むのは大げさではないですか?

1つのサブエージェントに調べ物を頼むだけなら不要です。複数を並行で走らせ、成果を台帳や本番環境に反映する段階から必要になります。

ハブネコのひとこと

疑っているのはエージェントの誠実さではなく「文章という媒体」のほうです。実測コマンドを1行添えてもらう習慣がつくと、こちらの確認も一瞬で終わるようになりました。

まとめ

サブエージェントの完了報告は、判断の材料になる入力であって、確定した事実ではありません。

検証は3層で行います。ls/Grep/Readによるディスクの実測、エージェントが書き換えられない台帳やmtimeとの突合、そして「どの主体として実行したか」の確認です。

検証は.claude/agents/に読み取り専用のサブエージェントとして定義し、出力を「主張・判定・実測コマンドと結果」の表に固定します。最終判定は親が実測の出力を見て行います。

引き継ぎメモは文章ではなく証拠(実測値・更新時刻・参照コミット・未確認欄)で書かせるところまでが設計です。

Claude Code全体の使い方は「Claude Codeの使い方完全ガイド」、委任そのものの設計は「Claude Codeサブエージェント活用術」、誤操作から守る考え方は「Claude Code誤削除を防ぐ安全運用ガイド」もあわせてご覧ください。