私は、AIコーディングツールとして Claude Code と Codex を併用しています。
基本的な役割分担は、次のとおりです。
- Claude Code：設計、計画、レビュー
- Codex：実装作業
設計や判断には高性能なAIを使い、実装は別のAIに任せることで、トークン、つまり利用量を節約する運用をしていました。
ところが、使い込むうちに、いくつかの困りごとが積み重なってきました。
困っていたこと
指示書がバラバラ
Claude Codeは CLAUDE.md、Codexは AGENTS.md を読みます。
同じルールを両方のファイルに書くのは面倒です。最初は同じ内容でも、更新を繰り返すうちに、少しずつ内容がずれてしまいます。
新規プロジェクトのたびに設定が必要
新しいフォルダで開発を始めるたびに、共通ルールを設定し直す必要がありました。
理想は、どのフォルダで起動しても、特に指示しなくても共通ルールが読み込まれる状態です。
トークン消費が気になる
指示書はセッション開始時に読み込まれます。
ルールを書き足すほど毎回のトークン消費も増えていきます。しかし、ファイルを分割すれば節約できるのか、どの部分を削るべきなのかが分かりませんでした。
昔作ったマルチエージェント環境が残っている
以前、tmuxを使って複数のAIエージェントを並行稼働させる環境を導入していました。
しかし、現在のClaude Codeにはサブエージェントなどの標準機能があります。昔の仕組みを今も残すべきなのか、削除してよいのか判断できない状態でした。
これらの問題をClaude Codeと相談しながら、半日ほどかけて整理しました。
この記事は、その作業記録です。
全体のフロー
解決1：ルールの「正本」を1つにする
まず、Claude CodeとCodexでは、読み込む指示書が異なります。
- Codex：
AGENTS.md - Claude Code：
CLAUDE.md
そのまま運用すると、同じルールを2つのファイルに書かなければなりません。
そこで、次の形に統一しました。
-
AGENTS.mdをメインの指示書にする -
CLAUDE.mdには@AGENTS.mdの1行だけを書く
Claude Codeでは、@を使って別のファイルを参照できます。
そのため、Claude Codeは CLAUDE.md を入口として AGENTS.md を読み、Codexは AGENTS.md を直接読みます。
Claude Code
↓
CLAUDE.md
↓ @AGENTS.md
AGENTS.md
Codex
↓
AGENTS.md
どちらのツールも、最終的には同じ AGENTS.md にたどり着きます。
これで、修正する指示書は1つだけになりました。AGENTS.mdを更新すれば、Claude CodeとCodexの両方が同じルールで動きます。
解決2：どのプロジェクトでも共通ルールを自動で読み込む
次に、プロジェクトを新しく作った場合でも、共通ルールが自動的に適用されるようにしました。
Claude Codeには、どのフォルダで起動しても読み込まれるユーザー共通の指示ファイルがあります。
~/.claude/CLAUDE.md
~はユーザーのホームフォルダです。
Windowsの場合は、通常、次の場所に相当します。
C:\Users\<ユーザー名>
この ~/.claude/CLAUDE.md に、共通ルールファイルへの参照を1行だけ記述します。
@<共通ルールを置いたフォルダ>/global-rules.md
これで、Claude Codeをどのフォルダで起動しても、global-rules.md が自動的に読み込まれます。
Codex側の設定
Codexにも、ユーザー共通の指示ファイルがあります。
~/.codex/AGENTS.md
このファイルも、どのフォルダでCodexを起動しても読み込まれます。
ただし、CodexにはClaude Codeの @ のように、別ファイルの内容を自動展開する仕組みがありません。
そこで、~/.codex/AGENTS.md には、次のような指示を書きました。
作業開始時にglobal-rules.mdを読み、その共通ルールに従うこと。
仕組みは少し異なります。
- Claude Code：
@参照によって共通ルールを自動展開する - Codex：指示を受けて、共通ルールファイルを自分で読み込む
それでも、最終的に参照する共通ルールは同じ global-rules.md です。
共通ルールを変更したい場合は、global-rules.mdだけを書き換えれば済みます。
コーディングAIに「共通ルールへ○○を追加して」と依頼すれば、ファイルの更新も任せられます。
これで、どのプロジェクトから起動しても、同じ共通ルールが適用される環境になりました。
解決3：プロジェクト固有の指示書はテンプレート化する
共通ルールを自動化しても、プロジェクトごとのルールは残ります。
例えば、次の内容はプロジェクトによって異なります。
- 使用するプログラミング言語
- 使用するフレームワーク
- 開発サーバーの起動方法
- テストコマンド
- ビルドコマンド
- 編集してよいファイル
- 触ってはいけないファイル
- プロジェクト固有の設計方針
これらは全プロジェクト共通の global-rules.md には書けません。
一方で、新しいプロジェクトを始めるたびに、指示書をゼロから作成するのも大変です。
そこで、新規プロジェクト用のテンプレートを1つ用意しました。
テンプレートは、質問項目だけが書かれた空欄付きのカードのようなものです。
プロジェクト名：（ ）
このプロジェクトで行うこと：（ ）
使用言語：（ ）
起動コマンド：（ ）
テストコマンド：（ ）
新しいプロジェクトを始めるときに行う作業は、次の2つだけです。
- テンプレートをコピーして、新しいプロジェクトのフォルダに置く
- 空欄に、そのプロジェクトの情報を記入する
例えば、次のように埋めます。
使用言語：Python
起動コマンド：python main.py
これで、そのプロジェクト専用の AGENTS.md が完成します。
テンプレートを1つ作っておけば、プロジェクトが増えても、コピーして空欄を埋めるだけです。
実際には、この作業もAIに任せられます。
このプロジェクトをセットアップして、テンプレートからAGENTS.mdを作成してください。
このように依頼すれば、プロジェクトの構成を調査し、テンプレートのコピーと記入を行ってもらえます。
- 共通ルール：自動で適用
- プロジェクト固有ルール：テンプレートから作成
プロジェクトを立ち上げる際の負担を、かなり小さくできました。
最終的なファイル配置
最終的なファイル構成は、次のようになりました。
~/.claude/CLAUDE.md
Claude Codeが必ず読む入口
中身はglobal-rules.mdへの@参照だけ
~/.codex/AGENTS.md
Codexが必ず読む入口
「global-rules.mdを読むこと」という指示だけ
<中央管理フォルダ>/
├── global-rules.md
│ └── 全プロジェクト共通ルールの正本
│ 常時読み込むため、約50行に厳選
│
├── templates/
│ └── AGENTS.template.md
│ 新規プロジェクト用の穴埋めテンプレート
│
└── docs/
└── 長い詳細資料
規約、DB設計、運用手順など
必要なときだけ読み込む
<各プロジェクト>/
├── CLAUDE.md
│ └── @AGENTS.md の1行だけ
│
└── AGENTS.md
└── テンプレートをコピーして作成した
プロジェクト固有のルール
重要なのは、ホームフォルダに置くファイルを「入口」に徹することです。
ホーム直下のファイルに大量のルールを直接書くのではなく、実際の共通ルールは中央管理フォルダの global-rules.md に集約します。
これにより、編集やバックアップをするときも、中央管理フォルダだけを確認すればよくなりました。
解決4：トークン節約は「ファイル分割」ではなく「常時読み込みを減らす」
今回、一番大きな学びだった部分です。
私は当初、指示書を複数のファイルに分割すれば、トークン消費を減らせるのではないかと考えていました。
しかし、単にファイルを分けるだけでは節約になりません。
例えば、次のように参照を連鎖させたとします。
CLAUDE.md
↓
@A.md
↓
@B.md
AとBの内容がすべて読み込まれるのであれば、消費されるトークン数は、1つのファイルにまとめた場合とほとんど変わりません。
ファイル分割は整理には役立ちますが、それだけではトークン節約にはならないということです。
節約に効果があった3つの方法
1. 常時読み込むルールを最小限にする
共通ルールには、本当に毎回必要な内容だけを書きます。
私の環境では、global-rules.mdを約50行まで絞りました。
2. 使用頻度の低い詳細は、参照ではなくパスだけを書く
たまにしか使わない長い資料には、@を付けません。
例えば、共通ルールには次のように書きます。
データベース設計の詳細が必要な場合は、docs/database.mdを読むこと。
これなら、毎回全文を読み込む必要はありません。
AIがデータベース作業をするときだけ、必要な資料を読みます。
3. 繰り返し使う作業手順はSkill化する
何度も使う手順は、Skillとして切り出します。
Skillは通常、短い説明文だけが読み込まれます。実際にそのSkillが必要になったときだけ、詳しい本文が読み込まれます。
毎回長い手順書を読み込ませるより、トークンを節約しやすくなります。
つまり、節約のポイントは「ファイルを何個に分けるか」ではありません。
毎回読み込ませる情報を、どこまで減らせるかが重要でした。
解決5：モデルの使い分けとサブスクリプションの整理
コストを見直した結果、Codexで使用しているChatGPTのサブスクリプションは、近いうちに終了することにしました。
これまでCodexが担当していた「実装の委任先」がいなくなります。
しかし、この役割はClaude Codeの標準機能でも、ある程度置き換えられます。
サブエージェントごとにモデルを指定する
Claude Codeでは、サブエージェントに使用するモデルを指定できます。
例えば、次のような分担ができます。
- メインAI：上位モデルで設計とレビュー
- サブエージェント：Sonnetで実装
実装をサブエージェントに任せている間も、メインAIとは次の設計について相談できます。
これにより、これまでClaude CodeとCodexの2画面で行っていた並行作業を、Claude Code内でまとめられる可能性があります。
opusplanモード
opusplanモードでは、計画立案には上位モデルを使用し、実装段階では自動的にSonnetへ切り替えられます。
上位モデルをすべての作業に使わず、重要な判断に集中させられるため、従量課金時のコスト対策として実用的です。
利用上限に応じたフォールバック
利用上限に近づいた場合、下位モデルへ切り替える仕組みも利用できます。
高性能なモデルを常時使い続けるのではなく、作業内容に応じてモデルを使い分けることで、コストを抑えやすくなります。
さらに、今回の移行計画そのものをAIの永続メモリに保存してもらいました。
サブスクリプションの終了後に「終了した」と伝えれば、共通ルールの変更も含め、次の運用へ移行できるように段取りを作っています。
おまけ：整理中に見つけた便利な設定
環境整理のついでに設定した、細かい便利機能を2つ紹介します。
スマートフォンから接続する /remote-control
Claude Codeで次のコマンドを実行します。
/remote-control
スマートフォンのClaudeアプリと連携し、進行中のセッションを外出先から確認したり、追加の指示を出したりできます。
長時間かかる実装をサブエージェントへ任せているときも、PCの前に付きっきりになる必要がありません。
Codexの「Gitリポジトリ外」エラーと --skip-git-repo-check
codex execで実装を依頼したとき、次のような内容のエラーで止まることがあります。
Gitリポジトリ外のため実行が拒否されました。
Codexは、意図しない場所でファイルを変更してしまう事故を防ぐため、既定ではGitリポジトリの外での実行を拒否します。
この確認を省略するのが、次のオプションです。
--skip-git-repo-check
--skip-git-repo-checkは、GitリポジトリではないフォルダでCodexを実行するためのオプションです。
安全確認を1つ外すことになるため、意図した作業フォルダにいることを確認してから使用してください。
私の場合、Git管理していない実験用フォルダで作業することが多く、毎回このエラーでAIが停止し、対応方法を確認してくることが小さなストレスになっていました。
そこで、共通ルールには次のように書きました。
Gitリポジトリ外のエラーが発生した場合は、
Get-Locationなどで現在の作業フォルダを確認し、
依頼対象のフォルダであることを確認したうえで、
--skip-git-repo-checkを付けて再実行すること。
「エラーが出たら無条件で付ける」のではなく、「作業場所を確認してから付ける」という条件を入れておくことで、安全性を保ちながら、停止のたびに人間が対応する手間を減らせます。
AIがつまずくたびに、解決方法を共通ルールへ1行ずつ追加する。
指示書は最初から完璧なものを作るのではなく、実際の失敗やつまずきを反映しながら育てていくものなのだと実感しました。
最終的なフロー
[Claude Code起動] [Codex CLI起動]
│ │
▼ ▼
~/.claude/CLAUDE.md ~/.codex/AGENTS.md
@参照で自動展開 読み込み指示のポインタ
│ │
└────────────┬───────────────────┘
▼
global-rules.md
全プロジェクト共通ルール
ここまでは毎回読み込まれるため
短く保つ
│
▼
プロジェクトのCLAUDE.md
@AGENTS.md
│
▼
プロジェクトのAGENTS.md
テンプレートから作成した
プロジェクト固有ルール
│
▼
docs/内の詳細資料
必要になったときだけ読み込む
トークン節約部分
まとめ
今回の環境整理で、次の形に落ち着きました。
- 指示書の正本は
AGENTS.mdに統一する -
CLAUDE.mdには@AGENTS.mdの1行だけを書く - 共通ルールは
~/.claude/CLAUDE.mdと~/.codex/AGENTS.mdを入口として、どのプロジェクトでも適用する - 全プロジェクト共通のルールは
global-rules.mdに集約する - プロジェクト固有のルールは、テンプレートから作成する
-
@でファイルを分割するだけでは、トークン節約にならない - トークン節約では、毎回読み込む情報量を減らすことが重要
- 長い詳細資料は、必要なときだけ読む
- 繰り返し使う作業手順はSkill化する
- 古い自作マルチエージェント環境は、知見だけを残し、標準機能へ置き換える
- 実装はモデルを指定したサブエージェントへ委任する
- 上位モデルと低コストモデルの並行運用は、Claude Code内でも構築できる
一番の収穫は、完成した環境そのものだけではありません。
環境の問題点をAIと一緒に洗い出し、構成を確認し、不要なものを判断しながら、運用方法まで整理できたことです。
今後もトークン節約に関する情報を集めながら、共通ルールやSkillを少しずつ改善していきたいと思います。