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

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

2025年9月9日原文(zachwills.net)

概要

  • 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を使った場合と比べると、結果はかなり悪かったです。もしかしたら、押し通してうまくいく組み合わせを見つける必要があったのかもしれませんが、この記事はあまり説得力がないですね。著者は「うまくいく」と言っているだけで、具体例やサブエージェントありとなしで同じプロジェクトを比較していないです。もっと説得力のある提案があれば、こういうフローを構築するためにもっと時間をかける価値があると思えるんですが。

Hacker Newsで議論の続きを見る