第6章 §2-C・Codex中心マルチエージェントチーム実習
空の実習フォルダから始めてCodex Desktop App/Codex CLIを中心にシナリオを一つずつ実践していく実習ガイド — 両ツールは役割の定義・遂行方式に差がないため、この節ではまとめて案内する | ← 第6章 §1 リファレンス文書に戻る | 第6章 §2-A Claude中心 → | 第6章 §2-B Antigravity中心 →
AGENTS.md仕様として書く。Codexではその仕様をあらかじめ定義済みのサブエージェントとして「実装」しない。代わりに、同じ仕様をワークスペース共通フォルダagents/<name>.mdにも書き写しておき、セッション中にPMがそのファイルを読み取り専用の役割コンテキストとして読み込み、「その役割のように考えながら」自ら作業を遂行する。定義は一つ、実行方式だけがツールごとに異なるという原則を手を動かして確認することが、この実習の中心的な目標である — Claude・Antigravityでの対応方法は第6章 §2-A・第6章 §2-Bを参照する。
準備: 必要なプログラムのインストール
以下の実習はCodex Desktop AppとCodex CLIを中心に進める。ローカル環境にこれらのツールがまだなければ、このハンドブックに同梱された環境設定自動化ツールであるsetupガイドが、この章の実習に必要な構成を自動的にインストールしてくれる。案内に従ってスクリプトをダウンロードし、ローカルで実行すればよい。
スクリプトを実行する前に事前インストールチェックリストを先に読んでおく。この文書には次の前提条件がまとめられている。
- 有効なOpenAIアカウントとCodex利用権限(サブスクリプション/アカウントベースのプラン、または組織のポリシーによってはAPIキー)
gh auth loginを実行できるGitHubアカウント- 最低5GBの空きディスク容量
- 管理者(admin)またはsudo権限
① ブラウザでgithub.com/signupにアクセスする。
② メールアドレス、パスワード、ユーザー名を入力する — ユーザー名はリポジトリURL(
github.com/<username>/...)にそのまま使われるので慎重に決める。③ 自動登録防止のためのパズル/コード認証を通過する。
④ 登録時に入力したメールに届いた認証メールを開きメール認証を完了する — この手順を飛ばすと、後で
gh auth loginやリポジトリ作成がブロックされることがある。⑤ 無料(Free)プランで登録すれば十分 — このハンドブックの実習・PR練習には有料プランは不要。
登録が終わるとGitHub CLI(
gh)が上記のインストールスクリプトに含まれて一緒にインストールされ、下記のgh auth loginコマンドでターミナルをそのアカウントに接続する。
gh auth login # 案内に従って: GitHub.comを選択 → HTTPSを選択 → ブラウザでログイン(推奨)を選択 # ブラウザが開いたら先ほど作成したアカウントでログインし、認証コードを確認する
Windowsでのインストール
このハンドブックのパス表記はWindows基準なので、Windowsユーザーは以下のコマンドで5throck/setupリポジトリをクローンした後、PowerShellを管理者権限で実行して続くコマンドを実行する。
① スタートメニューを開き
PowerShellを検索する。② 検索結果の「Windows PowerShell」を右クリックする。
③ 表示されるメニューから「管理者として実行」を選択する。
④ ユーザーアカウント制御(UAC)のウィンドウが表示されたら「はい」を押して承認する。
ウィンドウのタイトルバーに
管理者: Windows PowerShellのように「管理者」が付いていれば正しく開けている。wingetインストールなど一部の手順は管理者権限なしで実行するとエラーになったり、静かにスキップされたりすることがある。
git clone https://github.com/5throck/setup.git cd ./setup powershell -ExecutionPolicy Bypass -File .\setup-windows.ps1 # オプション: -WSL2, -WezTerm, -Docker, -Force (インストール済みツールも再インストール)
スクリプトが終わったらターミナルを完全に閉じてから開き直さないと、PATHの変更が反映されない。
macOS / Linuxでのインストール
以下のコマンドで5throck/setupリポジトリをクローンして使う。macOSはsetup-mac.sh、Linuxはsetup-linux.shを実行し、両方とも--wezterm、--dockerの任意フラグをサポートする。
git clone https://github.com/5throck/setup.git # macOS cd ./setup && bash setup-mac.sh # Linux cd ./setup && bash setup-linux.sh
インストールの検証
OSに関係なくsetup-common.tsをbunで実行すると、インストール状況を点検するチェックリスト表が出力される。すべての項目が✅で表示されれば、以下の実習を進める準備が整ったということ。
cd ./setup && bun setup-common.ts
このプロジェクトがインストールするツールのうち、この章の実習に直接関わるのは次の通り。Codex Desktop App、codex(Codex CLI)、そしてワークスペース共通のagents/*.md参照に必要なbun、後の章で使うgh(GitHub CLI)も一緒にインストールされる。
%USERPROFILE%\workshop-setup-logs\フォルダにログが残る。問題解決の際はまずこのログを確認する。
harness-lab/を新しく作り、reviewer役割をツール中立的なAGENTS.md仕様としてまず書いた後、同じ内容をagents/reviewer.mdにも書き写す。Codex Desktop AppでPMがこのファイルを読み取り専用の役割コンテキストとして読み込み、「レビュアーのように考えながら」直接検討を遂行する過程を観察する。このフォルダは実習専用なので、他のプロジェクトファイルと混ざらない。
-
① 実習フォルダの作成と移動
現在のフォルダの下に
harness-labフォルダを新しく作り、その中に移動する。以降のすべてのコマンドはこのフォルダ内で実行する。mkdir -p harness-lab cd harness-lab
-
② 共通の役割仕様を書く —
AGENTS.mdClaude、Antigravity、Codex、その他AGENTS.md標準をサポートするどのツールで開いても同じ意味で読めるよう、
reviewer役割をツール依存の表現なしに純粋なテキストで書く。このファイル一つが「何をする役割か」の唯一の原本になる。macOS/Linux/Git Bashでは以下のコマンドをそのまま使う。cat > AGENTS.md << 'EOF' ## Agent: reviewer 役割: テキストファイルの誤字、論理的な穴、改善点を検討する。 入力: 検討対象のテキストファイルパス 出力: 誤字・論理的な穴・改善点のリスト 権限: 読み取り専用 — ファイルを直接修正しない。 EOF
Windows PowerShellでは
catコマンド自体はGet-Contentのエイリアスとしてファイル読み取りにそのまま使える。ただし<< 'EOF'のように複数行を直接入力するheredoc構文はサポートされないため、同じ内容を引用符付きのhere-string(@'...'@)で作ってSet-Contentでファイルに書き込む。@' ## Agent: reviewer 役割: テキストファイルの誤字、論理的な穴、改善点を検討する。 入力: 検討対象のテキストファイルパス 出力: 誤字・論理的な穴・改善点のリスト 権限: 読み取り専用 — ファイルを直接修正しない。 '@ | Set-Content AGENTS.md
-
③ ワークスペース共通の役割ファイルに書き写す —
agents/reviewer.mdCodexは
.claude/agents/のようなプラットフォーム専用フォルダの代わりに、ワークスペースルートのagents/<name>.mdを読み取り専用の役割コンテキストとして参照する。AGENTS.mdの仕様をそのままfrontmatter形式で書き写す。mkdir -p agents cat > agents/reviewer.md << 'EOF' --- name: reviewer description: テキストファイルの誤字、論理的な穴、改善点を検討する tools: Read, Grep tier: codex: medium --- ## 役割 テキストファイルの誤字、論理的な穴、改善点を検討する。 ## 入力 検討対象のテキストファイルパス ## 出力 誤字・論理的な穴・改善点のリスト ## 権限 読み取り専用 — ファイルを直接修正しない。 EOF
ターミナルや別のエディタで事前にファイルを作らない。以下の2つのステップをそのまま進める — グレーのコードボックスはすべて「コピー」ボタンでそのままコピーして貼り付ければよい内容である。
-
① Codex Desktop Appでプロジェクトを開く
Codex Desktop Appを起動し、先ほど作った
harness-lab/フォルダをプロジェクトとして開く。 -
② 検討対象ファイルの作成 + 役割コンテキストでの検討依頼 — チャット欄に以下の文章をそのまま貼り付けて送信
notes.txtファイルを作り「このプロジェクトはとても良い。これはとても良い。」と書き込んだ後、agents/reviewer.mdに定義されたreviewer役割を読み取り専用コンテキストとして読み込んで、その役割通りnotes.txtを検討して。
Codex Desktop AppのPMは別のサブエージェントをスポーンしない。代わりにagents/reviewer.mdをReadツールで開き、「役割/入力/出力/権限」の仕様をコンテキストに読み込み、以後の応答をその役割の制約(読み取り専用、誤字・論理的な穴・改善点のみ報告)に合わせて生成する — ファイルを実際に修正しないことも自ら守らなければならない。画面にはサブエージェントのスポーン過程の代わりに、PMがagents/reviewer.mdを読むツール呼び出しとそれに続く検討結果が、一つの連続したセッションとして表示される。
Codex CLIでも完全に同じく — ターミナルでcodexを実行した後、②の文章をそのままチャットに貼り付ければ、CLIも同じくagents/reviewer.mdを読んでその役割通り応答する。Codex Desktop AppとCLIの間で役割の定義・遂行方式の違いはない — どちらも自動発火するフックもない。
agents/reviewer.mdを読むツール呼び出しが実際に表示されているか確認する。最後の応答には誤字・論理的な穴・改善点に分けたリストが表示されるのが正常 — PMが「修正しました」のような答えをしたりnotes.txtを直接直したりした場合は、agents/reviewer.mdの「読み取り専用」権限制約を自ら守らなかったということである(Codexにはこれを強制するtools制限の仕組みがない — 役割文書の指針をPM自身が守る構造である)。
agents/reviewer.mdを読まずにそのままnotes.txtを検討してしまう場合、②のステップの文章にagents/reviewer.mdに定義されたreviewer役割を読み取り専用コンテキストとして読み込んでという表現が抜けている場合である。Claude系の「サブエージェント呼び出し」と違い、Codexは役割ファイルを明示的に参照するよう要求しないと、そのままデフォルトのPMペルソナで応答することがある。
harness-lab/フォルダで、2つ目の役割writerもG-1と同じ方式でAGENTS.mdとagents/writer.mdにまず明記する。Codex PMがwriter役割として先に下書きを書き、同じセッション内でreviewer役割に切り替えてその結果を批評する過程を、順序を守りながら観察する — 両方の役割とも同じPMが順番に「演じる」だけで、別のインスタンスがスポーンされないという点がClaude/Antigravityとの核心的な違いである。
Claude/Antigravityはwriter.md/reviewer.mdそれぞれのインスタンスをスポーンするが、Codexは単一のPMセッションが役割だけ変えて順番に「演じる」 — 4つのボックスすべて同じPMである。
-
共通の役割仕様を追加 —
AGENTS.mdにwriter項目を書き足すG-1で作った同じ
AGENTS.mdにwriter役割を書き足す。reviewer項目はそのままにして以下の内容だけを追加する。macOS/Linux/Git Bashでは以下のコマンドをそのまま使う。cat >> AGENTS.md << 'EOF' ## Agent: writer 役割: 与えられたテーマで3〜5文程度の短い下書きを作成する。 入力: テーマ、保存するファイルパス 出力: 下書きテキストファイル 権限: 書き込み許可 — 指定されたファイルにのみ保存する。 handoff_to: reviewer (下書き完了後、検討に引き継ぐ) EOF
Windows PowerShellではhere-stringを
Add-Contentで追記する(Set-Contentはファイルを上書きするため、reviewer項目が消えないよう必ずAdd-Contentを使う必要がある)。@' ## Agent: writer 役割: 与えられたテーマで3〜5文程度の短い下書きを作成する。 入力: テーマ、保存するファイルパス 出力: 下書きテキストファイル 権限: 書き込み許可 — 指定されたファイルにのみ保存する。 handoff_to: reviewer (下書き完了後、検討に引き継ぐ) '@ | Add-Content AGENTS.md
-
ワークスペース共通の役割ファイルを追加 —
agents/writer.mdcat > agents/writer.md << 'EOF' --- name: writer description: 与えられたテーマで3〜5文程度の短い下書きを作成する tools: Write, Read tier: codex: medium --- ## 役割 与えられたテーマで3〜5文程度の短い下書きを作成する。 ## 入力 テーマ、保存するファイルパス ## 出力 下書きテキストファイル ## 権限 書き込み許可 — 指定されたファイルにのみ保存する。 ## handoff_to reviewer (下書き完了後、検討に引き継ぐ) EOF
G-1と同じくファイルを事前に準備しない。G-1で開いておいた同じharness-lab/チャットで続けて進める。
-
① writer → reviewer順次切り替えの依頼 — チャット欄に以下の文章をそのまま貼り付けて送信
agents/writer.mdに定義されたwriter役割を読み取り専用コンテキストとして読み込んで、その役割通りdraft.txtに「リモートワークの利点」というテーマの下書きを書いて。完了したらagents/reviewer.mdに定義されたreviewer役割に切り替えてdraft.txtを検討して。2つの段階を順番に進めて。
PMはまずagents/writer.mdを読み、writer役割の制約(書き込み許可、下書きのみ作成)をコンテキストに読み込んでdraft.txtを生成する。その作業が終わってからagents/reviewer.mdを新たに読み、今度は読み取り専用のレビュアーとして「役割を着替え」てdraft.txtを検討する — 別のインスタンスがスポーンされるのではなく、同じセッション・同じPMが参照する役割ファイルだけが変わるのである。2つの役割の順序を調整するのもこのPM自身の仕事である。
agents/writer.mdの読み込み → draft.txt作成 → agents/reviewer.mdの読み込み → 検討結果の順にツール呼び出しが表示されるのが正常。完了後harness-lab/draft.txtを開いて下書きが実際に保存されているかも確認する。
Codex CLIでも完全に同じく — 同じagents/writer.md/agents/reviewer.mdをそのまま使い、ターミナルで①の文章をそのまま貼り付ければ同じく順次切り替わる。
agents/writer.md・agents/reviewer.mdはそのままにして、要求の性質だけを変えながら、同じPMが実際にどの役割を、何回、どの順序で参照するのかを観察する — 役割定義ファイルは一度も新しく作らないという点がポイントである。Codexには並列ファンアウト自体が存在しないため、「2つの観点を同時に検討」というような要求も、実際にはPMが1つの観点ずつ順次処理する。
D-1を終えた同じチャットで続けて進める。毎回PMがどの役割ファイルを読み、何回切り替えるか、画面に表示されるツール呼び出しの過程に注目する。
-
① 単純な要求 — reviewer役割が1回だけ必要な場合
draft.txtの誤字だけざっと見て。
PMは今回のリクエストにwriter役割への切り替えが不要だと判断し、agents/reviewer.mdだけを参照して終える。同じ役割名簿(writer+reviewer)が定義されていても、実際にどの役割を「演じる」かはリクエストごとにPMがその都度決めるということを示す最も単純な例である。 -
② 複合的な要求 — writer役割とreviewer役割を2つの観点で順次組み合わせる
draft2.txtに「週4日勤務制」というテーマで新しい下書きを書いて。下書きが完了したら、その下書きを文法の観点と論理の観点の2つでそれぞれ検討して。Codexは同時実行をサポートしないので、1つの観点ずつ順番に進めて。
今回はPMがagents/writer.mdを参照して下書きを書いた後、agents/reviewer.mdに切り替えて「文法の観点」で1回、続けて「論理の観点」で再度1回 — 同じ役割を異なる指示で2回順次遂行する。Claude/Antigravityの「ファンアウト(同時並列検討)」とは異なり、Codexではこれが常に順次的な2回反復として現れる — 同じ2つの役割で①とはまったく異なる形のワークフローが作られたという点は同じである。
agents/にどの役割を定義しておいたか)」と「今回の作業に実際に使われる構成(どの役割を何回、どの順序で参照するか)」が異なる層であることがはっきりする。前者はワークスペースに事前に固定されているが、後者はリクエストごとにPMが新しく決定する — ただしCodexは常に順次的にしか決定できないという制約がある。
Codex CLIでも完全に同じく — 同じagents/writer.md/agents/reviewer.mdをそのまま使い、ターミナルで①②の文章をそのまま貼り付ければ同じく動作する。
topic-a.txt、topic-b.txtの下書き作成)を同時に進めたいと考える。Codexには一つのセッション内でチームメイトを並列スポーンする機能がないため、同じharness-lab/フォルダを対象にターミナルウィンドウ(またはCodex CLIセッション)を2つ別々に開いて、それぞれ独立してタスクを任せる — 「並列」の単位がチームメイトではなくセッション自体である。
同じharness-lab/フォルダを対象にターミナルウィンドウを2つ開く(tmuxなどの分割ウィンドウを使ってもよい — Codex CLI自体にはClaude CodeのteammateMode: "tmux"のような組み込みサポートがないため、ターミナルマルチプレクサはユーザーが自分で構成する)。
-
① 1つ目のターミナル — writer役割でtopic-a.txtを作成
1つ目のターミナルで
harness-lab/に移動しcodexを実行して、以下の文章を貼り付ける。cd harness-lab codex
agents/writer.mdに定義されたwriter役割でtopic-a.txtに「リモートワーク」というテーマの下書きを書いて。完了したらagents/reviewer.mdのreviewer役割に切り替えて検討もして。
-
② 2つ目のターミナル — 同時にwriter役割でtopic-b.txtを作成
①とは別の2つ目のターミナルを新しく開き、同じ
harness-lab/に移動してcodexをもう一度実行する。このセッションは①のセッションと完全に独立している — 同じワークスペースを見ているだけで、会話の文脈も進行状態も共有しない。cd harness-lab codex
agents/writer.mdに定義されたwriter役割でtopic-b.txtに「週4日勤務制」というテーマの下書きを書いて。完了したらagents/reviewer.mdのreviewer役割に切り替えて検討もして。
SendMessageのようなセッション間の直接通信手段もない。2つのセッションが同じファイル(例えば両方がAGENTS.mdを修正しようとする)を同時に触ると、ファイルシステムレベルの競合がそのまま発生しうるため、完全に分離された対象ファイルを割り当てるのが安全だという点はClaude/Antigravityと同じである。
agents/writer.md自体を修正しようとすると(例えば「ティアを変えて」のような要求を両方から同時に送ると)ファイル書き込みの競合が発生し、片方の変更が上書きされることがある。並列で実行するときは「対象ファイル(topic-a.txt/topic-b.txt)」だけをそれぞれ触らせ、役割定義ファイル自体を変更する要求は並列セッションでは避ける。
G-1のnotes.txtより少し複雑で、論理的な穴のある文章を準備する。チャット欄に以下の文章をそのまま貼り付ける。
-
① 検討対象ファイルの準備
argument.txtファイルを作り、次の内容を書いて: 「リモートワークは常にオフィス勤務より生産的だ。なぜならリモートワークをしている人々がリモートワークは良いと言っているからだ。したがってすべての会社はリモートワークのみにすべきだ。」
-
② lowティア(gpt-5.6-luna)で検討
チャット欄に以下の文章をそのまま貼り付ける。PMが
agents/reviewer.mdのtier.codexフィールドをlowに変えた後、その役割で検討を遂行する。agents/reviewer.mdのtier.codexフィールドをlowに変えて。そしてそのreviewer役割でargument.txtを検討して。
-
③ mediumティア(gpt-5.6-terra)で同じ要求を繰り返す
同じ方式で
tier.codexをmediumに変えてから検討する。循環論法のような論理的な穴を正確に指摘できるか、low結果と比較する。agents/reviewer.mdのtier.codexフィールドをmediumに変えて。そしてそのreviewer役割でargument.txtを検討して。
-
④ highティア(gpt-5.6-sol)で同じ要求を繰り返す
同じ方式で
tier.codexをhighに変えてから検討する。応答時間と指摘の深さが②③とどう違うか記録する。agents/reviewer.mdのtier.codexフィールドをhighに変えて。そしてそのreviewer役割でargument.txtを検討して。
gpt-5.6-lunaは3つの中で最も速く応答する — 第7章で説明する「判断が重い役割ほど高いティア、定型化された作業ほど低いティア」という原則がなぜ存在するのか、速度と深さのトレードオフを直接体験するとずっと明確になる。
agents/reviewer.mdを修正した後、その役割で検討を遂行する。
tier.codexフィールドに存在しない値(haiku/sonnet/opusのようなClaude系の名前をそのまま使う間違いなど)が入ると、PMがその値を無視してデフォルトティアに黙って置き換えることがある。②③④が終わったらagents/reviewer.mdを直接開いて、tier.codexの値がlow/medium/highのうち意図した値と正確に一致しているか確認する。
実習の後片付け
5つのシナリオをすべて終えたら、harness-lab/フォルダをどうするか決める。次の章(第7章)では新しい実習フォルダを使うので必ず残しておく必要はないが、これまで作ったAGENTS.md・agents/*.mdの定義を比較してみたければ、削除する前に一度目を通しておくことを勧める。
もう必要ない場合はフォルダ全体を削除する。macOS/Linux/Git Bashでは以下のコマンドをそのまま使う。
cd .. rm -rf harness-lab
Windows PowerShellでは
cd .. Remove-Item -Recurse -Force harness-lab
git init && git add -A && git commit -m "harness-lab実習記録"でローカルコミットだけ残しておく方法もある。以後は参考資料として残しておき、次の章の実習は別の新しいフォルダで始めてもよい。
harness-lab/フォルダを削除すると次のコマンドでエラーになる。フォルダを整理する前に両方のセッションを終了(Ctrl+Cまたはexit)したか確認する。
参考動画
- ENCodex — OpenAI Developers — Codex CLI/Desktop App公式紹介資料
Codex CLI/App 2026-09基準 | 2026年9月12日作成
← 第6章 §1 マルチエージェントチーム活用リファレンス · 第6章 §2-A Claude中心実習 · 第6章 §2-B Antigravity中心実習 · 第7章 ai-workspace-standards紹介 →