メインコンテンツへスキップ
見出し画像

Claude Code Agent Teamsで並列開発する実務メモ。Subagentsとの差、Cursor運用、実測まで

    はじめに

    Claude CodeのAgent Teamsは、2026年2月に出てきた実験的な並列開発機能です。
    ざっくり言うと、1つのClaude Codeセッションから複数のチームメンバーを立ち上げ、調査・実装・テスト・レビューを同時に走らせる仕組みです。
    2026年5月時点では、まだ「何でも速くなる魔法」ではありません。
    効くのは、ファイル責務を分けられる作業、仮説を並べて試せる作業、レビュー観点を分離できる作業です。
    逆に、同じファイルを全員で触る改修は、かなり高確率で人間のマージ作業が増えます。
    この記事では、Subagentsとの違い、設定、Cursor内での使い方、そして単独実行と並列実行の測り方まで、開発現場で使う前提でまとめます。
    ポイントは「AIを増やす」ではなく「変更単位を分ける」です。

    📌 この記事を読むとわかること

    • Claude Code Agent TeamsとSubagentsの実務上の違い

    • 並列化しやすい作業、失敗しやすい作業の見分け方

    • settings.jsonでの有効化、起動プロンプト、Cursor内での使い方

    • 単独実行と並列実行を測るためのログ設計と比較表

    Agent Teamsは「複数セッションを束ねる」機能

    Agent Teamsは、Claude Code v2.1.32以降で使える実験的機能です。2026年5月時点では、環境変数 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` を有効にして使います。

    通常のClaude Codeは、1つの会話の中で調査、編集、テスト、修正を順番に進めます。Agent Teamsでは、リーダー役のClaude Codeが複数のメンバーを作り、それぞれに役割を割り当てます。

    たとえば、こんな分け方です。

    • architect: 変更方針と影響範囲を確認

    • implementer-api: API層を修正

    • implementer-ui: UI層を修正

    • tester: テスト追加と失敗原因の切り分け

    • reviewer: 差分レビューとリスク確認

    重要なのは、Agent Teamsではメンバー同士が直接メッセージをやり取りできる点です。Subagentsは基本的に、親セッションから依頼され、結果を返す「専門タスクの呼び出し」に近いです。一方、Agent Teamsは、複数のClaude Codeセッションが同じ作業空間を見ながら、共有タスクリストやメッセージで協調する設計です。

    Subagentsとの違いは「自律性」と「調整コスト」

    画像

    SubagentsとAgent Teamsは似ていますが、使いどころはかなり違います。

    画像

    私の使い分けはシンプルです。

    「答えが1つに収束する作業」はSubagentsで十分です。たとえば、API仕様の確認、ログの読み取り、テスト失敗原因の調査など。

    「同時に別々の成果物を作れる作業」はAgent Teamsが向きます。たとえば、バックエンド実装、フロントエンド接続、テスト、移行ドキュメントを別々に進めるようなケースです。

    Agent Teamsを使うときは、最初に「誰がどのファイルを触るか」まで切っておくのが大事です。役割だけ決めても、編集範囲が曖昧だとすぐ衝突します。

    設定と最初の起動方法

    有効化は、シェルの環境変数でもできますが、プロジェクトや個人設定として残すなら `settings.json` に書くのが扱いやすいです。

    {
      "env": {
        "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
      }
    }

    起動後は、いきなり「いい感じにチームで実装して」と投げないほうがいいです。最初のプロンプトで、役割、編集範囲、完了条件、禁止事項を渡します。※日本語でもいいですが、英語のほうが理解してもらいやすいです。

    Create an agent team for this task.
    
    Goal:
    Implement CSV export for the admin users table.
    
    Team:
    - lead: coordinate tasks and merge final plan
    - api-member: only inspect and edit server/routes/admin-users.*
    - ui-member: only inspect and edit src/features/admin-users/*
    - test-member: add or update tests only
    - reviewer: review diffs, security risks, and edge cases
    
    Rules:
    - Do not edit package manager files unless the lead asks.
    - Do not add dependencies.
    - Each member must report changed files before editing.
    - If two members need the same file, stop and ask the lead to assign ownership.
    - Final output must include commands run, files changed, and remaining risks.

    この粒度で渡すと、Agent Teamsは「複数人で同じ画面を囲む」感じではなく、「小さなPRを同時に作る」感じに近づきます。

    `CLAUDE.md` には、毎回守ってほしい運用ルールを書いておくと安定します。特に、依存追加、秘密情報、同一ファイル編集、テスト実行の扱いは固定ルール化したほうがいいです。

    # Agent Team Rules
    
    - Before editing, state the intended file paths.
    - Do not modify `.env`, secrets, credentials, or CI tokens.
    - Do not add dependencies without explicit approval.
    - Prefer small commits or small patch sets by responsibility.
    - If a file is already being edited by another member, stop and coordinate.
    - Run the narrowest relevant test first, then broader tests if needed.
    - Final report must include: changed files, tests run, risks, and rollback notes.

    Cursor内では「ターミナル運用」と割り切る

    2026年5月時点で、Cursor内のAgent Teamsは「Cursorの専用UI機能」として考えるより、Cursorの統合ターミナルでClaude Codeを動かす運用として捉えるほうが現実的です。

    おすすめは、Cursorで次の3面を並べる形です。

    画像

    Cursorのターミナルから起動するなら、プロジェクトルートでいつも通りClaude Codeを開きます。

    cd your-project
    claude

    そのうえで、リーダーセッションにAgent Teamsの作成を依頼します。分割ペイン表示を使う場合でも、私は最終的な判断はCursor側のGit差分で見ます。理由は単純で、AI同士の会話ログより、最終的にリポジトリへ入った差分のほうが信頼できるからです。

    実務では、次の順番が扱いやすいです。

    1. Cursorで対象ファイルと既存設計をざっと確認

    2. Claude CodeにAgent Teamsを作らせる

    3. 各メンバーの編集範囲を明示

    4. CursorのSource Controlで差分を確認

    5. テストを人間が再実行

    6. 必要ならレビュー担当だけ再起動して差分を見せる

    Dispatchを併用する場合も、同じ考え方です。遠隔で投げるタスクほど、編集範囲と完了条件を狭く書いたほうが失敗しにくいです。

    並列化しやすい作業、しにくい作業

    Agent Teamsに向いているのは、責務の境界がはっきりした作業です。

    画像

    コツは「レイヤーで分ける」か「仮説で分ける」ことです。

    レイヤーで分けるなら、API、UI、テスト、ドキュメント。仮説で分けるなら、原因A、原因B、原因Cを別メンバーに調査させます。

    逆に、同じコンポーネントを3人で改善するような依頼は避けたほうがいいです。見た目は並列ですが、最後に人間が競合解決係になります。

    単独実行と並列実行の差を測る

    Agent Teamsは「速く感じる」だけでは導入判断ができません。最低限、時間、トークン、テスト結果、手戻りを記録します。

    私が小さな管理画面改修で測るときは、次のようなログを残します。数値はプロジェクト構造、モデル設定、タスク粒度でかなり変わるので、自分のリポジトリで測る前提です。

    # Agent Teams Measurement Log
    
    Task:
    - Add CSV export to admin users table
    
    Conditions:
    - Same repository state
    - Same acceptance criteria
    - No dependency additions
    - Human intervention logged separately
    
    Run A: single Claude Code session
    - Start:
    - End:
    - Files changed:
    - Tests passed:
    - Manual fixes after AI:
    - Notes:
    
    Run B: Agent Teams
    - Team size:
    - Start:
    - End:
    - Files changed:
    - Tests passed:
    - Manual fixes after AI:
    - Coordination issues:
    - Notes:

    比較するときは、完了時間だけを見ないほうがいいです。並列実行は、実装が早く終わってもレビューと統合に時間が乗ります。

    画像

    私の判断基準はこうです。

    単独実行より早くても、統合後の手修正が増えるなら採用しません。逆に、時間短縮が小さくても、レビュー観点が増えてバグを拾えるなら採用することがあります。

    特にセキュリティ、権限、データ削除、課金まわりは、implementerとreviewerを分ける価値があります。速さより、見落としを減らす目的です。

    衝突させないマージワークフロー

    画像

    Agent Teamsで一番差が出るのは、実は起動方法ではなくマージ設計です。

    おすすめは、最初に「編集権」を宣言させることです。人間のチーム開発でいう、簡易的なファイルロックです。

    Before editing, each member must post:
    
    - Role:
    - Intended change:
    - Files to edit:
    - Files to inspect only:
    - Test command:
    - Blocking dependency:
    
    The lead approves or reassigns file ownership before edits begin.

    さらに、最終統合ではリーダーにいきなり全部まとめさせず、次の順で確認します。

    1. 各メンバーが変更ファイルを報告

    2. reviewerが重複実装と危険な差分を見る

    3. 人間がCursorで差分確認

    4. narrow testを実行

    5. full testまたはCI相当を実行

    6. PR本文に「AI担当範囲」と「人間確認範囲」を残す

    PR本文のテンプレートも用意しておくと便利です。

    ## Agent Team Summary
    
    Team members:
    - lead:
    - api:
    - ui:
    - test:
    - reviewer:
    
    Changed files:
    -
    
    Tests run:
    -
    
    Human verification:
    -
    
    Known risks:
    -
    
    Rollback plan:
    -

    これをやると、Agent Teamsの出力が「会話の成果」ではなく「レビュー可能な作業単位」になります。ここが実務投入の分かれ目です。

    まずは3人チームから始める

    Agent Teamsは、増やせば増やすほど速くなる機能ではありません。メンバーが増えるほど、トークン消費、調整、重複、マージ確認が増えます。実務では3〜5人程度が扱いやすい、という報告が多いのも納得です。

    最初に試すなら、私はこの3人構成をすすめます。

    • lead: 作業分解と最終統合

    • implementer: 実装修正

    • reviewer/tester: テストとレビュー

    これで効果が出るなら、次にAPI担当とUI担当を分けます。最初から大人数にすると、何が効いたのか分からなくなります。

    2026年5月時点のAgent Teamsは、まだ実験的な香りが残る機能です。ただ、責務分割、編集権、ログ、テスト、PRテンプレートまでセットで運用すると、かなり実用に近づきます。

    「AIを何人にするか」ではなく、「人間がレビューできる単位に分けられているか」。
    ここを外さなければ、Agent Teamsはちゃんと開発速度と品質の両方に効いてきます。

     
     

    Nushi

     
     
    エンジニア9年目。現在はフリーランス。案件でCodexやClaudeCodeを使用。現場や個人開発で得た知識の備忘録Noteです。※たまに関係ないことも記事にしますがお許しください。※アイコンは我が家の主 以下成果物 https://github.com/foxlabo

    あなたへのおすすめ