2026-07-03 追記: 実運用で見つかった抜け穴と発展形を反映しました。①Claude Code（Desktop）の worktree セッションで除外がすり抜ける問題と対策（自動生成スクリプト修正・FAQ追加）、②除外した指示ファイルをオンデマンド参照の資料として活かす運用（新節）。手元の計測では、除外したはずの28KBの指示ファイルが worktree 経由で毎セッション約10.6kトークン流入していました。
チームの AGENTS.md / CLAUDE.md が巨大で属人化していて、AIエージェントが毎回ノイズを読まされる。でもリポジトリは直せない。そういうとき、Claude Code と Codex のローカル設定だけで読み込みを抑える方法をまとめます。
はじめに
AIエージェントを使っていると、リポジトリに置かれた AGENTS.md や CLAUDE.md が重すぎて、作業しづらいと感じることがあります。
本来これらのファイルは便利です。プロジェクトの前提、ビルド手順、テスト方針、レビュー観点、禁止事項などをAIエージェントに渡せるからです。
しかし現場によっては、次のような状態になっています。
・長すぎる
・古い
・重複している
・精神論が多い
・実装に関係ない指示が大量にある
・特定人物の個人的な作法が混ざっている
・誰もメンテしていない
・AIに読ませる前提で設計されていない
この状態になると、AIエージェントはタスクに入る前から大量のコンテキストを消費します。さらに、実装に関係ない指示に引っ張られて、調査・修正・テストの判断が不安定になる可能性もあります。
この記事では、リポジトリの AGENTS.md / CLAUDE.md を直接修正できない立場でも、自分のローカル環境だけで読み込みを抑制する方法をまとめます。対象は次の2つです。
Claude Code : プロジェクト側の CLAUDE.md / rules を除外する
Codex : プロジェクト側の AGENTS.md 読み込み量を抑える
目的はチームルールを破ることではありません。セキュリティ、リリース、レビュー、秘密情報の扱いなど、業務上必須のルールは必ず守るべきです。この記事で扱うのは、AIに毎回読ませる必要のない巨大な指示ファイルを、自分の作業環境だけで抑制する方法です。
この記事の前提
扱うのは、次のような問題です。
・AIエージェントに毎回巨大な指示ファイルを読ませたくない
・トークン消費を減らしたい
・リポジトリの AGENTS.md / CLAUDE.md を直接直せない
・チームの都合で、不要な指示が押し付けられている
・自分のローカル環境だけで回避したい
一方で、次のようなルールは無視してはいけません。
・本番環境への操作禁止
・秘密情報の読み取り禁止
・認証情報の取り扱い
・レビュー必須条件
・リリース手順
・監査ログ
・顧客データの扱い
セキュリティ、コンプライアンス、本番作業の承認フローは別問題です。会社、案件、チームの規約がある場合は、必ずそれを優先してください。
なぜ AGENTS.md / CLAUDE.md が問題になるのか
AIエージェントは、リポジトリに置かれた指示ファイルを読み込んでから作業します。適切に設計された指示ファイルなら、これは便利です。
# 良い指示の例
- `src/generated/` は直接編集しない
- APIを変更した場合は `npm run test:api` を実行する
- `.env` は読まない
- DBマイグレーションを作成した場合は rollback 可能性を確認する
- 変更後に `npm run lint` を実行する
短く、具体的で、実行可能なので、AIにとって有効です。
逆に、次のような指示は扱いづらいです。
# 悪い指示の例
このプロジェクトでは常に品質を最優先し、責任感を持って実装してください。
既存の思想を深く理解し、チームの文化を尊重してください。
可読性を重視し、将来の拡張性を考慮してください。
人間にはそれっぽく見えます。しかしAIにとっては曖昧です。何を読めばいいのか、何を変更してはいけないのか、どのテストを実行すべきなのかが明確ではありません。
AIエージェントに渡すべきなのは、思想ではなく実行可能な制約です。
巨大な指示ファイルが起こす問題
AGENTS.md / CLAUDE.md が肥大化すると、次のような問題が起きます。
・開始時点でコンテキストを消費する
・毎回読む必要のない情報が混ざる
・本当に重要な指示が埋もれる
・AIの判断が不安定になる
・修正対象のコードを見る前にコンテキストを浪費する
・古い運用ルールにAIが引っ張られる
規模感を挙げると、手元の計測では 28KB の指示ファイル1本で、毎セッション約10.6kトークンを消費していました。タスクを1文字も進めていない時点での固定費です。
AIエージェントは、長い指示を渡せば強くなるわけではありません。むしろ短く、具体的で、現在のタスクに関係する情報だけを渡したほうが安定します。
Claude Code の場合
Claude Code では claudeMdExcludes を使うと、特定の CLAUDE.md や .claude/rules/** を読み込ませないようにできます。
ここで知っておきたいのは、除外パターンが「絶対パス」に対して照合される、という点です1。たとえば、次のように雑に書くのは避けたほうが安全です。
{
"claudeMdExcludes": [
"**/CLAUDE.md"
]
}
**/CLAUDE.md のように広く書くと、プロジェクト内の CLAUDE.md だけでなく、自分のグローバル設定である ~/.claude/CLAUDE.md まで除外される可能性があります。つまり、自分用の最小ルールまで消えてしまう可能性があります。
公開記事やチーム展開を考えるなら、プロジェクト側だけを狙って除外するほうが安全です。
Claude Code の実務手順
まず対象プロジェクトに移動します。
cd /absolute/path/to/your-project
次に、プロジェクト直下に .claude/settings.local.json を作成します。.claude/settings.local.json は、自分だけに効くローカル設定として使えます。チーム全体で共有する設定ではなく、自分の作業環境だけに効かせたい場合に向いています。
手作業で絶対パスを書くとミスしやすいので、現在のディレクトリを使って自動生成します。
mkdir -p .claude
python3 - <<'PY'
import json
import os
project_dir = os.getcwd()
excludes = [
f"{project_dir}/CLAUDE.md",
f"{project_dir}/CLAUDE.local.md",
f"{project_dir}/.claude/CLAUDE.md",
f"{project_dir}/.claude/rules/**",
# Claude Code（Desktop）が作る worktree セッション対策。
# worktree 内のチェックアウトは別の絶対パスになり、上の除外にマッチしない（詳細は後述）
f"{project_dir}/.claude/worktrees/*/CLAUDE.md",
]
# CLAUDE.md がシンボリックリンクなら、実体のパスも除外対象に加える（worktree 側も）
claude_md = os.path.join(project_dir, "CLAUDE.md")
if os.path.islink(claude_md):
real = os.path.realpath(claude_md)
if real not in excludes:
excludes.append(real)
real_name = os.path.basename(real)
excludes.append(f"{project_dir}/.claude/worktrees/*/{real_name}")
settings = {
"claudeMdExcludes": excludes,
"autoMemoryEnabled": False,
}
with open(".claude/settings.local.json", "w", encoding="utf-8") as f:
json.dump(settings, f, ensure_ascii=False, indent=2)
f.write("\n")
PY
生成された内容は、その場で確認します。
cat .claude/settings.local.json
たとえば、次のように出力されます。
{
"claudeMdExcludes": [
"/Users/sano/work/your-project/CLAUDE.md",
"/Users/sano/work/your-project/CLAUDE.local.md",
"/Users/sano/work/your-project/.claude/CLAUDE.md",
"/Users/sano/work/your-project/.claude/rules/**",
"/Users/sano/work/your-project/.claude/worktrees/*/CLAUDE.md"
],
"autoMemoryEnabled": false
}
これで、プロジェクト側の重い CLAUDE.md や .claude/rules/** を読み込ませにくくできます。一方で、自分の ~/.claude/CLAUDE.md は残せます。
なお、CLAUDE.md が AGENTS.md などへのシンボリックリンクになっている場合は、上のスクリプトが実体のパス（通常版と worktree 版の両方）を自動で追加します。たとえば CLAUDE.md -> AGENTS.md なら、次のようになります。
{
"claudeMdExcludes": [
"/Users/sano/work/your-project/CLAUDE.md",
"/Users/sano/work/your-project/CLAUDE.local.md",
"/Users/sano/work/your-project/.claude/CLAUDE.md",
"/Users/sano/work/your-project/.claude/rules/**",
"/Users/sano/work/your-project/.claude/worktrees/*/CLAUDE.md",
"/Users/sano/work/your-project/AGENTS.md",
"/Users/sano/work/your-project/.claude/worktrees/*/AGENTS.md"
],
"autoMemoryEnabled": false
}
この判定がないと、リンク名だけを除外しても実体ファイルが読み込まれ続けてしまうので注意してください（詳細は後述）。
管理者が配布している managed policy の CLAUDE.md は、個人設定では除外できません。組織全体で強制される設定は、個人の claudeMdExcludes より優先されます。
worktree セッションのすり抜けに注意する
claudeMdExcludes の絶対パス方式には、実運用で見つけた抜け穴が1つあります。
Claude Code（特にDesktopアプリ）は、新規セッションを .claude/worktrees/<名前>/ 内の git worktree で開くことがあります。worktree にはリポジトリのチェックアウト——つまり CLAUDE.md / AGENTS.md のコピー——が含まれ、そのパスはこうなります。
/Users/sano/work/your-project/.claude/worktrees/cranky-pascal-aab812/CLAUDE.md
これはプロジェクト直下の CLAUDE.md とは別の絶対パスなので、除外リストにマッチしません。結果、除外したはずの巨大な指示ファイルが worktree セッションでは丸ごと読み込まれます。手元の計測では、この経路で 28KB の指示ファイル≒約10.6kトークンが毎セッション流入していました。除外が効いていると思い込んでいるぶん、気づきにくい漏れ方です。
対策は、worktree 配下を glob で除外することです（上の自動生成スクリプトは対応済みです）。
"{project}/.claude/worktrees/*/CLAUDE.md",
"{project}/.claude/worktrees/*/AGENTS.md"
worktree のセッションでも、メインのプロジェクト側 settings.local.json が適用されるため、この glob を足すだけで塞がります。
.claude/settings.local.json はGit管理しない
この設定は自分のローカル環境だけで使うものなので、Gitに入れる必要はありません。
Claude Code が .claude/settings.local.json を作成した場合は自動で gitignore されますが、自分で手作成した場合は手動で除外しておくのが安全です。.git/info/exclude に入れておきます。
echo ".claude/settings.local.json" >> .git/info/exclude
.git/info/exclude は自分のローカルだけに効く除外設定です。.gitignore を変更しないので、チームに影響しません。
設定ファイルのパスがずれていないか確認する
os.getcwd() で生成しているので、別ディレクトリでスクリプトを実行していると、claudeMdExcludes のパスが対象プロジェクトとずれます。先ほど cat で見た内容について、次の点を確認しておきます。
・claudeMdExcludes のパスが、対象プロジェクトの絶対パスになっているか
・CLAUDE.md がシンボリックリンクの場合、実体ファイル（例: AGENTS.md）も入っているか
・worktrees 配下の glob（.claude/worktrees/*/...）が入っているか
・autoMemoryEnabled が false になっているか
特にパスのずれは見落としやすいので、pwd の結果と claudeMdExcludes のパスが一致しているか確認しておくと確実です。
pwd
Claude Code 側で確認する
Claude Code を起動したあと、次を実行します。
/memory
確認ポイントは次のとおりです。
・プロジェクト側の CLAUDE.md が外れているか
・プロジェクト側の .claude/rules/** が外れているか
・自分の ~/.claude/CLAUDE.md が残っているか
・不要な local memory / auto memory が混ざっていないか
必要なら /status も確認します。
/status
/memory は、読み込まれている memory / CLAUDE.md / rules の確認に向いています。/status は、設定ソースや現在のセッション状態を確認する用途に向いています。設定が想定通り効いているか確認してから使うのが安全です。
なお、/memory の一覧表示は「メモリソースの一覧」であり、必ずしも「実際にコンテキストへ読み込まれている内容」と一致しないことがあります。特に claude-mem などのプラグインを入れている環境では、表示が独自に拡張されていることがあります。実際にコンテキストへ取り込まれている量を確認したい場合は、/context でコンテキストウィンドウの内訳を見るのが確実です。
/context
/context の Memory files セクションを見ると、除外が効いていれば、自分の ~/.claude/CLAUDE.md だけが残り、プロジェクト側の CLAUDE.md は一覧から消えています。/memory の一覧にはプロジェクト側が残って見えても、/context で消えていれば、実際のコンテキストには読み込まれていないということです。除外が効いているかどうかは、/context の Memory files で判断するのが確実です。
このとき、Desktop の新規セッション（worktree で開いたセッション）でも一度 /context を確認してください。Memory files にパスに .claude/worktrees/ を含む数千〜1万トークン級のエントリが出ていたら、worktree のすり抜けが起きています。前述の glob を除外リストに足して、セッションを開き直してください。
なお、/status の Setting sources に Project local settings が出ていて、パスも一致しているのに CLAUDE.md が外れない場合は、CLAUDE.md がシンボリックリンクになっている可能性を疑ってください。
上の自動生成スクリプトを使わず手で claudeMdExcludes を書いた場合や、設定後に外れないことに気づいた場合は、CLAUDE.md がシンボリックリンクになっていないか確認してください。CLAUDE.md -> AGENTS.md のように実体が別ファイルだと、リンク名だけを除外しても実体ファイルが読み込まれ続けます。Claude Code と Codex で1つの指示ファイルを共有するために、CLAUDE.md を AGENTS.md へのシンボリックリンクにしている現場で起きやすい落とし穴です。
まず ls -la CLAUDE.md でリンクかどうかを確認します。
ls -la CLAUDE.md
# 例: CLAUDE.md -> AGENTS.md と表示されたらシンボリックリンク
リンクだった場合は、実体側のファイル名も claudeMdExcludes に加えます。
{
"claudeMdExcludes": [
"/absolute/path/to/your-project/CLAUDE.md",
"/absolute/path/to/your-project/AGENTS.md"
]
}
追加後に Claude Code を再起動すると、/memory から該当の Project memory が消えます。
元に戻す（プロジェクトの CLAUDE.md を再び有効にする）
この方法は、リポジトリ本体に手を入れない一時的な回避です。やめたくなったら、簡単に元に戻せます。
一番確実で簡単なのは、設定ファイルごと削除することです。.claude/settings.local.json は除外のために作ったファイルなので、消せば除外設定がなくなり、プロジェクトの CLAUDE.md は元どおり読み込まれます。
cd /absolute/path/to/your-project
rm .claude/settings.local.json
autoMemoryEnabled: false も一緒に消えるので、auto memory も既定（オン）に戻ります。除外も auto memory 設定もまとめて元に戻したいなら、これが一番きれいです。
除外だけ解除して autoMemoryEnabled: false は残したい場合は、claudeMdExcludes を空にします。
cd /absolute/path/to/your-project
python3 - <<'PY'
import json
with open(".claude/settings.local.json", "r", encoding="utf-8") as f:
settings = json.load(f)
settings["claudeMdExcludes"] = []
with open(".claude/settings.local.json", "w", encoding="utf-8") as f:
json.dump(settings, f, ensure_ascii=False, indent=2)
f.write("\n")
PY
特定のファイルだけ復活させたい場合（たとえば CLAUDE.md は読ませたいが .claude/rules/** は除外したまま、など）は、.claude/settings.local.json を開いて、戻したいパスの行だけ削除します。
いずれの場合も、変更後は Claude Code を完全に終了して起動し直してください。設定はセッション開始時に読まれるため、再起動しないと反映されません。再起動後に /context の Memory files を見て、プロジェクトの CLAUDE.md が一覧に戻っていれば、有効化できています。
自分用の最小 ~/.claude/CLAUDE.md を置く
プロジェクト側の巨大な CLAUDE.md を除外する代わりに、自分用の最小ルールを ~/.claude/CLAUDE.md に置いておくと、固定の方針だけは毎回効かせられます。
たとえば、これくらいで十分です。
# My minimal Claude Code rules
- Do not read repository CLAUDE.md files unless I explicitly ask.
- Inspect source code directly.
- Read only files relevant to the task.
- Before editing, identify the exact target files.
- Run only necessary tests.
- Do not change unrelated files.
- Ask before destructive operations.
指示を英語で書いているのは、コピペでそのまま使えて、短く簡潔に書けるからです。日本語にすると「リポジトリの CLAUDE.md は明示的に指示しない限り読み込まない」「ソースコードを直接確認する」「タスクに関係するファイルだけ読む」「編集前に対象ファイルを特定する」「必要なテストだけ実行する」「無関係なファイルは変更しない」「破壊的な操作は事前に確認する」といった内容です。
すでに ~/.claude/CLAUDE.md を使っている場合は、上書きせず追記してください。大事なのは短くすることです。固定ルールはこれくらいに抑え、タスク固有の条件はその都度プロンプトで渡せば足ります（共通の完成形は後述します）。
除外した指示ファイルは「参照資料」として活かす
除外は「二度と読まない」という意味ではありません。自動読み込みを切っても、AIは必要なときに Read でファイルを開けます。この違いを使うと、除外運用が一段良くなります。
チームの指示ファイルには、ノイズに混ざって事実も書かれています。コミットメッセージの規約、標準のビルドコマンド、変更してはいけない設定——こういう情報は、毎ターン読み込む価値はなくても、コミット直前の1回だけ読む価値はあります。
そこで、自分用の最小ルールに1行足しておきます。
- Team rules and build commands live in AGENTS.md. Read only the relevant section when needed.
（日本語: チーム規約とビルドコマンドは AGENTS.md にある。必要なときに該当セクションだけ読むこと）
これで、たとえば「このリポジトリのコミット規約は？」と聞くと、AIはその場で指示ファイルの該当部分だけを読んで正確に答えます。手元の運用で確認済みです。
自動読み込み → 切る（毎ターンのノイズとトークンを削減）
オンデマンド参照 → 残す（事実が必要な瞬間だけ、該当セクションを読む）
「思想は読ませない、事実は参照させる」——除外運用の完成形はこの形です。
なお、.claude/ ディレクトリ自体がチームの .gitignore に入っている現場なら、.claude/rules/** を除外リストから外して、自分専用の常時ルール置き場として転用する手もあります（Git管理外なので誰にも影響しません）。「チームの巨大ファイルは除外、自分の数行ルールは常時読み込み」という選択的な運用ができます。
Claude Code のまとめ
・プロジェクト側の CLAUDE.md / rules を狙って除外する
・~/.claude/CLAUDE.md は残す
・.claude/settings.local.json は Git 管理しない
・手作成した settings.local.json は自分で除外設定する
・CLAUDE.md がシンボリックリンクなら実体ファイル名も除外する
・worktree セッション用に .claude/worktrees/*/ 配下も glob で除外する
・除外後に /context の Memory files で確認する（worktree セッションでも）
・チーム規約などの「事実」はオンデマンド参照で活かす
最重要ポイントは、**/CLAUDE.md のような広すぎる glob は慎重に扱うことです。プロジェクト側だけ除外したいなら、対象プロジェクトの絶対パスを使って明示するほうが安全です。
Codex の場合
Codex では、AGENTS.md の読み込み量を project_doc_max_bytes で制御できます。project_doc_max_bytes は、Codex がプロジェクト指示を組み立てるときに、AGENTS.md などから読む最大バイト数を制御する設定です。デフォルトは 32 KiB で、これを超える分は静かに切り捨てられます2。
実務上は、プロジェクト側の巨大な AGENTS.md を読ませないようにし、自分用の最小ルールだけで動かすのが扱いやすいです。
ただし、Codex には AGENTS.override.md という仕組みもあります。AGENTS.override.md が存在する場合、同じ階層の AGENTS.md より優先されます。そのため、確認時は AGENTS.md だけでなく、AGENTS.override.md の有無も見る必要があります。
Codex の指示ファイル読み込み順
Codex は起動時に instruction chain を組み立てます。大まかには次の順番です。
1. グローバル側
~/.codex/AGENTS.override.md があればそれを読む。
なければ ~/.codex/AGENTS.md を読む。
2. プロジェクト側
プロジェクトルートから現在の作業ディレクトリまで順に探索する。
各ディレクトリで次の順番で確認する。
- AGENTS.override.md
- AGENTS.md
- project_doc_fallback_filenames に指定されたファイル
3. マージ順
ルート側から現在の作業ディレクトリ側へ連結される。
現在の作業ディレクトリに近い指示ほど後ろに置かれるため、実質的に優先されやすい。
つまり、プロジェクトに巨大な AGENTS.md があると、毎回それが指示として入ってくる可能性があります。また、上位ディレクトリや Codex home に AGENTS.override.md がある場合は、通常の AGENTS.md よりそちらが優先されます。
この挙動が不要なら、プロジェクト直下の .codex/config.toml で読み込み量を抑えます。
Codex の実務手順
特定のプロジェクトだけで AGENTS.md の読み込みを抑えたいので、Claude Code と同じく、対象プロジェクト直下に設定を置きます。Codex はプロジェクト直下の .codex/config.toml をプロジェクトスコープの設定として読み込みます。
まず対象プロジェクトに移動して、.codex/config.toml を作成します。
cd /absolute/path/to/your-project
mkdir -p .codex
cat > .codex/config.toml <<'EOF'
project_doc_max_bytes = 0
project_doc_fallback_filenames = []
EOF
プロジェクトスコープの .codex/config.toml は、そのプロジェクトが trusted の場合のみ読み込まれます。untrusted のプロジェクトでは、.codex/config.toml を含むプロジェクトスコープの設定はスキップされます。初回起動時に trust を確認されたら許可するか、~/.codex/config.toml に次のように明示してください。
[projects."/absolute/path/to/your-project"]
trust_level = "trusted"
project_doc_max_bytes は、プロジェクト指示として読み込む AGENTS.md の最大バイト数です。ここを 0 にすることで、プロジェクト側の巨大な AGENTS.md からプロンプトへ取り込まれる本文量を、実質的に 0 に近づけます。
ただし、これは「AGENTS.md を無効化する専用スイッチ」というより、「読み込む最大バイト数を制御する設定」です。Codex のバージョンや起動方法によって挙動が変わる可能性があるため、設定後に必ず実際の環境で確認してください。
project_doc_fallback_filenames = [] は、AGENTS.md がない場合に別名ファイルを探させないための明示的な安全策です。たとえば、次のようなファイルを勝手に指示ファイルとして扱わせたくない場合に有効です。
・TEAM_GUIDE.md
・.agents.md
・PROJECT_RULES.md
fallback filename は project_doc_fallback_filenames に明示したものだけが対象です。そのため、空配列にしておけば、AGENTS.md がない場合でも別名ファイルを探しにくくできます。
なお、すべてのプロジェクトで一律に抑えたい場合は、同じ設定をグローバルの ~/.codex/config.toml に書く方法もあります。ただしその場合は、対象でないプロジェクトの AGENTS.md まで読み込まれなくなる点に注意してください。
.codex/config.toml はGit管理しない
この設定も自分のローカル環境だけで使うものなので、.git/info/exclude に入れておきます。
echo ".codex/" >> .git/info/exclude
Codex 用の最小 ~/.codex/AGENTS.md を置く
プロジェクト側の巨大な AGENTS.md を読ませない代わりに、自分用の最小ルールを置きます。
# My minimal Codex rules
- Inspect source code directly.
- Read only files relevant to the task.
- Do not summarize repository instruction files unless explicitly requested.
- Prefer implementation facts over documentation assumptions.
- Avoid broad repository scans.
- Before editing, explain the target files.
- Do not change unrelated files.
- Run only necessary tests.
- Ask before destructive operations.
このファイルは自分のCodex環境にだけ効く最小ルールです。すでに ~/.codex/AGENTS.md を使っている場合は、上書きせず追記してください。日本語にすると「ソースコードを直接確認する」「タスクに関係するファイルだけ読む」「リポジトリの指示ファイルは明示的に指示しない限り要約しない」「ドキュメントの前提より実装の事実を優先する」「広範なリポジトリ走査はしない」「編集前に対象ファイルを説明する」「無関係なファイルは変更しない」「必要なテストだけ実行する」「破壊的な操作は事前に確認する」といった内容です。ここでも、長くしすぎないことが重要です。
~/.codex/AGENTS.md のバイト数も、project_doc_max_bytes の予算を消費します。グローバル側を大きくすると、プロジェクト側が切り捨てられる原因にもなるため、グローバルは数 KB 以内に抑えるのが無難です。
AGENTS.override.md に注意する
Codex では AGENTS.override.md がある場合、同じ階層の AGENTS.md より優先されます。たとえば、次のような構成があるとします。
~/.codex/
├── AGENTS.md
└── AGENTS.override.md
この場合、Codex はグローバル側では AGENTS.override.md を優先します。プロジェクト側でも同じです。
your-project/
├── AGENTS.md
└── AGENTS.override.md
この場合、同じディレクトリでは AGENTS.override.md が優先されます。AGENTS.override.md は同じ階層の AGENTS.md を「追記」するのではなく「置き換える」点にも注意してください。
巨大な AGENTS.md だけを見て「これが読まれているはず」と判断するのは危険です。もし想定外の指示が効いている場合は、次を確認してください。
・~/.codex/AGENTS.override.md が存在しないか
・プロジェクトルートに AGENTS.override.md が存在しないか
・作業ディレクトリに近い階層に AGENTS.override.md が存在しないか
・CODEX_HOME が想定と違っていないか
Codex 側で確認する
設定後、新しい Codex セッションを起動します。
codex --ask-for-approval never "Show which instruction files are active. Do not summarize the repository."
サブディレクトリでの読み込みも確認したい場合は、対象ディレクトリを指定します。
codex --cd services/payments --ask-for-approval never "Show which instruction files are active. Do not summarize the repository."
ログを出したい場合は次のようにします。
codex -c log_dir=./.codex-log
確認ポイントは次のとおりです。
・プロジェクトの巨大な AGENTS.md が読み込まれていないか
・プロジェクトの AGENTS.override.md が読み込まれていないか
・自分の ~/.codex/AGENTS.md が効いているか
・意図しない fallback ファイルを読んでいないか
・CODEX_HOME が想定どおりか
project_doc_max_bytes = 0 にした結果、自分の ~/.codex/AGENTS.md まで想定通り読み込まれない環境なら、最小ルールはプロンプトテンプレートとして渡す運用に切り替えてください。たとえば次の定型文を最初に付けます。
Repository instruction files may be stale or too large.
Do not summarize AGENTS.md unless explicitly requested.
Inspect source code directly.
Read only files relevant to the task.
Do not change unrelated files.
このあたりは利用しているCodexのバージョン、起動方法、CODEX_HOME、プロジェクトの trust 設定によって挙動が変わる可能性があります。必ず実際の環境で確認してください。
Codex のまとめ
・対象プロジェクト直下の .codex/config.toml に設定を置く（trusted が前提）
・project_doc_max_bytes = 0 でプロジェクト側の AGENTS.md 読み込み量を抑える
・これは無効化専用スイッチではなく、最大バイト数の制御である
・project_doc_fallback_filenames = [] で別名ファイルの探索を抑える
・全プロジェクト一律にしたいなら ~/.codex/config.toml に書く
・AGENTS.override.md は AGENTS.md より優先される
・~/.codex/AGENTS.md に自分用の最小ルールを書く
・起動後に、どの指示ファイルが有効か確認する
プロジェクトの巨大な AGENTS.md を盲目的に読ませないことが重要です。必要な情報は、コードから直接確認すれば十分な場合が多いです。
元に戻したくなったら、プロジェクト直下の .codex/config.toml を削除する（または project_doc_max_bytes を既定の 32768 などに戻す）だけです。次回起動時から、そのプロジェクトの AGENTS.md が通常どおり読み込まれます。グローバルの ~/.codex/config.toml に書いた場合は、そちらの該当行を消すとすべてのプロジェクトの挙動が元に戻ります。
cd /absolute/path/to/your-project
rm .codex/config.toml
AIエージェントに渡すべき指示とは何か
AIエージェントに渡すべき指示は、短く、具体的で、実行可能なものです。
# 良いAI向け指示
- `.env` は読まない
- `src/generated/` は直接編集しない
- API変更後は `npm run test:api` を実行する
- UI変更後はスクリーンショット差分を確認する
- 破壊的な操作は事前に確認する
逆に、次のような指示はノイズになりやすいです。
# 悪いAI向け指示
- 品質を大切にする
- 責任感を持つ
- チーム文化を理解する
- 将来性を考慮する
- 既存思想を尊重する
人間のマネジメント文脈では意味があるかもしれません。しかしAIエージェントへの指示としては弱いです。AIに必要なのは、抽象的な思想ではなく実行可能な条件です。
現場で起きがちな属人化
AIエージェント運用が未成熟な現場では、AGENTS.md や CLAUDE.md が「チームの共通知」ではなく、「特定人物の作法をAIに押し付ける場所」になりがちです。
これは危険です。AIエージェントが、それをプロジェクトの正規ルールとして扱ってしまうからです。
本来、AI向け指示ファイルに書くべきなのは、こういう情報です。
・現在も有効なビルド手順
・現在も有効なテスト手順
・編集禁止ファイル
・秘密情報の扱い
・レビュー前に必要な確認
・プロジェクト固有の制約
逆に、次のようなものは向きません。
・古い開発思想
・長すぎる背景説明
・特定人物の好み
・誰も守っていない作法
・タスクと無関係な運用メモ
・曖昧な精神論
AIエージェントに大量のノイズを読ませても、性能は上がりません。むしろ重要な情報が埋もれます。
リポジトリを直せない場合は、自分の環境を守る
理想は、チームで AGENTS.md / CLAUDE.md を整理することです。しかし現実には難しいことがあります。
・開発リーダーがAIエージェントの特性を理解していない
・長文指示を書けばAIが賢くなると思っている
・一度書いたルールが更新されない
・現場メンバーが改善提案しづらい
・指示ファイルが属人化している
この場合、正面から直そうとしても時間がかかります。なので、まずは自分のローカル環境だけ守るのが現実的です。
この記事の方法なら、リポジトリ本体を変更せずに回避できます。Claude Code なら、プロジェクトの CLAUDE.md や .claude/rules/** を除外する。Codex なら、プロジェクトの AGENTS.md 読み込み量を project_doc_max_bytes = 0 で抑える。これだけでも、毎回のコンテキスト消費とノイズを減らせます。
最小ルールの完成形
Claude Code でも Codex でも、基本思想は同じです。自分用の最小ルールはこれくらいで十分です。
# Minimal agent rules
- Inspect source code directly.
- Read only files relevant to the task.
- Do not scan the entire repository unless necessary.
- Do not summarize repository instruction files unless explicitly requested.
- Team rules and build commands live in repository instruction files. Read only the relevant section when needed.
- Do not edit unrelated files.
- Explain target files before editing.
- Run focused tests when possible.
- Ask before destructive operations.
日本語にすると次のような内容です。
# 最小のエージェント向けルール（日本語版）
- ソースコードを直接確認する
- タスクに関係するファイルだけ読む
- 必要がない限りリポジトリ全体を走査しない
- リポジトリの指示ファイルは、明示的に指示しない限り要約しない
- チーム規約とビルドコマンドはリポジトリの指示ファイルにある。必要なときに該当セクションだけ読む
- 無関係なファイルは編集しない
- 編集前に対象ファイルを説明する
- 可能なら絞り込んだテストを実行する
- 破壊的な操作は事前に確認する
固定指示は短くする。タスク固有の条件は、その都度プロンプトで渡す。このほうがAIエージェントは安定します。
よくある疑問
AGENTS.md / CLAUDE.md は全部不要なのか
不要ではありません。適切に書かれていれば有効です。問題は、長すぎる、古い、曖昧、重複している、タスクに関係ない、という状態です。AI向け指示ファイルは、短く、具体的で、現在も有効なものに絞るべきです。
チームルール違反にならないのか
セキュリティ、リリース、レビュー、秘密情報の扱いなど、業務上必須のルールは守るべきです。一方で、AIに毎回読ませる必要のない巨大な指示ファイルを自分のローカル環境で抑制することは、作業環境の最適化です。ただし、会社や案件の規約がある場合はそれを優先してください。
設定したのに CLAUDE.md が外れないのはなぜか
/status の Setting sources に Project local settings が出ていて、パスも一致しているのに外れない場合は、CLAUDE.md がシンボリックリンクになっていないか確認してください。CLAUDE.md -> AGENTS.md のように実体が別ファイルだと、リンク名だけを除外しても実体側が読み込まれ続けます。ls -la CLAUDE.md で確認し、リンクなら実体のファイル名（この例では AGENTS.md）も claudeMdExcludes に加えてください。
worktree のセッションで CLAUDE.md が復活するのはなぜか
Claude Code（特にDesktop）は、新規セッションを .claude/worktrees/<名前>/ 内の worktree で開くことがあります。worktree にはリポジトリのチェックアウト（CLAUDE.md / AGENTS.md のコピー）が含まれ、除外リストの絶対パスとは別のパスになるため、除外がすり抜けます。手元の計測では、この経路で28KBの指示ファイル≒約10.6kトークンが毎セッション流入していました。対策は worktree 配下の glob 除外です（本文の自動生成スクリプトは対応済み）。
"{project}/.claude/worktrees/*/CLAUDE.md",
"{project}/.claude/worktrees/*/AGENTS.md"
**/CLAUDE.md ではダメなのか
避けたほうが安全です。**/CLAUDE.md は広すぎて、自分の ~/.claude/CLAUDE.md まで除外される可能性があります。プロジェクト側だけ除外したいなら、対象プロジェクトの絶対パスを指定するほうが安全です。
project_doc_max_bytes = 0 は必ず効くのか
project_doc_max_bytes は、AGENTS.md から読み込む最大バイト数を制御する設定です。「AGENTS.md を完全に無効化する専用スイッチ」としてではなく、最大バイト数の制御として理解したほうが安全です。実際にどのファイルが読み込まれているかは、Codexのバージョンや起動方法によって確認したほうが安全です。設定後は次のような確認をしてください。
codex --ask-for-approval never "Show which instruction files are active. Do not summarize the repository."
AGENTS.override.md は確認すべきか
確認すべきです。Codex では、AGENTS.override.md がある場合、同じ階層の AGENTS.md より優先されます。想定外の指示が効いている場合は、AGENTS.md だけでなく、AGENTS.override.md も確認してください。
fallback filenames とは何か
project_doc_fallback_filenames に指定したファイル名を、AGENTS.md がない場合の代替指示ファイルとして扱う仕組みです。たとえば次のように指定できます。
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
この場合、Codex は各ディレクトリで次の順番で確認します。
1. AGENTS.override.md
2. AGENTS.md
3. TEAM_GUIDE.md
4. .agents.md
別名ファイルを指示として扱わせたくない場合は、空配列にしておくと意図が明確になります。
project_doc_fallback_filenames = []
まとめ
AGENTS.md / CLAUDE.md は便利です。しかし設計が悪いとAIエージェントの判断を不安定にします。特に、リポジトリに置かれた巨大な指示ファイルを毎回読ませる運用は、コンテキスト効率が悪く、重要な情報も埋もれやすいです。
リポジトリを直接直せない場合でも、自分のローカル環境だけで回避できます。
Claude Code の場合は、プロジェクトの CLAUDE.md や .claude/rules/** を除外します（worktree 配下も忘れずに）。
{
"claudeMdExcludes": [
"/absolute/path/to/your-project/CLAUDE.md",
"/absolute/path/to/your-project/CLAUDE.local.md",
"/absolute/path/to/your-project/.claude/CLAUDE.md",
"/absolute/path/to/your-project/.claude/rules/**",
"/absolute/path/to/your-project/.claude/worktrees/*/CLAUDE.md",
"/absolute/path/to/your-project/.claude/worktrees/*/AGENTS.md"
],
"autoMemoryEnabled": false
}
Codex の場合は、プロジェクトの AGENTS.md 読み込み量を抑えます。
project_doc_max_bytes = 0
project_doc_fallback_filenames = []
ただし、Codex では AGENTS.override.md が AGENTS.md より優先されるため、確認時は AGENTS.override.md の有無も見てください。
AIエージェントに必要なのは、長い思想ではありません。短く、具体的で、実行可能な指示です。そして、除外した指示ファイルの中の「事実」は、オンデマンド参照で活かせます。
もし現場の AGENTS.md / CLAUDE.md が巨大化し、属人化し、誰も直せない状態になっているなら、まずは自分のローカル環境だけでも守るのが現実的です。不要な指示を大量に読ませるより、必要なコードを直接見せる。そのほうが、AIエージェントは安定して動きます。
このシリーズの歩き方
Claude Code実務運用シリーズ ― 暴走させない、から仕組みにするまで。
- ◀ 前の記事: AGENTS.md / CLAUDE.md が100行を大幅に超えたら危険。チームに無視されないAI指示ファイルの分け方
- ▶ 次の記事: andrej-karpathy-skillsのCLAUDE.mdに足したい、Claude Codeの安全運用ルール3選
- 🔍 あわせて読む: Claude Codeの「重い・忘れる」を防ぐ：7万スター超のclaude-memと98%削減のcontext-modeを比較 ― 「重い」の根本対策
- 🗺 シリーズ全記事の地図(親記事)