昨年11月下旬、卸売クライアント向けのWooCommerceビルドを3週間進めていました。約30個のカスタム投稿タイプ、オーダーメイドの価格設定エンジン、条件分岐ロジックが異常に多いチェックアウトフロー。開発者は私だけでした。そしてプラグイン層、テーマオーバーライド、REST APIエンドポイント間のコンテキスト切り替えで何日も失っていました。
そこで私はClaude Codeサブエージェントを本格的に並列実行することに決めました。試験的ではなく、複数のエージェントが同時に動作し互いに邪魔しないように作業分解方法を実際に再構築しました。
ここに学んだことをまとめました。最初の失敗も含めて。
---
Claude Codeでの「Subagents」が実際に意味すること
この言葉は人によって使い方がまちまちです。Claudeのエージェンティックフレームワークでは、サブエージェントは単にオーケストレーター（調整役）からスコープを絞ったタスクを受け取り、それを実行して出力を返すClaudeインスタンスです。オーケストレーター（それ自体がClaudeセッションである場合もあります）は作業をどのように分割するか、どのサブエージェントを起動するか、そして結果をどのように組み合わせるかを決定します。
実際には、サイトとアプリケーションを構築するほとんどの開発者にとって、これは同じコードベースに対して、それぞれが焦点を絞ったClaude Codeコンテキストを持つ複数のターミナルセッションを実行することを意味します。オーケストレーションはスクリプト経由で自動化されることもあります。実際のところ、多くの場合は私がNotionの計画ドキュメントから各エージェントが何をしているかを手動で調整しているだけです。
順序実行と並列実行の違い
順序実行でのエージェンティック作業は、ほとんどの開発者がデフォルトで選ぶもので、クラウドにタスクAを実行させて待つ、その後タスクBを実行させるというものです。シンプルな場合は問題ありません。しかしAとBが互いの出力に依存していない場合、時間を無駄にしています。
並列サブエージェントは独立したワークストリームで同時実行されます。前述したWooCommerceプロジェクト：一方のエージェントが価格設定エンジンロジックをリファクタリングしている間、もう一方がREST APIコントローラー全体でPHPDocコメントを生成していました。重複がなく、両方とも1つ完了するのに必要な時間でほぼ完了しました。
---
実際に作業分割を構造化する方法
これは誰も十分に明確に説明していない部分です。エージェントセットアップは簡単です。難しいのは何を分割するかを把握することです。
2022年の痛い機能統合の競合発生後に私が考案したシンプルなルールを使用しています：同じセッション中に2つのエージェントが同じファイルに触れてはいけません。絶対です。それが保証できなければ、並列実行タスクではありません。
並列実行前の計画ステップ
何かを起動する前に、短いタスクマニフェストを書きます。特に凝ったものではなく、プレーンテキストファイルまたはNotionページに以下を含めるだけです：
- タスク名と1文の説明
- スコープ内のファイル（明示的なリスト）
- スコープ外のファイル（エージェントが寄り道したくなるかもしれない隣接する要素）
- 期待される出力形式
- エージェントが必要とするコンテキスト（コードベースにはないもの）
これはおそらく15分ぐらいです。本当に多くの競合から私を救ってくれています。
---
私が最も頻繁に分割する3つのワークストリームタイプ
Seahawk での12,000以上のサイト構築と、傍らでの個人クライアントワークを通じて、並列化の候補として繰り返し登場する同じカテゴリーに気づきました。
1. ドキュメントとコード生成
一方のエージェントがコードを書くか、リファクタリングします。もう一方は異なるモジュールのドキュメント、テスト、またはコメントを書きます。これらはほぼ競合しませんし、両方とも手動で行うのは本当に退屈です。WooCommerce卸売プロジェクトでは、1つのサブエージェントが価格設定関数用のPHPUnitテストスタブを生成している間に、別のエージェントがカスタム管理者列を構築していました。テストスタブには約4分かかりました。管理者列には12分かかりました。その4分を待つことは何もありませんでした。
2. フロントエンドとバックエンドの分離
フロントエンドとバックエンドが明確に分離されたディレクトリに存在する場合（そうすべきですが、それは別の投稿です）、これは自然な分割です。/resources/js でReactコンポーネントを構築するサブエージェントを実行させながら、別のエージェントが/app/Http でLaravelコントローラーを配線していたことがあります。唯一の調整ポイントは、いずれのエージェントも開始する前にAPIコントラクトに合意することでした。それをプロジェクトのルートにあるAGENTS.md ファイルに書きました。両方のエージェントがそれを参照しました。
3. モジュール単位のリファクタリング
大規模なリファクタリングは順序立てて行うと本当に大変です。たとえば、8つの機能モジュールがあり、それぞれが同じタイプの変更（非推奨メソッドの更新、新しいヘルパーへの移行など）が必要な場合、それらをエージェント全体に分割します。かつて、4つの同時エージェントがWP_Query ループから リポジトリパターンへの移行を行うレガシープラグインを実行しました。各エージェントは2つのモジュールを取得しました。1時間以内に完了しました。順序立てて行うと半日になるはずでした。
---
ツール設定：実際に使っているもの
複雑なインフラストラクチャを持っているふりはしません。実際のセットアップは：
- Claude Code を MacBook Pro M3 の複数の
tmuxペインで実行 - プロジェクトのルートにある共有
AGENTS.mdファイルで、規約、ファイル所有権、ワークストリーム間のAPIコントラクトを定義 - エージェント単位のGitブランチ。常に。ブランチが20分だけしか存在しなくても
- マージ前に
git diff --statを素早く実行して、サプライズをキャッチ
AGENTS.md ファイルはおそらく、過去1年間のワークフローに追加した最も有用な単一のものです。プレーンなマークダウンファイルで、任意のエージェント（または人間も同様に）にプロジェクトの規約、どのファイルがどのワークストリームに属しているか、何を触るのを避けるべきかを伝えます。これはCONTRIBUTING.md のようなものですが、AI コンテキストウィンドウ用に書かれています。
コンテキストウィンドウ管理について
これは人々が怠け者になり、その後混乱する場所です。各サブエージェントは独自のコンテキストを持っています。つまり、エージェントBがエージェントAが決定したことを知る必要がある場合、明確に伝える必要があります。それは自動的に知られることはありません。
これは、各エージェントがチャンクを完了した後に手動で更新するSESSION_LOG.md を保持することで処理します。最大3～5個の箇条書きです：何が行われたか、何が変わったか、次のエージェントが知る必要があることです。オーバーヘッドは低いです。別の方法は、エージェントがコードを破壊する仮定をすることで、そのオーバーヘッドはずっと高いです。
---
どこで失敗するか（つらい経験から）
Seahawk は昨年春、ファイル所有権を適切に定義せずにモノレポ全体でサブエージェントを実行しようとした金融技術ダッシュボードプロジェクトを実行しました。2つのエージェントが両方とも共有utils/formatters.ts ファイルを更新することにしました。どちらも他のことを知っていませんでした。結果のマージは技術的には問題ありませんでしたが、意図の調整に40分を費やしました。完全に回避可能でした。
繰り返し見られる失敗モード：
- 共有ユーティリティファイル。これらはトラップです。それらをロックダウンしてください。サブエージェントが共有ユーティリティを更新する必要がある場合、そのタスクは並列実行ではなく、単独で実行される必要があります。
- 曖昧なタスク説明。エージェントに「auth モジュールをクリーンアップしろ」と指示すると、コンテキストに何が含まれているかによって解釈が大きく異なります。具体的に指示してください。「
AuthController.phpをリファクタリングして、app/Repositories/UserRepository.php に既に定義されているUserRepositoryインターフェースを使用するようにしてください。インターフェース自体は変更しないこと。」そうした指示なら安全です。 - ブランチの分離がない。すべてのエージェントをメインで実行するのは、刺激的な金曜日の午後を生み出す方法です。ブランチはコストゼロです。
- マニフェストをスキップしている。わかってます、オーバーヘッドに感じるんですよね。でもやってください。マニフェストをスキップするたびに、1時間以内に後悔しています。
---
実際の並列実行、ステップバイステップ
先週の火曜日の Shopify から WooCommerce への移行プロジェクトのセッションはだいたいこんな感じでした（匿名化していますが、構造は完全に正確です）。
- Notion でタスクマニフェストを書きました。並列化可能として特定された4つのタスク。
- 4つの git ブランチを作成しました： agent/product-import、agent/tax-logic、agent/rest-endpoints、agent/admin-ui。
- 4つの
tmuxペインを開き、各ペインで Claude Code セッションを1つずつ実行。 - 各セッションの開始時に
AGENTS.mdの関連セクションをコンテキストとして貼り付けました。 - 各エージェントにタスクプロンプトを与え、特定のファイルを参照させました。
- 4つすべてを同時に実行。コーヒーを淹れました。実は温かいうちに飲めました。奇跡に感じました。
- 各ブランチの出力をレビュー。PHP に対して
phpcsを実行、タッチした JS に対してeslintを実行しました。 - 順序に従ってマージ： product import 最初（他は軽い依存関係がスキーマにあった）、次に tax logic、次に REST endpoints、最後に admin UI。
SESSION_LOG.mdを変更内容で更新しました。
4つのタスク全体の合計時間：約35分。順序実行の予想時間は90分から2時間でした。これなら大満足です。
---
これが代替する（そうでない）もの
並列サブエージェントは思考の代替ではありません。その15分の計画ステップは、本当にあなたがアーキテクチャの仕事をしています。エージェントは実行します。何を構築するか、どのようにピースが合致するか、出力が実際に正しいかどうかはまだあなたが知る必要があります。
エージェントの出力はすべてレビューしてからメインにタッチさせます。毎回です。マルチサイトセットアップで古いデータの問題を引き起こしたであろうキャッシングレイヤーを自信満々に書いたサブエージェントを引っかけたことがあります。コードは良く見えました。その特定のコンテキストに対して論理的に間違っていました。読んだから気づけた。
Anthropic 自身のエージェントタスクに関するガイダンスは、不可逆的なアクション前に人間のチェックポイントの重要性を明確に示しています。それは企業のボイラープレートではありません。実際に重要なアドバイスです。特にエージェントがデータベースへのアクセスを持つか、マイグレーションを実行している場合。
これが代替しないもう1つのこと：クライアントとのコミュニケーション。エージェントは機能を構築できます。デッドラインがシフトした理由をクライアントに説明することや、スコープクリープの周辺の期待を管理することはできません。その部分はまだあなたのものです。
---
FAQ
Claude Code サブエージェントを実行するのに特別な API アクセスやツールが必要ですか？
珍しいセットアップは必要ありません。Claude Code は Anthropic のターミナルベースのコーディングツールで、複数のインスタンスを個別のターミナルセッションで実行できます（私は tmux を使用しています）。API に直接ヒットしている場合は、十分なレート制限を持つ Claude API キーが必要です。重い並列ワークロードの場合は、セッション中のスロットリングに見舞われないよう、開始前にレート制限の層をチェックしてください。
エージェントが共有ファイルで競合するのを防ぐにはどうしたらいいですか？
ファイルの所有権を開始前に定義してください。私が説明したAGENTS.mdの規約はうまく機能します。2つのタスクが共有ユーティリティファイルの変更を必要とする場合、その2つのタスクを並列化しないでください。まず共有ユーティリティの変更を実行してコミットし、その後、その清潔なベースから他のタスクを並列で実行してください。
これは大規模プロジェクトでのみ有用ですか？
正直なところ、そうではありません。新機能コードと一緒にドキュメンテーションを生成したい単一ページのサイトで使用してきました。計画のオーバーヘッドは十分に低いため、控えめな時間短縮でもそれを正当化します。とはいえ、プロジェクトに並列化可能な異なるタスクが5未満しかない場合、セットアップ時間が利益を上回り始めます。判断力を使ってください。
エージェントが悪い出力を生成した場合はどうなりますか？
レビューで捕捉し、ブランチを破棄して、より具体的なプロンプトで再試行します。これがブランチ分離の全体的なポイントです。悪いエージェント出力はレビューと再プロンプトの時間がかかります。ブランチ単位のエージェント規則に従っていれば、コードベースの破損にはコストがかかるべきではありません。
手動で行う代わりに、オーケストレーションを自動化できますか？
はい、繰り返されるワークフローの場合、その価値があります。事前定義されたプロンプトとコンテキストを使用して、順序付けられたClaude Codeコールをスピンアップする単純なBashスクリプトを書きました。完全に自動化された並列オーケストレーションの場合、プログラムでエージェントをスポーン、出力を収集、依存関係を処理するオーケストレーターレイヤーを構築します。これは大きなエンジニアリング投資です。ほとんどのフリーランサーと小規模なエージェンシーにとって、tmuxとタスクマニフェストを使用した手動調整で十分です。
---
正直なところ、並列サブエージェントは私を劇的によりよい開発者にしませんでした。実行がボトルネックだった特定のタスク種別で、より速い開発者にしました。思考はまだ私のものです。アーキテクチャの決定、クライアントコール、コードレビュー。すべてまだ私のものです。
しかし、退屈な実行部分？取り戻せるあらゆる分の時間を歓迎します。