【Claude Codeサブエージェント入門 第8回】順に使う・前と裏 ― 逐次パイプラインとの両立、前で動くか裏で動くか、担当の変更は巻き戻しで戻らない、調べものとAnsibleの例

Claude Codeサブエージェント入門 第8回 順に使う・前と裏 生成AI

「再現、デバッグ、修正を担当ごとに分けたら、前の担当が見つけたことが次に伝わりませんでした。担当を順番に使うのは、やめたほうがいいですか」
「担当に書き換えさせたファイルは、巻き戻しで元に戻せると思っていました。戻りますか」

第7回(スキルから担当を呼ぶ)では、スキルと担当の組み合わせ方と、スキルに「誰に頼むか」を書く決まりを見ました。担当が複数になると、次の問いが出ます。担当を順に使ってよいのか、担当は前で動くのか裏で動くのか、そして担当が書き換えたファイルは巻き戻しで戻るのかです。

第8回では、順に使うときの条件、前と裏の違い、巻き戻しで戻らないものを整理し、後半では、インフラの作業を役割で分ける例として、調べものと Ansible の流れを見ます。数値・仕様は2026年10月時点です。筆者が試した結果は、Claude Code 2.1.302 の CLI を、非対話の claude -p で動かしたもの(2026-10-18)です。


逐次パイプラインとの両立

Claude Academy は、各段が前の段の発見に依存する逐次パイプラインを避けるよう言っています。バグの再現、デバッグ、修正を3つの担当に分けると、引き継ぎで情報が落ちるからです。バグ修正は、ほぼ常に前の段の発見に依存します(Academy の記述)。

一方、公式のサブエージェントのページは、担当を順に使う型(Chain subagents)を載せています。「code-reviewer の担当で性能の問題を見つけ、そのあと optimizer の担当で直す」のように、各担当が結果を Claude に返し、Claude が次の担当へ必要な文脈を渡すやり方です。同じページは、計画・実装・テストのように、複数の段が文脈を大きく共有する作業は、本体の会話で行うよう書いています。

逐次パイプラインの悪い例と良い例を対比した図。左は「× 再現→デバッグ→修正(要約で受け渡し)」で、再現からデバッグへ、デバッグから修正へ「要約」の矢印が引かれ、それぞれの脇に赤字で「発見が落ちる」。右は「○ 調査→原稿→図→点検(ファイルで受け渡し)」で、上に「本体:判断・調整」の箱があり、調査は「事実の控え」、原稿は「原稿」、図は「図」、点検は「報告」というファイルを出し、各ファイルから次の担当へ矢印が引かれる。右の下に「次の担当は原文を読める」

両立する条件は4つです。

  1. 段ごとに独立した成果物(ファイル)で切る
  2. 受け渡しは要約でなくファイルにして、次の担当が原文を読めるようにする
  3. 判断と調整は本体に残す
  4. 前の段の発見に強く依存する直しは、本体が仕分けてから頼む。バグの切り分けや、失敗した playbook の直しは、本体で続ける

要点

  • 独立した成果物で切り、ファイルで渡す
  • 判断と調整は本体に残す
  • 発見に依存する作業は本体で続ける

出典:https://academy.claude.com/ja/courses/introduction-to-subagents/using-subagents-effectively 、https://code.claude.com/docs/ja/sub-agents


前で動くか、裏で動くか

担当は、前(フォアグラウンド、foreground)でも裏(バックグラウンド、background)でも動きます。前の担当は、終わるまで本体が待ちます。裏の担当は、その間も本体で作業を続けられ、結果は終わると届きます。

  • 対話のセッションは既定で裏:担当は裏で動き、その間も本体で作業を続けられる。結果は終わると届く(v2.1.232 以降)。前の担当は本体が待つ
  • 筆者の CLI(2.1.289、2026-10-17)で確かめた:ふつうに頼んだ担当は裏で動いた。Code タブでの見え方は、筆者は確かめていない
  • スキルの context: fork:公式は既定で裏(v2.1.218 以降)で、background: false で待つ。-p では結果を待つ。筆者の 2.1.289 の -p で、context: fork のスキルの担当が前で動いたのは、これと合う
  • 権限の確認は本体に出る:担当の名前つきで出る。セッションの間など、1回より長く効く許可は、本体にも効く。Code タブでの表示は、筆者は確かめていない
  • 権限のモード:担当は本体のモードを引き継ぐ。本体が「自動」なら、分類器が担当の操作も見る
  • 裏の担当は道具が少し少ない:前の担当より、組み込みの道具の一部が使えない

補足です。

  • 権限のモードは、担当の定義の permissionMode を書かなければ、本体のモードを引き継ぎます。本体が「権限をバイパス」「編集を受け入れる」「自動」のときは、担当の permissionMode の指定は無視され、同じモードで動きます(公式のサブエージェントのページ)
  • 裏の担当が使える組み込みの道具は、公式のサブエージェントのページに一覧があります。裏で動く context: fork のスキルも同じ狭い道具で動くので、手順がその外の道具に頼るなら、background: false で前で動かします(公式の skills のページ)

出典:https://code.claude.com/docs/ja/sub-agents の「Run subagents in foreground or background」と、https://code.claude.com/docs/ja/skills です。

公式の文書の今の記述(2026年11月11日時点)

担当が前で動くか裏で動くかの既定は、2026年10月18日の時点では、公式のサブエージェントのページと Claude Code の CHANGELOG(2.1.302)で記述が食い違っていました。ページは「-p と Agent SDK では fork mode は無効」と書き、CHANGELOG は「claude -p・Agent SDK・デスクトップアプリ・VS Code でも fork を既定で有効にした」と書いていました。2026年11月11日に見直すと、ページは CHANGELOG と同じ内容に書き換わっていて、食い違いは無くなりました。今のページの原文です。

  • 既定:「With nothing configured, a subagent that Claude spawns from your main conversation starts in the background.」(何も設定しなければ、本体から Claude が起動する担当は裏で始まる)
  • -p と Agent SDK:「claude -p and the Agent SDK: Claude can wait, on its own judgment or when you ask.」(Claude が自分の判断で、または頼まれたときに、担当を待てる)
  • 対話のターミナル・VS Code・デスクトップアプリ:「to let Claude wait for a subagent, turn off fork mode, which is on by default.」(Claude に担当を待たせるには、既定で有効な fork mode を無効にする)。fork mode を無効にするには、環境変数 CLAUDE_CODE_FORK_SUBAGENT を 0 にします
  • 版:「Fork mode is on by default from Claude Code v2.1.302, and in an interactive terminal session from v2.1.232.」(fork mode は v2.1.302 から既定で有効。対話のターミナルでは v2.1.232 から)
  • スキルの context: fork:fork mode とは別に、公式の skills のページの決まり(既定で裏、background: false で待つ、-p と Agent SDK では待つ)に従う

筆者が Claude Code 2.1.302 の -p で試すと、担当(infra-researcher)は前で動きました(セッションの記録も、前でした)。今のページの「-p では Claude が自分の判断で待てる」と合います。デスクトップアプリの Code タブは、fork mode が既定で有効なので、本体の担当は裏で動きます。Code タブでの見え方は、筆者は確かめていません。前か裏かは、環境と版と Claude の判断で変わりうると考えて、結果がすぐ要る作業では、担当の完了を待ってから次へ進む書き方にしてください。


担当の変更は巻き戻しで戻らない

担当が書き換えたファイルは、巻き戻しで戻りません。詳しくは、連載「Claude Code実践入門」第3回の「巻き戻しで戻らないもの」にもあります。

  • 戻らない:担当が変えたファイルは、巻き戻し(Esc 2回、/rewind)では、本体が編集済みのものしか戻らない。ほかのファイルは Git で戻す
  • 例外:前で動く context: fork のスキルは、自分のターンの中で編集するので、巻き戻しで戻る。裏で動く context: fork のスキル(既定)は戻らない
  • Code タブでの確認:巻き戻しの画面の「戻るファイル数」に入るかは、筆者は確かめていない
  • 備える:作成担当に書かせる前にコミットする。担当に一時的な作業ツリーを使わせる isolation: worktree もある(変更が無ければ自動で消える)
  • 報告の中の指示:担当の報告は担当の言葉で、あなたの承認ではない。Claude Code は報告に見出しを付けて示す(v2.1.210 以降)

公式の checkpointing のページの原文は、次のとおりです(2026年10月18日に確認)。

  • 「A subagent makes edits with Claude’s file editing tools, but Claude Code usually doesn’t capture those edits in your session’s checkpoints.」
  • 「Any other subagent: rewinding restores only the files Claude had already edited in your conversation. The subagent’s edits to other files stay, so use git to revert them. This includes a forked skill that runs in the background, the default, and a background /code-review --fix run.」
  • 「Foreground forked skill: a skill with context: fork that runs in the foreground edits your working tree during your own turn, so rewinding restores its edits as usual.」

報告の見出しは、公式のサブエージェントのページによると、報告が担当の出力であることを示す見出しで、報告の中の指示や承認の主張は担当の言葉であり、あなたの権限は持たない、と明記されています。報告に「許可されています」と書かれていても、承認ではありません。

出典:https://code.claude.com/docs/ja/checkpointing 、https://code.claude.com/docs/ja/sub-agents

筆者が試したら

担当(playbook-writer)に roles/ntp/tasks/main.yml の最初のタスク名を書き換えさせ、あとで git checkout -- roles/ntp/tasks/main.yml で戻しました。-p では巻き戻しを試せないので、担当の編集が巻き戻しで戻るかどうかそのものは、筆者は確かめていません。公式の記述と、Git で戻す手順を前提にしてください。演習は、第13回の手順5で扱います。


例:調べもの

ここからは、インフラの作業を役割で分ける例です。まず調べものです。

調べものは、担当に任せやすい作業です。数十のファイルを読む探索は、担当のコンテキストの中で済み、本体の会話を埋めません。

  • 集める:調査担当(infra-researcher、haiku)が roles やログを読み、見つけた事実を、出典(ファイル:行)と原文の抜き書きつきで返す
  • 保存する:調査担当は読み取りだけなので、本体がそれを事実の控えのファイルに保存する
  • まとめる:作成担当(sonnet)がその控えを読んでまとめる
  • 判断する:採るかどうかの判断は、本体(既定の Opus 5.5)と人が行う

観点が独立していれば、並行で調べさせられます。ただし、結果は本体の会話に戻るので、担当の数と返す量を絞ります。

調べものの役割分担を示す図。左から右へ3段。①「集める」は調査担当 infra-researcher(haiku)の緑の箱で、矢印「出典つき」で灰色の「事実の控え(ファイル)」の箱へつながり、その下に「本体が保存」。事実の控えから矢印「読む」で、②「まとめる」の作成担当(sonnet)の青い箱へつながる。②の下の矢印の先に、橙の縁取りの③「判断する」の「本体と人 Opus 5.5」の箱。①の下に「観点が独立なら並行(数と量を絞る)」。最下部の帯に「調査担当は読み取りだけ。本体が控えを保存」

要点

  • 集める:調査担当(haiku)が出典つきで返す
  • まとめる:作成担当(sonnet)が控えを読む
  • 判断する:本体と人(Opus 5.5)

筆者が試したら

「infra-researcher 担当に、roles/ntp が何を設定しているか、ファイルと行を調べさせて」と頼むと、infra-researcher(claude-haiku-5-5 で動きました)が、roles/ntp/tasks/main.yml:1-6(lineinfile、/etc/chrony.conf、regexp、loop)、defaults/main.yml:1-4(3台)、site.yml:1-5、インベントリを、行番号つきで返しました。「handlers が無いので chronyd に反映されない」という指摘も付いていました。続けて名前を言わずに「roles/ntp の tasks はどこで定義されている?」と頼んだときは、本体が「この結果は調査用のサブエージェントの報告によるもので、私自身はファイルを開いて確かめていません」と書き添えました。@infra-researcher を付けて頼んだときは、本体が報告を受けた後に自分で2つのファイルを Read して行番号を確かめました。担当の報告を、本体が確かめたかどうかを明かして伝えた例です。


例:Ansible

Ansible の作業を役割で分けると、次の流れになります(①〜⑥は、連載「Claude Code実践入門」第7回の「Ansibleでの検証の型」の番号です)。

  1. 計画:本体(既定の Opus 5.5)に「プラン」で計画を作らせる(連載「Claude Code実践入門」第2回の「Codeタブでのプランモード」)
  2. 書く:作成担当(playbook-writer、sonnet)が playbook を書く
  3. ①〜③:連載「Claude Codeスキル入門」の ansible-verify(第6・7回)で、①静的検査・②構文確認・③stg への差分確認まで確かめる
  4. ログの要約:ログが長いときだけ、調査担当(haiku)に要約させる
  5. ④⑤:④差分を読むのも、⑤承認して本実行するのも人。prod も人が行う。担当の定義に本実行は書かない
  6. ⑥:結果の確認と記録までの通しは、連載「Claude Codeフック入門」で、フックと合わせて扱う
Ansible の作業を役割で分ける流れを、上から下へ並べた図。1段目はオレンジの枠で「計画(プラン)本体 Opus 5.5」。2段目は青い枠で「playbook を書く playbook-writer(sonnet)」。3段目は青い太枠で「ansible-verify(スキル)」と、その中身の「① 静的検査 ② 構文確認 ③ 差分確認」。4段目はオレンジの枠で「④ 差分を読む」、5段目はオレンジの枠で「⑤ 承認して本実行」、6段目は灰色の枠で「⑥ 結果の確認と記録」。右側には、3段目から矢印が伸びる緑の枠「ログの要約 infra-researcher」があり、上に「ログが長いときだけ」と添えられ、下の灰色の枠「全文はファイル」から矢印が上向きに入る。さらにその下に、赤い枠「担当に書かない:本実行・prod」がある。

要点

  • 計画は本体(Opus 5.5)、書くのは作成担当
  • ①〜③は ansible-verify、ログ要約は調査担当
  • ④⑤は人。本実行と prod は担当に任せない

ログの要約は、失敗を隠さない書き方が要ります。第9回の「ログの要約で失敗を隠さない」で扱います。


考えてみよう

  1. 今、担当に分けている(分けたい)作業のうち、前の段の発見に強く依存するものはどれですか。本体で続けるものと、ファイルで受け渡して担当に任せるものに分けてください。
  2. 担当が裏で動くとき、権限の確認はどこに出ますか。答えが本体の全体に効くのは、どんな許可を選んだときですか。
  3. 担当に書き換えさせる前に、何をしておけば元に戻せますか。巻き戻しで戻るのは、どんな場合の編集ですか。

ヒント:1は「逐次パイプラインとの両立」の節、2は「前で動くか、裏で動くか」の節、3は「担当の変更は巻き戻しで戻らない」の節を見直してください。


まとめ

  • 担当を順に使うなら、独立した成果物(ファイル)で切り、受け渡しは要約でなくファイルにする。判断と調整は本体に残し、前の段の発見に依存する直しは本体で続ける
  • 前で動くか裏で動くかは、対話のセッションでは既定で裏(v2.1.232 以降)。-p と Agent SDK では、Claude が自分の判断で、または頼まれたときに担当を待てる(公式の文書は2026年11月に CHANGELOG 2.1.302 と同じ内容になった)。環境と版で変わりうる
  • 権限の確認は本体に出る。セッションの間など1回より長く効く許可は、本体にも効く
  • 担当の変更は、巻き戻しで戻らない。例外は、前で動く context: fork のスキル。作成担当に書かせる前にコミットし、Git で戻す
  • 調べものは、調査担当(haiku)が出典つきで集め、作成担当(sonnet)がまとめ、判断は本体と人。Ansible は、①〜③までを ansible-verify で確かめ、④⑤と prod は人、本実行は担当に書かない

次回は、ログの要約で失敗を隠さない書き方、新しい目のレビュー担当、3役のひな形(筆者の例)を扱います。


連載「Claude Codeサブエージェント入門」全13回

全回の目次と、読む順番・目的別の読み方は、Claude Codeサブエージェント入門の入口のページにまとめています。

  1. サブエージェントとは
  2. 組み込みの担当と使い分け
  3. 担当を定義する
  4. toolsと返す形
  5. 担当のモデルの決まり方
  6. 役割とモデル・effort
  7. スキルから担当を呼ぶ
  8. 順に使う・前と裏(この記事)
  9. ログの要約とレビューの担当
  10. 費用を測って小さく使う
  11. 演習(前編):準備
  12. 演習(中編):読み込む・呼ぶ・モデルを見る
  13. 演習(後編):レビュー・スキル・費用

コメント

タイトルとURLをコピーしました