Claude Codeの無人運用ログ設計｜サブエージェント可視化
「無人で走らせたAIが、途中で何をしていたのか分からない」——夜のうちに動かした処理が朝には終わっているのに、中身が見えない。AIを自動で回し始めると、誰もがこの不安に突き当たります。
結論から言うと、Claude Codeの --forward-subagent-text（v2.1.211で追加）を使えば、これまで観測できなかったサブエージェントの発言と思考を、そのままログに流し込めます。ただしフラグを足すだけでは運用は安定しません。ログは「見る頻度」で層を分ける必要があります。
株式会社Fyveは、常時起動のMac miniで毎日AIを無人稼働させています。私たちが実運用で組んだログ設計と、この新しいフラグをどこに挿すのかを公開します。
無人運用で最初に困るのは「中が見えない」こと
AIを無人で回すと、成果物は残ります。しかし「どういう判断でそうなったか」は残りません。特にサブエージェント（親のAIが仕事を切り出して投げる子のAI）を使うと、この空白が一気に広がります。
ヘッドレス実行（claude -p）で --output-format stream-json を指定すると、処理の流れがJSONで1行ずつ流れてきます。ところが既定では、この流れに乗るサブエージェントの情報は tool_use と tool_result のブロックだけです。子が何を考え、何と書いたかは流れません。
これは、途中まで正しく動いていたのか、それとも最初から見当違いのことをしていたのかを、事後に判別できないことを意味します。
私が実際に踏んだのはこの穴でした。定期実行の仕組みを組んだ当初、私はエラー出力を捨てる書き方をしていました。失敗しても静かに終わるため、「動いているように見えて、実は数日前から目的を果たしていない」状態に気づくまで時間がかかりました。
無人運用の事故は、派手に落ちるのではなく黙って進むほうが怖いのです。だから私は、機能を足すより先にログの設計を決めるようにしています。
常時起動のMac miniで定期実行を集約する構成そのものは、こちらの記事にまとめています。
--forward-subagent-textとは｜v2.1.211で追加された可視化の仕組み
2026年7月16日（日本時間。GitHubのリリース表記は7月15日23:02）に公開された Claude Code v2.1.211 で、--forward-subagent-text フラグと CLAUDE_CODE_FORWARD_SUBAGENT_TEXT 環境変数が追加されました。
公式のCHANGELOGには「サブエージェントのテキストと思考を stream-json 出力に含める」と記載されています。変化はシンプルですが、無人運用にとっては意味が大きい更新です。
- 既定: stream-json に流れる子の情報は
tool_useとtool_resultのブロックだけ - フラグを立てると: 子のテキストブロックと思考（thinking）ブロックも同じ流れに乗る
公式ドキュメントは、この目的を「各サブエージェントのトランスクリプトを再構成できるようにするため」と説明しています。子が何をしたかの断片ではなく、子の記録そのものを組み直せるという位置づけです。
parent_tool_use_idで親子をひもづける
複数のサブエージェントを並列で走らせると、流れてきた発言が「どの子のものか」が問題になります。ここで効くのが parent_tool_use_id です。
公式ドキュメントによると、サブエージェントのメッセージは assistant / user メッセージとして流れ、その parent_tool_use_id にはそのサブエージェントを起動したツール呼び出しのIDが入ります。本体の会話から出たメッセージは、このフィールドが null になります。
つまり、混ざって流れてきたログを、後から親子関係で組み立て直せます。並列実行のログが「誰の発言か分からない一本の川」にならずに済む、という点が実務では効きます。
サブエージェントそのものの使い方、並列・分離処理の設計はこちらで解説しています。
読者特典・無料ダウンロードClaude Codeを「素のまま」使うな無料でダウンロード →使い方｜フラグ1つ、または環境変数1つ
使い方は難しくありません。ヘッドレス実行で stream-json 出力と組み合わせて指定します。
claude -p "レポートを作成して" --output-format stream-json --forward-subagent-text実行環境全体で有効にしたい場合は、環境変数でも同じことができます。
export CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1フラグはその実行だけ、環境変数はその環境全体に効く、という使い分けです。ただし私は常時オンにはしていません。理由は後述の落とし穴で説明します。調査したいジョブや、落ちたジョブを再実行するときにだけ立てる運用にしています。
私のログ設計｜「見る頻度」で3層に分ける
可視化の手段が増えても、全部を1か所に流し込めば今度は量に埋もれます。人間が見ないログは、無いのと同じです。
そこで私は、無人ジョブのログを見る頻度が違う3つの層に分けています。
第1層: 通知（毎日見る・1行）
ジョブが終わったら、成否と要点だけをチャットに1行流します。ここは「異常に気づくため」だけの層なので、情報を増やしません。詳しく書くほど、毎日読み飛ばすようになるからです。
設計上の要点が1つあります。通知は、AI本体ではなくAIを呼び出している側（シェルなどの外側）から送ることです。AIが落ちたときこそ通知が必要なのに、AI自身に通知させると、落ちたときには通知も来ません。
第2層: 実行ログ（何かあったときに見る・全文）
1回の実行で流れた stream-json を、丸ごとファイルに残します。普段は誰も読みません。異常に気づいたときだけ開く層です。
--forward-subagent-text の挿し所はここです。第1層に流すには詳細すぎ、しかし障害を追うときには絶対に欲しい情報——サブエージェントの発言と思考は、まさにこの層の性格に合っています。
第3層: 健康チェック（週1で見る・動いていること自体）
見落としやすいのは「失敗した」ではなく「そもそも起動していない」ほうです。失敗は通知が出ますが、起動しなければ通知すら出ません。無音は正常と区別がつかないのです。
そこで、ジョブが動いたこと自体の記録を別に残し、週1で「予定どおりの回数走っているか」だけを見ます。中身ではなく、脈があるかどうかを見る層です。
可視化したログで、実際に何を見るのか
サブエージェントの中身が流れるようになっても、全文を読むわけではありません。障害を追うときに開くのは、だいたい次の3か所です。
1. 分岐点｜どの指示をどう解釈したか
子のAIが最初に何を「やるべきこと」と受け取ったかが分かると、失敗の大半はそこで説明がつきます。結果だけを見ていると「なぜかおかしな成果物が出た」で終わりますが、最初の解釈が見えると指示文のどの一語が曖昧だったかまで特定できます。直すべきは子の出来ではなく、渡した指示のほうだった、というケースが実際は多いです。
2. 手戻り｜途中で方針を変えた場所
思考が流れると、子が途中で方針を変えた箇所が見えます。ここは指示の矛盾を検出するセンサーとして使えます。AIが迷った場所は、たいてい人間が読んでも曖昧な場所だからです。翌日の指示文を直す材料は、この迷いの跡から拾えます。
3. 沈黙｜期待した作業をしていない区間
「やったはずのことをやっていない」は、結果だけ見ても分かりません。ログを時系列で見て、想定した工程に触れていなければ、指示が届いていないか、条件分岐で飛ばされています。何が起きたかより、何が起きなかったかのほうが、無人運用では重要な情報になります。
実運用の落とし穴3つ
1. 思考まで流すとログが太る
思考は本来ユーザーに見せる前提の出力ではないため、量が読めません。全ジョブで常時オンにすると、実行ログが一気に膨らみます。
私が常時オンにしないのはこれが理由です。既定はオフ、調査するときだけオン。可視化は「常に全部見る」ことではなく、「必要なときに遡れる」ことが目的だと割り切ります。
2. ログに機密が乗る面が広がる
子の発言や思考まで残るということは、そこに書かれた内容もそのままファイルに落ちるということです。ログの置き場所と共有範囲を、オンにする前に確認してください。
可視化とは、これまで消えていた情報を保存し始める行為です。見えるようにする範囲を広げるときは、同時にその保管先も設計対象になります。
3. エラー出力を捨てない
最後は、フラグ以前の話です。定期実行のコマンドでエラー出力を捨ててしまうと、どれだけ可視化の仕組みを足しても、肝心の失敗が握りつぶされます。私が数日気づけなかった原因はこれでした。
可視化フラグは「動いた中身」を見せてくれますが、「そもそも動かなかった」は外側の設計でしか捕まえられません。無人運用にはコストの規律も同じように効いてきます。
まとめ｜見えるようにしてから、任せる範囲を広げる
v2.1.211 の --forward-subagent-text は、これまで観測できなかったサブエージェントの中身を stream-json に流せるようにするフラグです。parent_tool_use_id で親子をひもづけられるため、並列実行のログも後から組み立て直せます。
ただし、可視化はフラグ1つで完成しません。通知・実行ログ・健康チェックの3層に分け、それぞれ情報量と見る頻度を変える。そのうえで、詳細な可視化は必要なときだけ立てる。この形にして初めて、無人運用は「放っておいても気づける」状態になります。
AIに任せる範囲を広げる前に、まず見えるようにする。私たちが無人稼働を積み上げてきて、順番として正しかったと感じているのはこの一点です。
Claude Codeを業務にどう組み込むか、無人運用をどこから始めるかは、こちらにまとめています。
Claude Codeを「素のまま」使うな
設定で差がつく——CLAUDE.md・権限・スキルの実物を公開（全24ページ）
素のClaude Codeは"優秀な新入社員"。仕事を教えるほど、自分専用になります。覚えさせる4点セット——会社の説明書（CLAUDE.md）・権限の柵・手順書（スキル）・フォルダの地図——を、1人会社の実運用からコピペで使える型つきで公開します。
- そのまま書き換えて使えるCLAUDE.mdの型
- お金と送信をAIに触らせない「3段階の柵」
- 1回教えたら何度でも動く、手順書のコピペ雛形
- AIが迷子にならないフォルダ構造の3原則
毎週金曜の無料ニュースレター「ひとりAI経営」の購読特典です。メール登録後すぐ、ダウンロードページのご案内が届きます。あわせて、AI活用に関するお知らせやお役に立てそうなご案内をお送りすることがあります。解除はいつでも1クリック。
御社の業務に合わせたClaude Code導入支援
「AIツールを導入したが、現場で使われない」を終わらせる。
業務課題のヒアリングから設計、ハンズオン実践、運用定着まで一貫して支援します。