世界を動かす技術を、日本語で。

Claude Codeのサブエージェントを使って開発を並列化する方法

概要

  • AIエージェント を活用したエンジニアリングワークフローの革新事例
  • 並列処理・自動化・コンテキスト分離 による効率的な開発プロセス
  • 専門エージェント によるチケット生成・実装・レビューの自動化
  • 実践例・設計思想・注意点 まで網羅的に解説
  • 実装用コマンド・エージェント定義 も付属

AIエージェントによるエンジニアリングワークフロー革新

  • AIとエージェント を活用し、グリーンフィールドなエンジニアリングメトリクスツールを1週間で開発
  • WebアプリのUI改善や新機能追加時、 Claude Code にホームページの再設計を依頼
  • 新機能「View All Insights」リンク追加時、未実装ページへのリンクで 404エラー 発生
  • 従来は 要件定義→UI設計→API設計→実装 という直列・手動プロセスが必要
  • 今回は カスタムコマンド でチケット生成を自動化し、 product-manager/ux-designer/senior-software-engineer の三者エージェントが並列で要件を具体化
  • 完成したチケットを 実装用コマンド に渡し、実装・レビューもエージェントが自動実行
  • 人間は他の作業に集中可能、失敗してもやり直しコストが低いため高速な試行錯誤が可能
  • エージェントが活発に動きすぎてAPIレートリミットに到達するほどの 真の並列化 を実現

エージェントワークフローの3原則

  • 1. 並列実行によるスピード向上

    • 独立タスクを 同時進行 で処理し、最長タスクの時間で全体完了
    • 例:Stripe API連携なら、 バックエンド・フロントエンド・QA・ドキュメント 各エージェントが同時着手
  • 2. シーケンシャルな引き継ぎで自動化

    • 複雑な工程は 自動組立ライン化 し、出力物を次工程に渡す
    • 例: 要件定義→実装→コードレビュー をエージェントが順に担当し、フィードバックループも自動化
  • 3. コンテキスト分離による品質担保

    • 各エージェントが 専用のコンテキストウィンドウ を持ち、専門領域に集中
    • 例:product-managerは ビジネス要件、ux-designerは UI/UX、senior-software-engineerは 実装 にそれぞれ200kトークン全振り
    • 情報劣化を防ぎ、各工程の品質を最大化

応用例

  • コードベースドキュメント生成
    • モジュール内の各関数やクラスごとにサブエージェントを割り当て、コメントや図の自動生成
  • 大規模リファクタリング
    • 75ファイルで使われている関数の非推奨化も、各ファイルごとにサブエージェントで安全に置換
  • インシデントレスポンス分析
    • 複数マイクロサービスのログ解析を並列化し、タイムラインを統合レポート化
  • プロダクトマネージャーのユーザーフィードバック集約
    • 500件のアンケートを分割してサブエージェントでタグ付け・要約し、最終レポートに集約
  • セキュリティエンジニアによるOSS監査
    • CVEスキャン・GitHub issue調査・コードパターン分析をサブエージェントで並列実施

実践上の注意点・トレードオフ

  • コスト・利用制限管理
    • エージェント連鎖やループはトークン消費が増大し、 Claude Pro/Max 等の上限に早く到達
    • 生産性・アウトプット向上とのトレードオフを意識
  • 非決定性との向き合い方
    • LLMの サブエージェント定義やプロンプト変更 で全体の挙動が変化しやすい
    • デバッグの難しさもあるが、創造性発揮のポイント
  • 集約(リデュース)工程の難易度
    • 複数エージェントの成果物を統合する最終工程が最も難しい
    • 各サブエージェントの出力を 個別ファイル保存 で監査性・デバッグ性を確保
  • プロンプトは脆弱な依存物
    • エージェント定義は コード同様にバージョン管理・テスト・監視 が必須
    • モデルのアップデートによる挙動変化も評価スイートで検知

実装用コマンド・エージェント定義(抜粋)

  • add-linear-ticketコマンド

    • 高レベルな依頼を受け、 product-manager/ux-designer/senior-software-engineer 三者エージェントが並列で要件・仕様・技術案を生成
    • 工数2日超の場合は自動でサブチケット分割
    • 生成チケットには ビジネス背景・期待動作・調査要約・受入基準・依存関係・実装ノート を網羅
  • product-manager agent

    • 要件定義・ユーザーストーリー・非機能要件・リスク・ロールアウト計画の明確化
  • ux-designer agent

    • ユーザーフロー・ワイヤーフレーム・全状態・アクセシビリティ要件の設計
  • senior-software-engineer agent

    • 工程分解・TDD・小PR・安全なマイグレーション・観測性担保・ロールバック戦略を実践
  • code-reviewer agent

    • 正確性・可読性・セキュリティ・設計原則遵守を重視し、構造化されたレビュー報告を生成

まとめ

  • AIエージェントの並列活用 で、開発の生産性・品質・スピードを劇的に向上
  • 失敗コストが低く、試行回数を最大化 するアプローチ
  • プロンプト設計・ワークフロー設計の工夫 が成功のカギ
  • 自分なりの分解・並列化パターン を見つけることで、より強力な問題解決力を獲得可能

Hackerたちの意見

この分野でプロジェクトを作ったことがある者として、これは本当に信頼性が低いです。サブエージェントは完全なシステムプロンプトを受け取らないから、プロジェクトに関してはかなり盲目的に動いてしまいます。そのせいで、プロジェクトの知識が不足していると、変な解決策に行き着いたり、「もっとシンプルな解決策を作ってみるよ」とか言い出したりします。サブエージェントは非常に特化したタスクにだけ使うべきだと思います。監視が難しくて、複雑なコードベースでは失敗しやすいからです。メインのClaudeインスタンスがサブエージェントにうまく引き継げない場合や、サブエージェントがメインのClaudeにうまく返さない場合、すぐに問題が起きます。それに、リファクタリングにエージェントを頼るのもやめた方がいいです。コードベースのリファクタリング能力はすぐにダメになります。

サブエージェントは作業をするためには使わないですね。分析するのが一番得意です。「テストカバレッジを評価して」とか「プロジェクトがスタイルガイドに従っているか確認して」とか。こうすることで、「メイン」のコンテキストにはレポートだけが届いて、大量のテスト出力や複数のファイルを読むスペースを無駄にしないです。

コードベースのリファクタリング能力はすぐにダメになります。まさにその通りです。Claudeにコードを一つのファイルから別のファイルに移動させようとしたんですが、いくつかのコードが消えちゃったり、途中で変更されちゃったりしました。人間はリファクタリングのための戦略を持っていて、「ファイルの先頭から始めて、移動させる必要のあるコードを切り取って、新しい場所に貼り付ける」とかやりますよね。でもLLMはクリップボードを持ってないから(まだ!)、これができないんです。Claudeは、開始ファイルと終了ファイルをコンテキストに保てる時だけ、信頼性のあるリファクタリングができます。これが大きなファイルだったので、情報が失われちゃったんです。それでも、直接の監視が必要です。

完全に同意します。いろんなことにエージェントを試してみました(エージェントのチームを作り始めたんです、アーキテクト、フロントエンドコーダー、バックエンドコーダー、QAなど)。失敗したプロジェクトに約50ドル使いましたが、コンテキストが汚染されて、結局プロジェクトを再作成しなければなりませんでした。それから、いくつかの部分をルールに移したり、スラッシュコマンドにしたりしたら、ずっと良い結果が出ました。サブエージェントはフリーランスの契約者みたいなもので(私も最近そうでした)、少ない引き継ぎ(リアルタイムでは不可能)や監視でうまくやれる時もあります。彼らの結果はアドバイスとしては良いけど、アクションにはならないです。彼らはあなたが何をしているか知らないし、彼らが出す情報で何をするかも気にしません。あなたが他のことをしている間に、彼らはあなたのために作業をしてくれるか、独立した結果を出すのを待っているだけです。彼らは既存の機能についての知識がほとんどなく、独立しては良い仕事をします。今、私がまだ持っているエージェントは3つと、現在作業中のものが1つあります。1: スキャフォールディング:今、私はたくさんの新しいプロジェクトを作ったり、時には壊したりしています。新しいことを試すときはスキャフォールディングエージェントを使います。彼らは「何をスキャフォールドするか」という一行の新しい指示から始まります(例:HonoとPostgres接続の新しいDockerコンテナ、R2、D1、AI Gatewayに接続する新しいCloudflareワーカー、またはSQSを使ったAWSサーバーレスAPIゲートウェイなど)。プロジェクトの構造を整え、GitHubリポジトリを作成してコミットしてくれます。私はそこから進めます。2: トリアージ:コードを読むだけでは明らかでない問題に直面したとき、場所といくつかのログを渡すと、エージェントは利用可能なもの(DBデータを含む)を使って、なぜその問題が発生するのかを最善の推測をしてくれます。最近の作業にバイアスされていないときに最も効果的に働くことが多いです。3: プレリリースチェックQA:このQAはシステム全体をテストします(基本的にすべての統合テストとエンドツーエンドテストスイートを呼び出して、この製品が既存のものを壊さないことを確認します)。今、私は彼らに元のビジネス要件を見せて、コードがそれを満たしているかどうかを確認する機能を追加しています。このエージェントには、何かをリリースパイプラインに進めるかどうかを決める手助けをしてもらいたいです。4: ウェブ検索(実験的):時々、既存のトークンでは検索が高コストすぎて、私たちが必要なのは最終結果だけで、彼らが検索した内容や見つけた10ページは必要ないことがあります…。

サブエージェントは同じシステムプロンプトを持っていると理解してたんだけど、どうやって彼らがCLAUDE.mdの指示に従わないってわかるの?サブエージェントが導入されて以来使ってるけど、コンテキストのサイズや汚染を管理するのにすごく役立ってるよ。

これまでの経験として、CCを異なる戦略で軌道に乗せようとした結果、結局同じような失敗に陥ることが多いと感じてる。エージェントやワークフローを定義しても、今はただGitHubのイシューとやり取りさせてるけど、品質はほとんど変わらないね。

それは私にはクレイジーに聞こえます。Claude Codeにはたくさんの制限があります。先週、Claude Codeに国際化対応のNext.jsプロジェクトをセットアップさせようとしたんですが、最新のNext.jsの国際化メソッド(Nextのミドルウェアを使う)を使わずに、サードパーティのライブラリをインストールしようとして、機能するボイラープレートサイトを作れませんでした。エージェントAIが役立つ特定のケースもありますが、今の状態でエージェントが無制限に動く姿は想像できません。

まずは計画モードに入れる筋肉記憶を身につけるように訓練してるんだ。そっから何をするか教える感じで。

俺はほぼいつも、(ライブラリ名)LLM.txtをコンテキストとして添付するか、(フレームワーク機能)のドキュメントページへの直接リンクを貼ってる。あんまりエージェント的じゃないけど、ずっと効果的だよ。

すごいことをやってるのを見たことがあるよ。一発で、独自のバックオフィスシステムの修正、DBスキーマの更新、新しいAPIモデルの定義、バックエンドとフロントエンドの変更を含む機能を追加したこともある。逆に、検索結果のカウントを追加するだけでつまずいてるのも見たことがある。短く言うと、試させるのは安上がりだよ。

Claudeは知識のカットオフのせいで、最新バージョンにはいつも少し遅れを取ってるんだ。それに、君が言ってるi18nライブラリも知ってるけど、それは多分正しい判断だったね。

よく、プロダクトマネージャーやバックエンド開発者などの役割をモデルにしたサブエージェントを作っている人を見かけます。私もこういうことを試してみたけど、エージェント特有の指示なしでCCを使った場合と比べると、結果はかなり悪かったです。もしかしたら、押し通してうまくいく組み合わせを見つける必要があったのかもしれませんが、この記事はあまり説得力がないですね。著者は「うまくいく」と言っているだけで、具体例やサブエージェントありとなしで同じプロジェクトを比較していないです。もっと説得力のある提案があれば、こういうフローを構築するためにもっと時間をかける価値があると思えるんですが。

私も今までの経験はそんな感じです。基本的なプロンプトだけで、これらの複雑な追加機能よりもずっと進むことができる気がします。どこかで立ち止まって、Claudeを管理するのにやりすぎているのではないかと考えなきゃいけない時が来ると思います。

そのコツは、エージェントの発見をまとめる合成ステップだと思います。少なくとも、私はそこで一番成功しています。

そうだね、役割ごとにサブエージェントを作るんじゃなくて、トークンが多いタスクのためにコンテキストを管理するためのものを作るべきだよ。バックエンド開発者のサブエージェントはまあまあ仕事をするけど、スーパーバイザーエージェントは何が行われたかの有用なコンテキストが欠けてしまって、うまくいかなくなる。理想的なサブエージェントは、シンプルな質問を受けて、大量のトークンを使って答えを出し、最終的にシンプルな答えだけ返すことができるものだね。その間のトークンは不要だからね。ドキュメント検索はいい例だよ。「XライブラリにはY関数があるの?」って質問に対して、サブエージェントがウェブを検索して、ドキュメントを読んで、スーパーバイザーがすべてのコンテキストに悩まされることなくシンプルな答えを返せるんだ。

いや、これが俺の経験でもあるよ。やるべきだって言ってる人はたくさんいるけど、実際には自分でやってないことが多い。あるいは、失敗したりスケールしたりしたときにどう対処するかの具体例を全然見せてくれない。だって、何もないときは、エージェントが適当なことをやっても問題ないからね。イライラするよ。

いや、みんなそのアイデアが好きで「エージェント」に関する盛り上がりのせいで遊んでるだけだと思うけど、個人的には必要ないと思うよ。

今、プロジェクトでエージェントを動かしながらコメントしてるんだけど、これに似たことを達成しようとしてる感じがする。「みんな」それぞれのやり方で、速いペースで似たようなことをやってると思う(俺はClaudeのコードを使ってて、サブエージェントがあることすら知らなかった)。過去の経験からの直感だけど、今はgitがあって、git-flowもあるけど、チーム全体で簡単に学んで実装できる標準化されたアプローチが必要だと思う。もし誰かが「正しく」理解して、エンジニアが効率的に仕様やコードを期待に対してレビューできる信頼できる方法を見つけたら、プログラマーの意味が大きく変わる瞬間が来ると思う。今まで見たプロジェクトは、結局「フレームワーク」を作って、各自の内部ワークフローに合わせてるだけだよ。それは素晴らしいし、一人にはとても効果的だけど(俺にはそう)、それがチーム全体で共有できないと、スループットは限られたままだよ(同じツールを使ってるエンジニアチームと比べると)。それに、AIワークフローをフル活用するためにプロジェクトをリファクタリングするのは、ゼロから再構築するのと比べると非効率的かもしれない。コンテキストを持つドキュメントを開発と同時に作ることは、過去に戻ることができないからね。時間が経ってしまって、技術的負債として蓄積されてしまう可能性が高い。

それぞれの瞬間に何が起こっているのかをどうやって頭の中で迷わずに把握してるの?システムを信頼して、最終的な出力をレビューするだけ?単一のワークストリームだとコンテキストが混乱するけど、なんだかもっと安心感があるんだよね。

もう一つエージェントが欲しいな…

だんだんと、そして突然?不正確な推論や解決策への「修正」は、現在のインスタンスを解決するだけじゃなくて、将来使われるルールベースのシステムに繋がるんだよね。ループにいることが必要で、「ただ承認する」だけになったら、リラックスして振り返ることができるけど、最初は細かいタスクが必要だと思う。信頼性が高まると、タスクはもっと複雑になっていく。「並列化」することで、単一の(サブ)エージェントがアドホックな責任を持ちながら、別の「制度化された」コンテキストやルールに頼ることができる。例えば、アーキテクチャエージェントとコーダーエージェントが互いに話し合って、どちらが具体的なルールに基づいて決定を下しているのか、あるいは幻覚的な決定をしているのかに基づいて、決定の対立を解決できる。友達がルールベースのシステムを構築しているのを見て、LLMがそのコンテキスト内でどれだけうまく機能するかに感心したよ。

このペルソナベースのエージェントが本当にそんなに違いを生むのか、ちょっと懐疑的なんだよね。話し方のスタイルで「違いがあるように見える」だけな気がする。実際はただのシステムプロンプト、もしくは「あなたはフロントエンドエンジニアで、ReactやNext.js、Tailwind CSSに精通している」というプロンプトが重なってるだけ。スタックの詳細やプロジェクトのレイアウト、重要な情報はすでにCLAUDE.mdに入ってるし。もっと色々やるなら、モデルがファイル読み取りツールを呼び出すんだろうけど、実際は演出が多いと思う。俺は親フォルダを作って、その中にfrontend/ backend/ infra/とかを子フォルダとして作ってる。親フォルダのCLAUDE.mdは「Postgresを使ったFastAPIバックエンド、Tailwindを使ったNext.jsフロントエンド」みたいなスタックの全体像を提供してる。親フォルダのCLAUDE.mdは子フォルダのCLAUDE.mdへのリンクも持ってて、もっと詳細な情報が載ってる。そしたら親フォルダでclaudeを立ち上げて、計画モードを設定して、デザインを行ったり来たりして、最後にマークダウンに出力してRFCにして、その後仕事に取り掛かる感じ。そうすると、他のサービスの文脈を持ったまま変更を加えてくれるから、すごくうまくいくよ。

サブエージェントはいらないよ。これ、ClaudeCodeのサブにもシェアしたんだ。https://www.reddit.com/r/ClaudeCode/s/barbpBxG78 サブエージェントはコーディングには全然向いてない。

同意だね、役割は何か儀式的な感じがする。

ペルソナには懐疑的だけど、異なるタイプの作業のためにコンテキストや指示を整理するのには使ってる。トップレベルの.agentsディレクトリを使って、コマンドや役割、ルールをサブディレクトリに分けてる。CLAUDE.mdはちょっとスリムに保ってて、./docs/の個別ファイルへのポインタを持ってるし、.claude/commandsは.agents/commandsへのシンボリックリンクになってる。Claudeを起動した後、/commandsを使って役割とコンテキストを読み込むんだけど、必要なドキュメントだけを引っ張ってくるから、バックエンド機能を追加する時にUIデザインやテストアーキテクチャのドキュメントを読み込むことは避けられる。こんなことはやりたくないんだけど、エージェントを軌道に乗せて、コンテキストの劣化を最小限に抑えるのに役立ってる。

俺も部分的に懐疑的なのは、どのLLMでも生成される長いエッセイが好きじゃないから。CLAUDE.md/AGENTS.md/README.mdが5ページ以上あるのは、どれも同じくらいダメだと思う。何かが自分にとって有用な情報を得るには長すぎるなら、そのLLMも同じように振る舞うべきだと思ってる。たとえそれが真実じゃなくても、短い文で説明できることを2段落も使って説明するのは無駄だよね。俺のCLAUDE.mdやAGENTS.mdは、だいたい高レベルの情報を持った箇条書きのリストになってる。エージェントがもっと指示を必要とするなら、もっとリマインダーを追加するようにしてる。事前に計画なしにあまりにも広いタスクを与えないようにしてるけど、そうしないと脱線しちゃうから。実は、claudeにADRを生成させることはあまり試したことがないんだけど、あなたのRFC/アイデアみたいにやってみようと思ってる。 [1]: https://adr.github.io/

フロントエンド/バックエンドを意識したClaude Codeを自分の好きな形で動かすのに苦労してるんだ。つまり、親のエージェントと計画を立てて、何らかの形式でファイルを出力して、それをフロントエンドとバックエンドのClaudeにそれぞれ渡すってこと?でもその「サブクラウド」たちは他のリポジトリのコンテキストを持ってないってこと?

この概念は小説『Accelerando』に出てくるから、またAIファンがLARPしてるだけだと思うよ、今のLLMの盛り上がりと同じようにね。

最近、Claude Codeを使ってサブエージェントで面白い話があったんだ。大きめのR分析をしてたんだけど、Rではみんなライブラリを丸ごと読み込むことが多くて、namespaceの衝突が起きるんだよね。だから、パッケージの関数を呼び出すときは、パッケージのnamespaceを使う方がいい。つまり、a::function_a()やb::function_b()って書く方が、両方のライブラリを読み込んで、function_a()やfunction_b()がaやbから来てるって無条件に信じるよりも良いってこと。Claude Codeに1000行以上のRスクリプトを渡して、すべての関数呼び出しをモデルのnamespace関数呼び出しに置き換えてもらうように頼んだんだ。そしたら、1つのサブエージェントが関数呼び出しを探して、40以上のパッケージを特定して、さらに40以上のサブエージェントを立ち上げて、各パッケージ呼び出しを処理し始めた。コスト的にも(スピード的にも!)大混乱だったよ、だって各サブエージェントがスクリプトを再読み込みしてたからね。普通のClaudeにRスクリプトをコピー&ペーストして同じことをやってもらう方が、ずっと早くて安かったけど、ちょっと判断が難しかった。教訓としては、サブエージェントはしばしばコストがかかりすぎるってことだね。

サブエージェントやCCタスクツールの一番の問題は、ブラックボックスになってて中で何が起きてるかわからないし、介入もできないことなんだ。だから、Tmuxを使って、CCが別のCLIエージェント(CCでも今流行りのCodex-CLIでも、もちろん他の優秀なCLIエージェントでも)にメッセージを送る方が良いことが多いと感じてる。これをスムーズにするために、CCが使えるTmux-cliコマンドを作ったよ: https://github.com/pchalasani/claude-code-tools/tree/main?ta... もし最初のCLIエージェントがレビューやアプローチの提案だけを必要とするなら、最初のエージェントが別のCLIエージェントにその分析をマークダウンファイルにダンプさせるのが役立つと思う。

他にもHNにBMADやccpm、conductorなどを提案してる投稿があったね。試してみようかとも思ったけど、ドキュメントを全部読むのが疲れるくらい、かなり詳細だったんだ。製品要件、エピック、ユーザーストーリー/ジャーニー、タスク、分析、アーキテクチャ、プロジェクト計画などがあって、サブエージェントが作業するためのコンテキストを1つのGitHubのイシュー/ドキュメントにまとめるのがアイデアだったんだ。GitHubのイシューのコンテキストに頼って、開発/QAサブエージェントが実際のシナリオでどうなるかはまだ見てないけど、ここにいる他の多くの人と同じように、サブエージェントはコンテキストが不足すると思ってる。Claude Codeエージェントはコンテキストが豊富だけど、claudeのサブエージェントはコンテキストが貧弱なんだよね。

この手の投稿は現実のアプリケーションとは関係ないよね。エージェントやマークダウンファイルに対しては敬意を表するけど、Claude Codeは他のLLMと同じように、特定のナラティブに固定されちゃって、指示が何であれ、その間違った選択を何度も繰り返しながら「ごめんなさい」って謝るんだ。実装をじっくり見直す以上のことは失敗する運命にあるよ。最近少し良くなったのは、Gemini CLIとClaude Codeが交互に設計、レビュー、実装、テストを行うようにしたことかな。