Article

Claude Codeでパイプライン型のエージェント作業を設計する方法

調査→計画→実装→レビューを流れ作業にする、Claude Codeのパイプライン型エージェント設計を整理します。サブエージェントの直列連結・中間成果物の受け渡し・各段のレビューゲート・失敗時の戻し方まで、公式のchain subagentsに沿った実務手順です。

This article is not published in this language yet, so the Japanese version is shown instead.

Claude Codeで「調査して、計画して、実装して、レビューする」を毎回手で繋ぐと、コンテキストが溢れて精度が落ちます。本記事は、この一連の流れをパイプライン（直列の流れ作業）として設計する方法を、中間成果物の受け渡しと失敗時の戻し方まで整理します。

結論：直列の段に分け、間に中間成果物とレビューを置く

Anthropic公式のサブエージェント解説には「chain subagents（サブエージェントを連結する）」というパターンがあります。「多段のワークフローでは、サブエージェントを順番に使うようClaudeに頼む。各サブエージェントはタスクを終えて結果をClaudeに返し、Claudeが次のサブエージェントへ関連コンテキストを渡す」と説明されています（Create custom subagents）。

要点は4つです。

段に分ける：調査・計画・実装・レビューを別々のサブエージェントにする
中間成果物：各段の出力をファイル（NOTES.md等）に書き出して次段の入力にする
レビューゲート：実装に進む前など、要所で人間が中身を確認する
戻し方：失敗した段だけやり直せるよう、段の境界をコミットで区切る

並列に独立調査を散らす「ファンアウト型」とは設計が異なります。違いは「複数のAIエージェントで調査を並列化する実践パターン」に分けてあり、本記事は「順番に流す」直列型に集中します。

パイプラインの基本構造

公式どおり、各サブエージェントは独立したコンテキストで動き、結果だけがメイン会話に戻ります。サブエージェントは別のサブエージェントを起動できないため、段の連結はメイン会話が司令塔になって行います。

依頼文の最小形はこうです。

調査エージェントで src/payment 周辺の決済フローと既存リトライ処理を調べ、
結果を NOTES/RESEARCH.md に書き出して。
次にその NOTES/RESEARCH.md を入力に、計画エージェントで実装計画を NOTES/PLAN.md にまとめて。
PLAN.md は私が確認するので、そこで一度止めて。

ここでのコツは、段から段へ生の会話を引き継がず、ファイル（中間成果物）を介すことです。会話で引き継ぐとメインコンテキストが各段の詳細で埋まりますが、ファイル経由なら次段は要約だけを読めます。

段ごとの設計

典型的な4段のパイプラインです。

段	役割	モデルの目安	出力（中間成果物）
調査	コードと前提の把握	速いモデル（Haiku等）	`NOTES/RESEARCH.md`
計画	実装計画の作成	標準〜上位	`NOTES/PLAN.md`
実装	コード変更とテスト	標準	コード差分＋コミット
レビュー	別コンテキストで検証	標準〜上位	指摘リスト

調査段は読み取り専用で十分なので、組み込みのExploreや読み取り専用のカスタムサブエージェントを使うとコストを抑えられます。レビュー段は、実装したのと同じ会話で評価させると自分のコードに甘くなるため、新しいコンテキストで走らせます。役割別の定義の書き方は「Claude Code用カスタムエージェントの作り方と役割設計」にあります。

中間成果物の受け渡し

パイプラインの品質は、段と段の間に何を残すかで決まります。各中間成果物には次を含めます。

何を確定したか：調査でわかった事実、計画で決めた方針
未確定事項：要検証として明示し、断定しない
次段への入力：次のエージェントが読むべきファイルパスや前提

NOTES/配下にMarkdownでためていくとGitで差分が追え、失敗時にどの段の出力が悪かったかを切り分けられます。

レビューゲートと人間の関与

全段を自動で流すと、調査の誤りが計画と実装に伝播し、最後にまとめて破綻します。要所に人間のゲートを置きます。

計画後：PLAN.mdを人間が読み、方針・スコープ・依存追加を確認してから実装へ
実装後：git diffを人間が読んでからレビュー段・コミットへ

「計画後に一度止めて」と依頼文に明示し、勝手に実装まで走らせないようにします。設計や互換に関わる判断を人間が持つ理由は「AIに任せすぎないためのClaude Code運用ルール」に整理しています。

失敗時の戻し方

パイプラインは途中で壊れる前提で設計します。段の境界をコミットで区切っておくと、失敗した段だけやり直せます。

調査が浅い：RESEARCH.mdを破棄し、スコープを絞って調査段だけ再実行
計画が筋違い：実装に進まずPLAN.mdを作り直す（コードは未変更のはず）
実装が破綻：git restoreや/rewindで実装段の前へ戻し、計画から見直す

段をまたいで一気に進めていないからこそ、戻すコストが小さくなります。

並列化・Agent Teamsとの境界

各段の中で独立した調査が複数あるなら、その段の内部だけ並列化できます。一方、段どうしが互いに通信しながら長時間並走する必要が出てきたら、それはパイプラインではなくagent teamsの領域です。公式も、サブエージェントは1セッション内で完結し、セッション間で通信させたい場合はagent teamsを使うと案内しています。まずは直列パイプラインで十分なことが多く、最初からチーム構成に手を広げないのが安全です。サブエージェントの仕組みそのものは「Claude Codeのサブエージェントとは？使いどころと注意点」にまとめています。