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

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 の判断は安定します。

Claude Code subagent が向くプロジェクトと実装方法

向く場面 1：大規模コードベースの把握

未知の大きなリポジトリを引き継ぐとき、最初の問題は「どこから見るか」です。

subagent で次のように分けられます。

api-reader：ルート、コントローラ、認証。
db-reader：schema、migration、ORM model。
frontend-reader：ページ構造、状態管理、コンポーネント入口。
test-reader：テストフレームワーク、カバレッジ、実行コマンド。

各 subagent は 5 から 10 件の結論だけを返します。主会話はリポジトリ全体を抱え込まず、構造化された地図を持てます。

monorepo、古い業務システム、前後端混在リポジトリ、ビルドやデプロイスクリプトが散らばったプロジェクト、技術的負債の評価に向いています。

Codex と Claude Code の引き継ぎを設計するなら、この「読む・構造を掴む」作業を Claude Code subagent 側に置き、結果を Codex に渡して長い変更を進める形も使えます。関連: Codex と Claude Code のタスク引き継ぎガイド：実装、レビュー、長時間タスク復旧まで。

向く場面 2：コードレビューを役割で分ける

レビューは観点ごとに分けやすいため、subagent と相性がよいです。

bug-reviewer：ロジックミス、null、境界条件、回帰。
security-reviewer：権限、入力検証、秘密情報、注入、越権。
performance-reviewer：ループ、クエリ、キャッシュ、描画、並行性。
test-reviewer：本当にリスクを覆うテストがあるか。

ただし、レビュー型 subagent は読み取り専用をデフォルトにするべきです。

安全な流れは次の通りです。

主会話が diff を集める。
複数の読み取り専用 subagent がレビューする。
主会話が結論を統合する。
明確な実装担当が小さく修正する。

Claude Code と Codex のレビュー閉ループは、こちらも参考になります: Claude Code と Codex のコードレビュー手順：ローカル変更から PR までの閉ループ。

向く場面 3：テスト失敗とログのノイズ

自動テストの失敗出力は長くなりがちです。E2E、統合テスト、CI ログでは、有用なエラーが数百行の中に埋もれます。

test-runner subagent は次を担当できます。

指定テストコマンドを実行する;
失敗ケースを抜き出す;
失敗理由を要約する;
関連しそうなファイルを示す;
直接コードを修正しない。

subagent	推奨ツール	タスク
`test-runner`	`Bash, Read, Grep`	テスト実行と失敗説明
`log-analyzer`	`Read, Grep, Glob`	ログとスタックトレース分析
`coverage-reviewer`	`Read, Grep, Glob`	不足テストと高リスク分岐の確認

Claude Code hooks でテストを自動実行している場合、hooks がトリガー、subagent が失敗を説明する役割にできます: 。

向く場面 4：大規模リファクタ前の影響分析

大きなリファクタは、いきなり編集しないほうが安全です。subagent は読み取り専用の偵察に向いています。

たとえば認証モジュール置換、DB アクセス層更新、フロントエンド状態管理の変更では、次を調べます。

古い interface に依存するファイルはどれか;
どのテストが対象ロジックを覆っているか;
どの呼び出し経路が壊れやすいか;
ドキュメント、スクリプト、設定も更新が必要か;
先にテストを追加すべき場所はどこか。

重要なのは、subagent は影響範囲を出し、patch を急がないことです。

主会話がその結果を見て、一括変更、段階的変更、先にテスト追加のどれを選ぶか決めます。これは長時間タスクの復旧にも役立ちます: 。

向かない場面

subagent には追加コンテキスト、待ち時間、調整コストがあります。

通常は次の場面では使いません。

1. 直接直せる小さな問題

typo、import、CSS class、null チェック、設定値更新などは主会話で直すほうが速いです。

2. 境界が曖昧な要件

「このプロジェクトを最適化して」「このページを良くして」のような依頼は、先に目標と制約を明確にします。

3. 頻繁な相談が必要なタスク

subagent は独立作業向きで、設計を細かく往復相談する仕事には向きません。

4. 複数 Agent が同じファイルを編集する

先に読み取り専用レビューを行い、修正は一つの実行者に集約します。

5. 高リスクな外部操作

本番環境、実アカウント、有料 API、削除、権限変更、メール送信、メッセージ送信は、厳しいツール制限と確認なしに背景 subagent へ任せるべきではありません。

プロジェクトレベル subagent の設計

Claude Code では subagent を Markdown として書けます。プロジェクトレベルでは通常ここに置きます。

1

.claude/agents/

グローバルに再利用するものはここです。

1

~/.claude/agents/

プロジェクト用には、テストコマンド、ディレクトリ構造、レビュー観点、触ってはいけないファイル、出力形式を書きます。

最小の読み取り専用レビュー subagent 例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


---
name: code-reviewer
description: Use when the task needs a read-only review of code changes for bugs, regressions, security risks, and missing tests.
tools: Read, Grep, Glob
---

# Code Reviewer

Only perform read-only review. Do not modify files.

Focus on:

- logic errors and edge cases
- regression risk
- security and permission issues
- missing tests
- inconsistency with project style

Output:

1. List high-risk issues first.
2. Include file paths and reasons.
3. If no issue is found, say so clearly.
4. Do not output long rewritten code.

特に重要なのは description です。Claude Code はこれを見て委任タイミングを判断します。

よく使う subagent 構成

最初から十数個作る必要はありません。まずは 3 から 5 個で十分です。

名前	ツール	役割
`code-reviewer`	`Read, Grep, Glob`	バグ、回帰、テスト不足の読み取り専用レビュー
`test-runner`	`Bash, Read, Grep`	テスト実行と失敗説明
`docs-researcher`	`Read, Grep, Glob`	ドキュメント、移行メモ、規約整理
`security-reviewer`	`Read, Grep, Glob`	権限、入力、秘密情報、注入リスク確認
`refactor-planner`	`Read, Grep, Glob`	大変更前の影響分析と段階計画

汎用的な助言ばかり返す subagent は、役割が広すぎます。範囲を狭めるか、プロジェクトルールを追加します。

呼び出し方

明示的に呼び出せます。

1

Use the code-reviewer subagent to review the current diff. Do not modify files.

@code-reviewer のように名前を指定したり、コマンドで起動することもできます。

1

claude --agent code-reviewer

重要な作業では自動委任だけに頼らず、「read-only」「do not modify files」「return conclusions only」と明示するのが安定します。

判断式

迷ったら次の 5 つを確認します。

モジュール、ディレクトリ、役割、観点で分割できるか。
サブタスク同士が十分独立しているか。
各サブタスクが明確な結論を返せるか。
異なるツール権限が必要か。
コンテキスト分離の利益が token と待ち時間のコストを上回るか。

3 つ以上が yes なら試す価値があります。1 つだけなら、分けないほうがよいでしょう。

落とし穴チェックリスト

helper、assistant、worker のような曖昧な名前を避ける。
description には起動場面を書く。
レビュー型 subagent は原則読み取り専用。
編集型 subagent は一度に小さな範囲だけ担当する。
大規模リファクタは先に影響分析をする。
テスト subagent はログ全文ではなく失敗要約を返す。
複数 subagent の出力は主会話が統合する。
高リスク操作はツールと範囲を制限する。
プロジェクトルールは .claude/agents/、個人習慣は ~/.claude/agents/ に置く。
低頻度、重複、品質の低い subagent は定期的に削除する。

参考資料

まとめ

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

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

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