Subagent on KnightLiブログ

Codex vs Claude Code：2 つの Subagent 設計をどう選ぶか

Fri, 08 May 2026 14:14:01 +0800

AI コーディングツールでは Subagent が重要になっています。これは流行りの機能ではなく、単一 Agent が実際の開発タスクを抱え込むと限界に当たりやすいからです。

1 つの Agent がコードを読み、ログを確認し、実装を変更し、テストを実行し、エラーを分析し、結果をまとめると、main context はすぐ汚れます。検索結果、コマンド出力、テストログ、中間推論が混ざり、後の判断が不安定になります。探索、実装、検証、レビューを 1 本の main thread に押し込むため、並行処理もしづらくなります。

Subagent の本質は Agent の負荷を下げることです。main session はすべてを最後まで行うのではなく、目標を決め、タスクを割り当て、結果を受け取り、最終回答へ統合する coordinator になります。Subagent は探索、実装、検証、レビューなど局所的な仕事を処理し、圧縮した結論を返します。

つまり Subagent は「もう 1 人の自分」ではなく、絡み合った開発作業を明確な役割に分ける仕組みです。

共通する土台

成熟した Subagent system には通常、次の要素が必要です。

Context isolation。
Role specialization。
Project/user level configuration。
Tool and permission boundaries。

Context isolation は前提です。実際のリポジトリでは、検索結果、テストログ、コマンド出力など中間情報が大量に出ます。これをすべて main session に入れると main thread が乱れます。Subagent は局所的な過程を先に消化し、判断に必要な signal だけを返します。

Role specialization も重要です。複数 Agent とは同じモデルを複数起動することではありません。探索役は検索、読解、要約に強くあるべきです。実装役はコード変更に集中します。検証役はチェックを実行し、リスクを見つけ、結果を明確に報告します。

Tool と permission の境界は安全性を決めます。Subagent が main session の全能力を自動継承すべきではありません。読み取り専用の explorer に書き込み権限は不要です。verifier が実装を変更する必要もありません。

Codex と Claude Code はこの問題意識を共有しつつ、異なる道を取っています。

Codex：明示的な委任

Codex の Subagent 設計は抑制的です。

現在の main session を中心に、制御された軽量な分業機構を提供します。いつ委任するか、誰に渡すか、いつ結果を受け取るかは明示的な判断です。制御フローは現在のタスクに残ります。

特徴は次の通りです。

main session が明示的に subtask を委任する。
role set は小さく保たれる。
main session は誰が何をしているか把握できる。
結果は main line に戻ってから判断される。
協作境界が透明。

これは手動 orchestration、予測可能性、実行の確定性を重視するチームに向いています。explorer に call chain を調べさせ、worker に限定的な変更を任せ、main session が結果を統合して次のテストを判断できます。

一方で、分割、委任、回収、統合の負荷は main session に残ります。軽量な協作には心地よいですが、長期的で複雑な workflow では重くなることがあります。

Claude Code：Agent を workstations として扱う

Claude Code はより platform 的です。

Agent を、説明可能、選択可能、設定可能、記憶可能、隔離可能、background 実行可能な正式な object として扱います。Subagent は会話中の一時的な helper ではなく、開発システムの workstation に近い存在です。

Agent list、use case、description、tool boundary をモデルに渡し、モデル自身がその turn に適した role を選ぶことができます。これにより委任はより自動化されます。

この方向性を支える要素はいくつかあります。

第一に role system。explorer、planner、general-purpose、verifier などの role が用途説明、tool restriction、default model、runtime condition を持てます。read-only explorer は編集できず、planner は設計に集中し、verifier は検証に集中します。

第二に inheritance と override。Subagent は完全に自由ではありません。main session の大きな境界を継承しつつ、許可された範囲で局所的に振る舞いを調整します。

第三に memory。memory は単に少し覚えることではなく、scope を持ちます。user memory は長期的な好み、project memory はリポジトリ背景、local memory は現在環境の状態です。

第四に background work と worktree isolation。検証 task は background で走り続けることができ、main thread は待ち続けなくて済みます。強い隔離が必要なときは別 worktree で作業できます。

第五に plugin ecosystem。Agent を first-class object と見るなら、配布、インストール、優先順位、override、安全境界を考える必要があります。plugin agent は入れられますが、permission mode、hooks、MCP servers など高リスク領域は制限されるべきです。

これにより Claude Code は単発 session の協作ツールではなく、Agent runtime に近く見えます。

違い

Codex は制御された分業ツールに近いです。

明示的な委任。
軽量な role set。
明確な制御フロー。
現在 session 中心の subtask。
人が orchestration する確定的な作業に向く。

Claude Code は engineering workstation system に近いです。

Agent が正式に model 化される。
role が体系化される。
memory、background、isolation、plugin が runtime に含まれる。
モデルが role 選択に関与できる。
長期 project や platform 的 workflow に向く。

問題は機能数ではありません。Subagent を「自分が明示的に呼ぶ helper」と見るか、「system に長期存在する workstation」と見るかです。

選び方

明示的な制御、軽量な分業、現在 session 内の安全な並行処理を重視するなら Codex 的な設計が合います。コードレビュー、小さな変更、明確な実装 task、人がリズムを握りたい workflow に向きます。

体系化された role、長期 memory、background execution、worktree isolation、plugin extension、より完全な Agent runtime を求めるなら Claude Code 的な設計が合います。

判断する質問は 2 つです。

モデル自身が誰に仕事を任せるか選ぶことを受け入れられるか。
より完全な Agent runtime が必要か。

1 つ目が不安なら明示的委任が向いています。2 つ目が yes なら、platform 的な workstation system が向いています。

使い方の注意

Subagent を「モデルを増やせば強くなる」と考えない方がよいです。

各 role の task boundary を明確にする。
role ごとの tool を制限する。
raw log ではなく結論を返させる。
最終判断は main session に残す。
background task と worktree isolation を可視化する。
plugin agent に安全境界を置く。

Subagent の価値は数ではなく分業品質です。role が明確で context がきれいなほど、main thread の判断は安定します。

まとめ

Codex と Claude Code は同じ問題に向き合っています。単一 Agent は実際の開発作業をすべて背負いにくい。両者とも context isolation、role specialization、permission boundary、local summarization を重視します。

違いは設計の方向です。Codex は抑制的で、明示的委任と main session の制御を重視します。Claude Code は体系的で、Agent を設定、記憶、隔離、background 実行、plugin ecosystem に対応した正式な workstation として扱います。

選択はブランド勝負ではありません。必要なのが制御された協作ツールなのか、完全な Agent runtime なのかで決まります。

Claude Code のマルチエージェント協調: Subagents と Agent Teams はどう使い分けるか

Wed, 22 Apr 2026 21:35:52 +0800

Claude Code でマルチエージェント協調を考えるとき、最も混同しやすいのが Subagents と Agent Teams です。どちらも「複数の Agent を動かして一緒に作業する」ように見えますが、実際には想定している使い方が異なります。簡単に言えば、前者は独立したタスクを切り出して処理するのに向いており、後者は複数の Agent が同じテーマについて継続的に協力し、相互に検証しながら進めるのに向いています。

もし Skill を使ったことがあるなら、まずは次のように理解すると分かりやすいです。

Skill は手順やルールを定義する
Subagent や Agent teammate は実際の作業を行う

つまり重要なのは、どちらが「上位」かではなく、どの種類の協調課題を解きたいのかです。

Subagents: サイドタスクを切り出す

Subagents は、現在のセッションから一時的に送り出す分身に近い存在です。各分身は独自のコンテキストウィンドウを持ち、作業後は結果の要約だけを返します。そのため、メインの会話は大量の中間ログや出力で埋まりにくくなります。

この仕組みには、実務上かなり分かりやすい利点があります。

メインスレッドがきれいなままで、テストログや検索結果、長い出力で汚れにくい
相互依存のない調査や実行タスクを並列化できる
「結果だけ返してくれればよい」タイプの仕事に向いている

元記事では、Claude Code には次の 3 種類の組み込み Subagent があると説明されています。

Explore: 読み取り専用で、コードベースの高速検索に向く
Plan: 読み取り専用で、plan mode 中のバックグラウンド情報収集に向く
General-purpose: 読み書き可能で、探索と編集を組み合わせる仕事に向く

カスタム Subagent

組み込みのものだけでは足りない場合は、自分で Subagent を定義できます。やり方はシンプルで、Markdown ファイルを用意するだけです。

.claude/agents/: 現在のプロジェクトでのみ有効
~/.claude/agents/: すべてのプロジェクトで有効

ファイル形式は次のようになります。

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:

1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:

- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:

- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

ここで特に重要なのは description です。Claude はこの説明を見て、いつこの Subagent を呼ぶべきか判断します。説明が正確であるほど、呼び出しの精度も上がりやすくなります。

ほかにも知っておくと便利な設定項目があります。

tools: 使用できるツールを制限する
model: sonnet、opus、haiku、inherit から選ぶ
permissionMode: 編集権限や権限プロンプトの挙動を制御する
memory: Subagent に対話をまたぐ記憶ディレクトリを与える

一時的にだけ使いたい場合は、CLI 経由で定義することもできます。

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Subagents が向いている場面

Subagents が特に向いているのは、たとえば次のような仕事です。

テストを実行し、数千行のログではなく失敗要約だけをメイン会話に返す
相互依存しない複数モジュールの調査を並列に進める
「問題を見つける」と「修正する」を単純なパイプラインに分ける

たとえば次のような指示です。

`1`	`Research the authentication, database, and API modules in parallel using separate subagents`

`1`	`Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them`

一方で、タスクが何度も往復しながら調整を要する場合、複数段階で大量の文脈を共有する場合、あるいは変更が一つ二つのファイルに集中している場合は、Subagent を立てるよりメイン会話で直接処理したほうが楽なことが多いです。

Agent Teams: 複数の独立セッションで協調する

Agent Teams は別のレイヤーの機能です。1 つのセッション内で分身を出すのではなく、完全に独立した複数の Claude Code インスタンスを起動し、共有タスクリストを中心に協調させます。しかも、メンバー同士が直接メッセージを送り合うこともできます。

そのため、単なるサイドタスク処理というより、本当に小さなチームを作る感覚に近いです。

元記事では、これはまだ実験機能であり、先に有効化が必要だと説明されています。

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

これを settings.json に追加すると、Claude に対して目的に応じた team を組ませることができます。たとえば次のような形です。

1
2
3

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

Agent Teams の構成

Agent Team は主に次の 3 つで構成されます。

Team lead: あなたが使っているメインセッション。編成、割り振り、要約を担当する
Teammates: 複数の独立した Claude Code インスタンス
Task list と Mailbox: 共有タスクリストとメッセージ経路

Subagents との最大の違いは、teammates 同士が直接やり取りできることです。毎回 lead を経由する必要はありません。タスク状態は通常 pending、in progress、completed の間を移り、1 つ終えた teammate は次のタスクを引き取ることもできます。

Agent Teams が向いている場面

複数視点からの検討、結論への異議申し立て、仮説同士の競合、あるいはモジュール単位の並列開発が必要なときは、Agent Teams のほうが適しています。

記事では次のような典型例が挙げられています。

同じ PR を複数 reviewer が並列でレビューし、それぞれ異なる観点を見る
同じ bug に対して複数の Agent が異なる仮説を立て、互いに反証する
フロントエンド、バックエンド、テストが別々の領域を並列で進める

たとえば並列コードレビューでは、次のように指示できます。

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

また、討論型のデバッグでは次のような使い方ができます。

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

この種の仕事に共通しているのは、単に 1 つの答えが欲しいのではなく、複数の Agent が判断を持ち寄り、前提を揺さぶり合いながら、より確かな結論に収束していくことです。

どう使い分けるか

手早く判断したいなら、次のように覚えると分かりやすいです。

結果だけ持ち帰ればよいなら Subagents
議論や相互検証が必要なら Agent Teams

もう少し整理すると、主な違いは次の通りです。

通信方法: Subagents は主にメイン会話へ結果を返すが、Agent Teams はメンバー同士で直接やり取りできる
調整方法: Subagents はメイン会話側のオーケストレーションに依存しやすいが、Agent Teams は共有タスクリストをもとに各メンバーが自律的に動ける
Token コスト: Subagents のほうが軽く、Agent Teams は各 teammate が独立インスタンスのため高くなりやすい
向いている仕事: Subagents は独立性が高く結果志向の仕事向き、Agent Teams は議論や相互検証が重要な仕事向き

実運用で気をつけたいこと

Agent Teams は強力ですが、だからといってすべてのタスクで team を組むべきというわけではありません。記事では特に次のような現実的な注意点が挙げられています。

token 消費が明らかに大きい
複数 teammate が同じファイルを同時に編集すると、上書き競合が起きやすい
teammate が多すぎると調整コストが増え、成果が伸びるとは限らない

そのため、比較的安全な進め方としては次のようになります。

まずは 3〜5 人程度の teammate から始める
モジュールやファイル単位で仕事を分け、編集衝突を避ける
lead が早まって teammate の仕事に手を出し始めたら、先に待つよう明示する

また、現時点の実験版には次のような制約もあります。

/resume と /rewind で in-process teammates を復元できない
タスク状態が遅れて反映され、手動での更新が必要になることがある
1 人の lead が同時に扱える team は 1 つだけ
teammate がさらに子 team を作ることはできない

まとめ

この 2 つの機能は、互いの代替ではありません。解いている協調課題そのものが違います。

目的が「サイドタスクを並列化し、メインの文脈をきれいに保つこと」なら、まずは Subagents を使うのが自然です。目的が「複数の Agent に小さなチームのように協力させ、議論し、相互検証させること」なら、Agent Teams が向いています。

実際のタスクで一度試してみると、違いはかなり早く体感できます。片方は文脈の分離と結果回収に強く、もう片方は多視点での協調と継続的なやり取りに強い、という違いです。