codex-team

Codex チーム

リードが指揮し、Codex エージェントが実行します。各エージェントには、焦点を絞ったタスクを1つ割り当てます。チームリードはエージェントを起動する前にファイルの競合を防ぎます。つまり、オーケストレーターがロックマネージャーです。

Claude ランタイムの機能互換性（エージェント／フック／worktree／設定）については、このスキルが /swarm にフォールバックする場合、skills/shared/references/claude-code-latest-features.md にある共有コントラクトを使用してください。これはローカルの references/claude-code-latest-features.md にミラーされています。

使用するタイミング

• 2つ以上のタスク（バグ修正、実装、リファクタリング）がある
• タスクの範囲が明確で、指示もはっきりしている
• 予測可能な分離環境で Codex に実行させたい
• Claude または Codex のランタイムを使用している可能性がある（スキルがバックエンドを自動選択します）

使用しない場合： タスクに緊密な共有状態の調整が必要な場合は、依存関係の多い段階的なオーケストレーションに /swarm を使用してください。

バックエンドの選択（必須）

次の順序でバックエンドを選択します。

1. spawn_agent が利用可能 -> Codex 実験的サブエージェント（推奨）
2. Codex CLI が利用可能 -> Bash 経由の Codex CLI（codex exec ...）
3. skill ツールが読み取り専用（OpenCode） -> OpenCode サブエージェント — task(subagent_type="general", prompt="<task prompt>")
4. 上記のいずれも利用できない -> /swarm にフォールバック

実行前の確認（CLI バックエンドのみ）

# REQUIRED before spawning with Codex CLI backend
if ! which codex > /dev/null 2>&1; then
  echo "Codex CLI not found. Install: npm i -g @openai/codex"
  # Fallback: use /swarm
fi

# Model availability test (uses the user's configured Codex default)
if ! codex exec --full-auto -C "$(pwd)" "echo ok" > /dev/null 2>&1; then
  echo "Default Codex model unavailable. Falling back to /swarm."
fi

標準コマンド

codex exec --full-auto -C "$(pwd)" -o <output-file> "<prompt>"

ユーザーのデフォルトの Codex モデルを使用します。特定のモデルを意図的に固定する場合に限り、-C の前に -m "<model>" を追加してください。

フラグの順序：--full-auto -> -C -> -o -> プロンプト（モデルを上書きする場合に限り、-C の前に -m を挿入します）。

有効なフラグ： --full-auto、-m、-C、-o、--json、--output-schema、--add-dir、-s

使用禁止： -q、--quiet（存在しません）

複数プロジェクトにまたがるタスク

タスクが複数のリポジトリ／ディレクトリにまたがる場合は、--add-dir を使用してアクセス権を付与します。

codex exec --full-auto -C "$(pwd)" --add-dir /path/to/other/repo -o output.md "prompt"

--add-dir フラグは、複数の追加ディレクトリに対して繰り返し指定できます。

進捗の監視（任意）

--json を追加すると、JSONL イベントが標準出力にストリーミングされ、リアルタイムで監視できます。

codex exec --full-auto --json -C "$(pwd)" -o output.md "prompt" 2>/dev/null

主なイベント：

• turn.started / turn.completed — 進捗を追跡します
• turn.completed にはトークンの usage フィールドが含まれます
• 60秒間イベントがない場合 → エージェントが停止している可能性があります

サンドボックスのレベル

-s を使用してサンドボックスを制御します。

レベル	フラグ	使用する場面
読み取り専用	-s read-only	判定者、レビュアー（ファイルへの書き込みが不要な場合）
ワークスペースへの書き込み	-s workspace-write	--full-auto 使用時のデフォルト
フルアクセス	-s danger-full-access	外部のサンドボックス環境内でのみ

コードレビューや分析のタスクでは、--full-auto よりも -s read-only を優先してください。

実行

ステップ 1：タスクを定義する

作業を焦点の絞られたタスクに分割します。各タスクに Codex エージェントを1つ割り当てます（統合する場合を除く）。

互換性のあるワーカー、ファイル予約、セッションメール、反復実行、または tmux ベースの調整が必要な複数エージェント作業では、エージェントを割り当てる前にreferences/fungible-agent-coordination.mdを読んでください。

ステップ 2：対象ファイルを分析する（必須）

起動する前に、各タスクで編集するファイルを特定してください。 Codex エージェントはヘッドレスであり、ロックについて交渉したり、順番を待ったりできません。競合の防止はすべてここで行います。

各タスクについて、対象ファイルを列挙します。その後、適切な戦略を適用してください。

ファイルの重複	戦略	アクション
すべてのタスクが同じファイルを編集する	統合	すべての修正を1つのエージェントにまとめる
一部のタスクでファイルが重複する	複数ウェーブ	ファイルを共有するタスクは、ウェーブごとに順番に実行する
重複なし	並列	すべてのエージェントを一度に起動する

# Decision logic (team lead performs this mentally):

tasks = [
  {name: "fix spec_path",    files: ["cmd/zeus.go"]},
  {name: "remove beads field", files: ["cmd/zeus.go"]},
  {name: "fix dispatch counter", files: ["cmd/zeus.go"]},
]

# All touch zeus.go → MERGE into 1 agent

tasks = [
  {name: "fix auth bug",     files: ["pkg/auth.go"]},
  {name: "add rate limiting", files: ["pkg/auth.go", "pkg/middleware.go"]},
  {name: "update config",    files: ["internal/config.go"]},
]

# Task 1 and 2 share auth.go → MULTI-WAVE (1+3 parallel, then 2)
# Task 3 is independent → runs in Wave 1 alongside Task 1

tasks = [
  {name: "fix auth",    files: ["pkg/auth.go"]},
  {name: "fix config",  files: ["internal/config.go"]},
  {name: "fix logging", files: ["pkg/log.go"]},
]

# No overlap → PARALLEL (all 3 at once)

ステップ 3：エージェントを起動する

戦略：並列（ファイルの重複なし）

Codex サブエージェントのバックエンド（推奨）：

spawn_agent(message="Fix the null check in pkg/auth.go:validateToken around line 89...")
spawn_agent(message="Add timeout field to internal/config.go:Config struct...")
spawn_agent(message="Fix log rotation in pkg/log.go:rotateLogFile...")

Codex CLI バックエンド：

Bash(command='codex exec --full-auto -C "$(pwd)" -o .agents/codex-team/auth-fix.md "Fix the null check in pkg/auth.go:validateToken around line 89..."', run_in_background=true)
Bash(command='codex exec --full-auto -C "$(pwd)" -o .agents/codex-team/config-fix.md "Add timeout field to internal/config.go:Config struct..."', run_in_background=true)
Bash(command='codex exec --full-auto -C "$(pwd)" -o .agents/codex-team/logging-fix.md "Fix log rotation in pkg/log.go:rotateLogFile..."', run_in_background=true)

戦略：統合（同じファイル）

すべての修正を単一のエージェントプロンプトにまとめます：

spawn_agent(message="Fix these 3 issues in cmd/zeus.go: (1) rename spec_path to spec_location in QUEST_REQUEST payload (2) remove beads field (3) fix dispatch counter increment location")

# CLI equivalent:
Bash(command='codex exec --full-auto -C "$(pwd)" -o .agents/codex-team/zeus-fixes.md \
  "Fix these 3 issues in cmd/zeus.go: \
   (1) Line 245: rename spec_path to spec_location in QUEST_REQUEST payload \
   (2) Line 250: remove the spurious beads field from the payload \
   (3) Line 196: fix dispatch counter — increment inside the loop, not outside"', run_in_background=true)

エージェント 1 つ、ファイル 1 つで、競合は発生しません。

戦略：複数ウェーブ（部分的に重複）

# Wave 1: non-overlapping tasks (sub-agent backend)
spawn_agent(message='Fix null check in pkg/auth.go:89...')
spawn_agent(message='Add timeout to internal/config.go...')

# Wait for Wave 1 (sub-agent backend)
wait(ids=["<id-1>", "<id-2>"], timeout_ms=120000)

# Wave 1: non-overlapping tasks (CLI backend)
Bash(command='codex exec ... -o .agents/codex-team/auth-fix.md "Fix null check in pkg/auth.go:89..."', run_in_background=true)
Bash(command='codex exec ... -o .agents/codex-team/config-fix.md "Add timeout to internal/config.go..."', run_in_background=true)

# Wait for Wave 1
TaskOutput(task_id="<id-1>", block=true, timeout=120000)
TaskOutput(task_id="<id-2>", block=true, timeout=120000)

# Read Wave 1 results — understand what changed
Read(.agents/codex-team/auth-fix.md)
git diff pkg/auth.go

# Wave 2: task that shares files with Wave 1 (sub-agent backend)
spawn_agent(message='Add rate limiting to pkg/auth.go and pkg/middleware.go. Note: validateToken now has a null check at line 89. Build on current file state.')

# Wave 2: CLI backend equivalent
Bash(command='codex exec ... -o .agents/codex-team/rate-limit.md \
  "Add rate limiting to pkg/auth.go and pkg/middleware.go. \
   Note: pkg/auth.go was recently modified — the validateToken function now has a null check at line 89. \
   Build on the current state of the file."', run_in_background=true)

TaskOutput(task_id="<id-3>", block=true, timeout=120000)

チームリードはウェーブ 1 の結果を統合し、関連するコンテキストをウェーブ 2 のプロンプトに組み込みます。生の差分をそのまま貼り付けるのではなく、何が変わり、それが次のタスクにとってなぜ重要なのかを説明します。

ステップ 4：完了を待つ

# Sub-agent backend:
wait(ids=["<id-1>", "<id-2>", "<id-3>"], timeout_ms=120000)

# CLI backend:
TaskOutput(task_id="<id-1>", block=true, timeout=120000)
TaskOutput(task_id="<id-2>", block=true, timeout=120000)
TaskOutput(task_id="<id-3>", block=true, timeout=120000)

ステップ 5：結果を確認する

• .agents/codex-team/ の出力ファイルを読みます
• git diff で各エージェントが行った変更を確認します
• 該当する場合はテストを実行します
• 複数ウェーブの場合：ウェーブ 2 のエージェントがウェーブ 1 の変更を正しく反映していることを確認します

出力ディレクトリ

mkdir -p .agents/codex-team

出力ファイル：.agents/codex-team/<task-name>.md

プロンプトのガイドライン

適切な Codex プロンプトは、具体的で自己完結しているものです：

# GOOD: Specific file, line, exact change
"Fix in cmd/zeus.go line 245: rename spec_path to spec_location in the QUEST_REQUEST payload struct"

# BAD: Vague, requires exploration
"Fix the spec path issue somewhere in the codebase"

各プロンプトに以下を含めます：

• 正確なファイルパス
• 行番号または関数名
• 変更内容とその理由
• 制約事項（他のファイルには触れない、API 互換性を維持するなど）

複数ウェーブのウェーブ 2 以降のプロンプトには、さらに以下を含めます：

• 以前のウェーブでの変更内容（生の差分ではなく要約）
• 以前の編集後における共有ファイルの現在の状態

制限

• エージェントの最大数： 1 ウェーブにつき 6（リソースを考慮した数）
• タイムアウト： エージェントごとのデフォルトは 2 分です。大規模なタスクでは timeout パラメーターで延長します
• ウェーブの最大数： 推奨は 3 です。それ以上必要な場合は、タスクの分割方法を見直してください

フォールバック

Codex を利用できない場合は、/swarm に委任します。/swarm は、利用可能な最適なバックエンド（メッセージング／リダイレクト／正常なシャットダウンに対応したネイティブチーム、または最終手段としてのバックグラウンドタスク）を自動で選択します：

Skill(skill="swarm")

注： /codex-team は Codex CLI プロセスをバックグラウンドのシェルコマンドとして実行します（別々の OS プロセスであるため、問題ありません）。Claude エージェントのオーケストレーションには、ランタイムのネイティブなマルチエージェントプリミティブを使用する /swarm を使ってください。

クイックリファレンス

項目	値
モデル	ユーザーが設定した Codex のデフォルト（特定のモデルに固定するには -m "<model>"）
コマンド	codex exec --full-auto -C "$(pwd)" -o <file> "prompt"
出力ディレクトリ	.agents/codex-team/
ウェーブあたりのエージェント最大数	推奨は 6
タイムアウト	デフォルトは 120 秒
戦略	並列（重複なし）、統合（同じファイル）、複数ウェーブ（部分的に重複）
フォールバック	/swarm（ランタイムネイティブ）

---

例

並列実行（ファイルの重複なし）

ユーザーの依頼： /codex-team を使って auth.go、config.go、logging.go の 3 つのバグを修正する

動作の流れ：

1. エージェントが対象ファイルを分析します（auth.go、config.go、log.go — 重複なし）
2. エージェントが並列戦略を選択します
3. エージェントが 3 つの Codex エージェントを起動します（利用可能な場合はサブエージェント、そうでなければ Bash 経由の CLI）
4. すべてのエージェントが同時に実行され、.agents/codex-team/*.md に書き込みます
5. チームリードが git diff とテストで結果を確認します
6. チームリードがすべての変更をまとめてコミットします

結果： ファイルの競合なしで、3 つのバグを並列に修正できます。

統合戦略（同じファイル）

ユーザーの依頼： zeus.go の 3 つの問題を修正する：フィールド名を変更し、未使用のフィールドを削除し、カウンターを修正する

動作の流れ：

1. エージェントが対象ファイルを分析します（3 つのタスクすべてが zeus.go に関係しています）
2. エージェントが統合戦略を選択します
3. エージェントが、行を指定した指示を含む単一の Codex プロンプトに 3 つの修正をまとめます
4. エージェントが統合済みのプロンプトで Codex エージェントを 1 つ起動します
5. エージェントが 1 回の処理ですべての修正を完了します
6. チームリードが確認してコミットします

結果： エージェント 1 つ、ファイル 1 つで、競合は発生しません。

複数ウェーブ（一部重複）

ユーザーの指示： auth.go を修正し、auth.go + middleware.go にレート制限を追加し、config.go を更新する

実行内容：

1. エージェントが重複を特定します。タスク 1 と 2 の両方で auth.go が対象です
2. エージェントが作業をウェーブに分割します。W1 = タスク 1 + タスク 3（重複なし）、W2 = タスク 2
3. エージェントが Wave 1 のエージェントを並列で起動し、完了を待ちます
4. エージェントが Wave 1 の結果を読み取り、Wave 2 用のコンテキストをまとめます
5. エージェントが更新されたファイル状態のコンテキストを付けて、Wave 2 のエージェントを起動します
6. Wave 2 の後、チームリードが検証してコミットします

結果： ウェーブを順番に実行することで競合を防ぎ、コンテキストを引き継ぎます。

---

トラブルシューティング

問題	原因	解決策
Codex CLI が見つからない	codex がインストールされていない、または PATH にない	npm i -g @openai/codex を実行するか、フォールバックの /swarm を使用します
デフォルトの Codex モデルを利用できない	アカウント／設定の不一致、またはデフォルトが未対応	codex exec --full-auto -C "$(pwd)" "echo ok" が動作することを確認するか、-m "<model>" で対応モデルを指定します
エージェントがファイル競合を起こす	複数のエージェントが同じファイルを編集している	ファイル対象の分析を行い、マージ戦略または複数ウェーブ戦略を適用します
エージェントが出力なしでタイムアウトする	タスクが複雑すぎる、またはプロンプトが曖昧	タスクを小さく分割し、ファイルと行を具体的に指定します
出力ファイルが空、または存在しない	-o のパスが無効、またはアクセスが拒否されている	.agents/codex-team/ ディレクトリが存在し、書き込み可能であることを確認します

参考ドキュメント

• references/fungible-agent-coordination.md
• references/claude-code-latest-features.md
• ../shared/references/claude-code-latest-features.md
• references/codex-team.feature — 実行可能な仕様：対象ファイルを分析してスコープの重複を避け、競合のないウェーブを起動し、結果を回収する前に完了を待ちます（soc-qk4b）