AGENTS.mdはどこに置く？上位・下位の関係、読み込み順、文章量をやさしく図解

AGENTS.mdが大事らしいから、見よう見まねで作ってみた。
ところが実際に使い始めると、「どこへ置けばよいのか」「全作業の共通ルールと案件固有のルールでは、どちらが優先されるのか」「どれくらい書けばよいのか」で迷い始めます。

読み終えた時に、自分で決められる4つのこと

整理できるのは、次の4つです。

1. 新しいルールを、自分がCodexで行う全作業・1つのObsidian Vault全体・特定の案件フォルダのどこへ置くか。
2. 広い範囲に届くAGENTS.mdと、案件フォルダのAGENTS.mdへ、何を書き分けるか。
3. 長くなった説明を、どの種類のファイルへ分けるか。
4. 「書いたのに伝わらない」時、文章を増やす前に何を確認するか。

AGENTS.mdの置き場所は、まず「追加したいルールを、どの作業で使うのか」で考えると迷いません。

全作業の共通ルールはCodex設定へ、案件固有のルールは案件フォルダへ

AGENTS.mdは、AIに「このフォルダ内の作業で守る前提」を伝えるファイルです。
中身は、見出しや箇条書きを書けるMarkdownという形式のテキストです。
AGENTS.mdだけでなく、Skillや正式な参照元も含めて、情報の置き場所を次の6種類に分けます。

~は、パソコン内で各自のファイルが入るホームフォルダを短く表す記号です。
Business-Vaultは、仕事用のObsidian Vaultを表す架空のフォルダ名です。

「Vaultを開いた直後の階層」とは、Business-Vaultフォルダの中に、Clientsなどの分類フォルダが並んでいる場所です。

1文で覚えるなら、Codexで行う全作業の共通ルールは ~/.codex/AGENTS.md、Vault全体の案内は Vault名/AGENTS.md、A社案件だけの決まりは A社/AGENTS.md、繰り返す手順はSkill、最新の事実は正式な参照元へ置きます。

「正式な参照元」とは、同じ事実を何か所にもコピーせず、1か所だけを最新版として管理するファイルです。
最新版を管理する1か所が「正本」です。

AGENTS.mdは、会社の案内板と同じです

AGENTS.mdの関係は、会社の案内板にたとえると分かりやすくなります。

会社の入口には、全員が守る案内があります。
「来客情報を外へ出さない」「退館前に施錠する」といった全社共通のルールです。

営業フロアへ行くと、営業だけの案内があります。
「見積もりは所定の台帳を確認する」といった、営業フロアで必要なルールです。

A社の会議室へ入ると、A社だけの案内があります。
「A社への納品メールだけは英語で作る」といった、さらに狭く具体的なルールです。

会議室へ入ったからといって、会社の入口にあった守秘ルールが消えるわけではありません。
入口の共通ルールに、営業フロアのルールとA社の個別ルールが重なります。
同じ話題で内容が食い違った時だけ、現在いる部署や会議室の案内が、全社ルールに対する具体的な例外になります。

AGENTS.mdも同じです。
ここから使う「上位」とは、Codexの個人設定やVault全体のように、広い範囲に届くルールです。
「下位」とは、A社フォルダなど、実際の作業ファイルに近い狭い範囲のルールです。
画面の上下やルールの偉さを表す言葉ではありません。

上位のAGENTS.mdには、広い範囲で共通するルールを書きます。
下位のAGENTS.mdには、案件・記事・機能のフォルダで初めて必要になる差分だけを足します。

Codexの個人設定
「外部へ送る前に本人へ確認する」

仕事用Vault全体
「顧客情報は公開原稿へ含めない」

顧客フォルダ全体
「最新の案件サマリーを事実の参照元にする」

A社フォルダ
「A社への納品メールは英語で作る」

Codexの個人設定から仕事用Vault、顧客フォルダ、A社フォルダへと進んでも、上位の文章を丸ごとコピーするわけではありません。
A社フォルダのAGENTS.mdには、A社で初めて必要になる具体的な差分だけを書きます。

「この案内はどこまで届くか」を、適用範囲と呼びます

会社の入口の案内は建物全体に届き、A社会議室の案内はA社会議室だけに届きます。
この「どこまで届くルールか」を、日本語では適用範囲と呼びます。
英語でこの適用範囲をscope（スコープ）と表します。

また、特定のフォルダとその配下だけに届くよう置いたAGENTS.mdを、scoped AGENTS.mdと呼ぶことがあります。
これは「scoped」という特別な形式のファイルではありません。
普通のAGENTS.mdを、顧客フォルダや記事フォルダの中へ置いた時の呼び名です。

難しく覚える必要はありません。
scoped AGENTS.mdとは、特定のフォルダと配下だけの案内板です。

1つの提案書を、上から下まで追ってみる

次のような構造を考えてみてください。
フォルダの親子関係を進むほど、ルールの適用範囲が、Codexの全作業から仕事用Vault、顧客業務、A社案件へと狭くなる例です。

ホームフォルダ
├─ .codex/
│  └─ AGENTS.md                 ← Codexで扱う全作業の運用ルール
└─ Documents/
   ├─ Business-Vault/
   │  ├─ AGENTS.md              ← このVault全体のルール
   │  └─ Clients/
   │     ├─ AGENTS.md           ← 顧客案件共通のルール
   │     └─ A社/
   │        ├─ AGENTS.md        ← A社案件だけのルール
   │        └─ proposal/
   │           └─ draft.md      ← 今回作っている提案書
   └─ Personal-Vault/
      └─ AGENTS.md              ← 個人Vaultだけの別ルール

ここでは、A社の提案書を作る仕事を始めたとします。
Codexは、今回の仕事へつながる道の途中にある案内を上から順に重ねます。
Codexの個人設定、Business-Vault全体、顧客業務、A社案件のルール、という順番です。

この構成では、A社フォルダ内のAGENTS.mdに書いたルールは、Business-Vault全体のルールよりも適用範囲が狭く、内容が具体的です。
上位に「文書は日本語」とあり、A社のAGENTS.mdに「A社への納品メールだけは英語」とあれば、A社への納品メールに限って後者が具体的な例外になります。

「深い階層が強い」と覚えるより、「作業ファイルに近い階層ほど、案件や機能の例外を具体的に書ける」と覚える方が正確です。
上位のルールと矛盾しない内容は、深いAGENTS.mdがあっても消えません。
AGENTS.md同士に矛盾を書いた場合は、作業場所に近い方が具体的な例外として採用されることがあります。
一方で、製品や実行環境の側で決められた上位の制約は、深いAGENTS.mdでも解除できません。
ただし、フォルダの近さによる優先と、製品や実行環境が持つ命令の優先順位は別物です。

上位と下位には、何をどれくらい書けばよいのか

実際の置き場所では、AGENTS.mdは大きく3段に分かれます。

上位ほど抽象的で、広い仕事に共通します。
下位ほど具体的で、使う場面が限られます。
これは「上が弱く、下が強い」という力関係ではなく、広い共通ルールに、狭い仕事の具体性を足す関係です。

文章量にも、製品公式の理想行数はありません。
ただし、初めて作る時の運用上の出発点として、次の範囲に収まるかを見ると整理しやすくなります。
この数字へ合わせるために、大切なルールを無理に削る必要はありません。
迷った時に中身を見直すための「黄色信号」だと考えてください。

この行数はCodexの仕様でも合格基準でもなく、整理を始めるための目安です。
読みやすさと役割分担を見る目安であり、技術上の32KiBという容量制限とは別です。
1行が極端に長ければ、行数が少なくても情報量は増えます。
大切なのは、上位を最小限にし、最上部を地図にし、下位には差分だけを書くという相対関係です。

たとえば、300行ある最上部のAGENTS.mdを、機械的に3分割しても整理にはなりません。
全ての作業で必要な原則だけをCodexの個人設定へ残し、Vaultの入口だけを最上部へ置き、顧客固有の事情を顧客フォルダへ移し、毎回行う工程をSkillへ分けます。
この整理により、今回の仕事に関係する情報だけが届きやすくなります。

そのまま使える、3段階のAGENTS.md目次例

AGENTS.mdを軽く保つコツは、本文を全部詰め込まず、次に読むべき正本やSkillへ案内することです。
同じ「目次」でも、置く場所ごとに役割を変えます。

例1：Codexの個人設定にあるAGENTS.mdは、最小限にする

# Codexで扱う全作業の共通ルール

## 常に守ること
- 返答は日本語にする。
- 外部送信、公開、課金は本人の明示依頼なしに実行しない。
- 不明な固有名詞は既存の正本を確認する。

## 作業場所の優先
- プロジェクト内のAGENTS.mdとSkillを確認する。
- 個人情報や認証情報は、必要な時だけ最小範囲で扱う。

Codexの個人設定には、どのVaultやリポジトリでも変わらない安全原則と応答方針だけを置きます。
特定顧客名、記事の文体、開発コマンド、過去の議論はここへ入れません。

例2：Vault最上部のAGENTS.mdは、総合案内所にする

# Business-Vaultの入口

## このVaultの境界
- 顧客情報は外部公開しない。
- 削除は物理削除ではなく、所定の保管場所へ退避する。

## 仕事別の入口
- 記事制作: `.agents/skills/article-writing/SKILL.md`
- 顧客案件: `Clients/AGENTS.md` → 対象顧客の台帳
- 開発: `Development/AGENTS.md` → 対象リポジトリのREADME

## このVaultの正本
- 言葉づかい: `Core/writing-guide.md`
- 事業の数字: `Core/kpi-ledger.md`

Vaultの最上部には、Vault内で守ることと、仕事の種類ごとに参照するSkill・資料を書きます。
これは「総合案内所」です。
細かな記事手順や全顧客の例外をここへ複製しないことで、容量上限も圧迫しにくくなります。
OpenAIの実運用記事には、最上部のAGENTS.mdを約100行の目次として保った事例があります。
ただし100行は製品仕様の上限ではなく、そのチームが採用した設計例です。

例3：案件フォルダのAGENTS.mdは、案件固有の差分を書く

# A社案件の作業ルール

## この案件だけの前提
- 顧客名を公開原稿へ書かない。
- 納品メールは英語で作成する。

## 作業の入口
- 商談記録: `meeting-digest` Skillを読む。
- 最新の決定事項: `project-summary.md`を正本にする。
- 提案書: `proposal/README.md`の構成に従う。

案件・記事・機能のフォルダにあるAGENTS.mdには、当該フォルダ内でしか意味を持たない例外、参照先、完了条件を置きます。
技術資料では、これをscoped AGENTS.mdと呼びます。
上位の全文をコピーする場所ではありません。
顧客案件の中でも提案書だけに固有の指示があるなら、proposal/AGENTS.mdへさらに絞れます。

この3つの置き分けができると、普段の運用は始められます。
次に確認するのは、正しい場所へ置いたルールを、Codexがどの経路で探すかです。

どのルールを読むかは、作業を始めたフォルダで決まります

重要なのは、Codexがパソコン内にある全てのAGENTS.mdを毎回探して読むわけではないことです。

新しいタスクを始める時、Codexには「今回はこのフォルダを中心に仕事をする」という開始場所があります。
これが作業開始フォルダです。

たとえば、仕事用Vaultを開いて新しいタスクを始めれば、そのVaultが作業の起点になります。
開発リポジトリを開いて始めれば、その開発プロジェクトが起点になります。
パソコンのファイル管理アプリでたまたま表示しているフォルダではなく、Codex側で今回の仕事の中心として開いた場所です。

まず、開発プロジェクトの最上部を見つける

Gitで管理された開発プロジェクトでは、通常は.gitを基準に、リポジトリの最上部が見つかります。

開発プロジェクトの最上部       ← Gitで管理された範囲の起点
├─ AGENTS.md
├─ app/
│  ├─ AGENTS.md
│  └─ checkout/
│     └─ page.tsx              ← 今回の作業開始フォルダがこの付近
└─ tests/

この場合、Codexはプロジェクトの最上部から作業開始フォルダまで、道の途中にあるAGENTS.mdを順番に確認します。
パソコン内を無制限にさかのぼるわけでも、兄弟フォルダにある無関係なAGENTS.mdまで集めるわけでもありません。

Gitで管理されていないObsidian Vaultでも、AGENTS.mdは使えます。
ただしCodexがプロジェクトの最上部を判定できない時は、プロジェクト側で自動確認する場所が作業開始フォルダだけになる場合があります。
そのため、Vault全体のAGENTS.mdを確実に使いたい時は、Vault名のフォルダ自体を中心フォルダにして、新しいタスクを始めるのが分かりやすい運用です。
つまり、「Vaultのルールは不安定」という話ではなく、Vault名のフォルダをCodexの中心にして新しいタスクを始めるという実務上の話です。

ルールの組み合わせは、基本的にタスク開始時に決まる

Codexは、ファイルを1つ開くたびに全てのAGENTS.mdを探し直すわけではありません。
基本は、新しいタスクを始めた時の作業開始フォルダを基準に、使う指示の組み合わせを作ります。

ターミナルの中で途中からcdという命令を使って別フォルダへ移動しても、タスク開始時にCodexが読み込んだAGENTS.mdの組み合わせが、自動で最初から作り直されるとは限りません。
別Vaultへ仕事を移す時や、AGENTS.mdの配置を変えた後は、目的のフォルダを中心に新しいタスクを始めて確認する方が安全です。

設定を調整する場合に知っておく探索順

普段の運用は、目的のVaultや開発プロジェクトを中心にしてタスクを始めれば十分です。
標準の設定を確認・変更する場合だけ、CODEX_HOMEとfallbackという2つの用語が必要になります。
CODEX_HOMEはCodexの個人設定を置くフォルダで、通常はホームフォルダ内の.codexです。
fallbackは、AGENTS.mdがない時だけ代わりに探すよう登録した予備のファイル名です。

最初に、Codexの個人設定にある入口を確認
$CODEX_HOME/AGENTS.override.md
  なければ $CODEX_HOME/AGENTS.md
  → 最初の空でない1ファイル

次に、プロジェクトの最上部から作業開始フォルダまで確認
各フォルダで AGENTS.override.md
  なければ AGENTS.md
  なければ登録済みの予備ファイル名
  → 各フォルダで最大1ファイル

最後に、広い適用範囲から作業開始フォルダに近い範囲へ順番に組み合わせる
Codexの個人設定 → プロジェクト最上部 → 作業開始フォルダに近いフォルダ

AGENTS.mdの読み込み順と、Codexに許可された操作は別です

AGENTS.mdの読み込み順は、複数のAGENTS.mdがある時に、どのルールを組み合わせるかを決めます。
一方、操作の権限は、ファイルの読み書き、外部送信、公開などをCodexが実行できるかを決めます。

この2つは、分けて考えると混乱しません。

AGENTS.md同士の組み合わせ
Codexの個人設定 → プロジェクト全体 → 作業開始フォルダに近い個別ルール

Codexが実行できる操作
製品・組織・実行環境の設定で決まる

実際の作業ファイルに近いフォルダのAGENTS.mdには、案件や機能に固有の事情を詳しく書けます。
しかし、AGENTS.mdへ「外部公開してよい」と書いても、実行環境に公開権限がなければ実行できるようにはなりません。
AGENTS.mdは作業方針を伝えるファイルであり、新しいOS権限や課金権限を与えるファイルではありません。

応用。いまだけ同じ場所の通常ルールを差し替える方法

Codexには、同じフォルダの通常ルールを特別な案内へ差し替えるAGENTS.override.mdがあります。
会社の例でいえば、「いつもの案内板」ではなく「本日の特別案内板」を同じ場所に掲げる仕組みです。
同じディレクトリに両方がある場合、順番はAGENTS.override.mdを先に探し、存在して内容があればその階層のAGENTS.mdは読まれません。
2つを連結する仕組みではありません。

同じフォルダ
├─ AGENTS.override.md が存在して内容あり → これを採用する
├─ AGENTS.override.md がない、または空 → AGENTS.md を採用する
└─ AGENTS.mdもない、または空 → 設定済みの予備ファイル名を順に確認する

この「置き換え」は、その階層にある通常のAGENTS.mdとの関係だけを指します。
親フォルダで採用済みのAGENTS.md、より深いフォルダのAGENTS.md、system、developer、userの指示、実行権限などを一括で無効化する意味ではありません。
一時的な実験、隔離した作業、明確な切替が必要な時には便利です。
日常運用で多用すると「なぜこのルールが読まれなかったか」を追いにくくなるため、常設の通常ルールにはAGENTS.mdを使う方が保守しやすいでしょう。

ObsidianのVaultが2つあるなら、別の建物として考える

ObsidianのVaultは、同じパソコン内に置ける独立した知識庫です。
仕事用Vaultと個人用Vaultがあるなら、2つの別の建物だと考えてください。

ここで、ObsidianのVaultとCodexのprojectは別の言葉です。
VaultはObsidianで管理する知識庫の単位で、projectはCodexが1つの作業場所として扱う単位です。
1つのVaultを1つのCodexプロジェクトとして開けば両者は重なりますが、言葉そのものが同じ意味なのではありません。

Vaultを2つに分けても、片方の最上部にあるAGENTS.mdが、もう片方へ自動で流れ込むわけではありません。
どちらを今回の中心としてタスクを始めたかと、フォルダの親子関係が適用範囲を決めます。

Documents/
├─ Business-Vault/
│  ├─ AGENTS.md                 ← 法人案件、機密、納品のルール
│  └─ Clients/
│     └─ AGENTS.md              ← 顧客フォルダ共通のルール
└─ Personal-Vault/
   ├─ AGENTS.md                 ← 日記、学習、公開前確認のルール
   └─ Content/
      └─ AGENTS.md              ← 記事制作だけのルール

両Vaultで守る「返答は日本語」「外部送信は確認する」といったルールだけを、Codexの個人設定に置きます。
法人の守秘、個人日記の扱い、記事の公開手順のような領域固有ルールは、それぞれのVaultのルートへ置きます。
特定の顧客、講座、リポジトリだけのルールは、対象の顧客・講座・リポジトリのフォルダ内へ置きます。

4つの言葉を整理すると、次のようになります。

Codexの1つのプロジェクトへ、複数のフォルダを見せることもできます。
1つのCodex projectに複数フォルダを追加した場合は、中心として指定したフォルダと、追加で参照できるフォルダの役割が違います。

中心のフォルダを正式にはprimary folderと呼びます。
これは「今回の本館」です。
本館にあるAGENTS.md、Skill、設定は自動発見の対象になります。

追加で見せたフォルダはsecondary folderと呼びます。
これは「資料を取りに行ける別館」です。
検索や読み書きはできても、通常は別館にあるAGENTS.mdやSkillを自動発見する起点にはなりません。

「複数Vaultを見せているから、全部のルールが混ざる」と考えないことが大切です。
自動適用を期待するVaultは中心フォルダとして開きます。
別Vaultのノートは、ファイルパスや検索対象を指定して、必要な資料として参照する設計が分かりやすいです。

2つのVaultで目的が大きく違うなら、Codex側のプロジェクトも分ける方が単純です。
仕事用Vaultでは顧客情報と納品ルール、個人用Vaultでは日記と学習ルール、というように、建物ごとの案内が混ざりにくくなります。

たとえば仕事用Vaultを中心にし、個人用Vaultを追加資料として見せた場合、個人用Vaultのメモを読むことはできます。
ただし個人用Vault側のAGENTS.mdまで自動適用したいなら、個人用Vaultを中心にした別タスクを始めます。

似て見える5つの資料は、役割が違います

同じMarkdownや設定ファイルでも、役割を混ぜるとAIも人も迷います。
ファイル名ではなく、「何を決める情報か」で置き場所を選びましょう。

会社の例を続けるなら、AGENTS.mdは案内板、Skillは作業レシピ、READMEは初めて来た人向けの館内案内、正本は最新の契約書や台帳です。
そして.codex/agentsは、仕事を子エージェントへ分担する時の役割設定です。

AGENTS.mdは、詳細手順を全て書く台帳ではありません。
「記事制作ではこのSkillを読む」「顧客案件ではこの台帳を正本にする」という地図として使うと、軽くて壊れにくくなります。
この考え方は、AIに読ませるmdファイルの役割整理で扱った役割分担の続きでもあります。

READMEだけに禁止事項を書いても、必ず読まれる保証はありません。
安全ルールはAGENTS.mdへ、背景説明はREADMEへ、反復手順はSkillへ、事実は正本へ置くと、二重管理を減らせます。

繰り返す仕事は、手順書としてSkillへ分ける

Skillは、繰り返し行う仕事の手順をまとめたものです。
AGENTS.mdが「どの案内へ進むかを示す地図」なら、Skillは「記事制作や商談整理などの作業を、どう進めるかを書いたレシピ」です。
記事作成、商談整理、画像制作のように、毎回ほぼ同じ工程と検品を行う仕事に向いています。

Skillがあるだけで、どんな言い方の依頼にも必ず自動で使われるわけではありません。
使われ方には、明示指定と自動選択の2つがあります。

Codexではユーザーが$skill-nameのように名前を指定して、明示的にSkillを使えます。
これは「今回はこの手順で進める」という最も確実な合図です。
Codex CLIやIDEでは$skill-nameや/skills、ChatGPTでは利用できるSkillを@から選ぶ方法があります。

同時に、Skillの名前と説明文が依頼内容に明確に合う時は、Codexが自動で選ぶこともあります。
この自動選択を、技術的には「暗黙の呼び出し」と呼びます。
この暗黙の呼び出しはallow_implicit_invocationで制御でき、標準では有効です。
必要ならSkill内のagents/openai.yamlでfalseにし、明示起動専用にもできます。
ただし、自然言語の依頼には曖昧さがあるため、Skillが存在するだけで全ての表現に必ず反応すると考えるのは危険です。

たとえば「記事を整えて」は、誤字修正、SEO改善、公開準備、SNS転用のどれを意味するかで使うSkillが変わります。
重要な仕事や固有の工程がある仕事では、ユーザーがSkill名を明示するか、AGENTS.mdに「この種類の依頼ではこのSkillを読む」と短くルーティングしておくと確実性が上がります。

Skillの一覧へ最初から載るのは、原則として名前、説明、パスなどの要約です。
Codexには、Skillの初期一覧に使う説明文の上限があります。
モデルが1度に扱える情報量を「コンテキスト」と呼び、最大2%、またはコンテキスト量が不明な時は8,000文字がSkill一覧に使われます。
Skillが多い場合は、まず説明文が短縮され、それでも収まらなければ一部のSkillが初期一覧から省略され、警告が出ます。
省略されたSkillの全文が途中まで入る、という意味ではありません。
CodexがSkillを選んだ後に読む完全なSKILL.mdは、この初期一覧の予算とは別です。

これは、プロジェクト指示の容量上限とも別の予算です。
Skill本体を読む量、会話全体の情報量、ツール結果の量とも別物です。
Skillの初期一覧で用途が伝わるよう、Skillの説明文は短くし、詳細な工程はSKILL.md本文へ置くのが向いています。

Skillを増やせばAGENTS.mdの肥大化が自動で解決するわけではありません。
毎回同じ品質確認をする仕事だけをSkillにし、一度きりの顧客固有情報は対象フォルダの正本へ置きましょう。

.codex/agentsは、AGENTS.mdの置き場所ではありません

.codex/agents/は、仕事を子エージェントへ分担する時の役割設定を置くフォルダです。
AGENTS.mdの読み込み階層に追加するフォルダではありません。

.codexはCodexの設定用フォルダです。
先頭のドットは、一部のOSで通常は表示しない設定用フォルダに使われる名前の慣習です。
画面に見えない場合は、パソコンのファイル管理アプリで「隠しファイルを表示」に相当する設定を使います。
隠しフォルダであっても、秘密情報が入っているとは限りません。

.codex/agents/に置くTOMLファイルは、特定プロジェクトで使うcustom agent、つまり子エージェントの役割設定です。
TOMLは、名前やモデルなどの設定項目を書くファイル形式です。

.codex/agents.mdという1つのMarkdownファイルではなく、.codex/agents/というディレクトリです。
たとえば「調査だけを行う役」「実装を担当する役」「確認済みのUI操作だけを行う役」を分ける時に使います。
全プロジェクトで使うcustom agentは~/.codex/agents/に、特定プロジェクトだけのcustom agentはプロジェクト内の.codex/agents/に置きます。

このフォルダやTOMLは、Codexが勝手に必ず作る標準ファイルではありません。
誰かが設定として作成したものであり、存在しなくても通常のCodex利用は可能です。
.codex/agents/内のTOMLは「誰へどの役割を委任するか」の設定で、AGENTS.mdは「現在の作業場所で何を守るか」の指示です。

custom agentのTOMLに権限希望が書かれていても、実際に許される操作は実行環境とユーザー承認で決まります。
AGENTS.mdやTOMLが、それ自体で権限を付与することはありません。

応用。1つの正本を、Codexの標準入口から参照する

Codexがグローバル指示として標準で探索する場所は、~/.codex/AGENTS.mdです。
~/.agents/AGENTS.mdは、そのままではCodexの標準自動検出場所ではありません。

それでも~/.agents/AGENTS.mdを人間が管理する正本にすることはできます。
そのために使えるのが「シンボリックリンク」です。
これは、1つの実体ファイルを別の場所から参照するための、パソコンのOSに備わったリンクの仕組みです。

~/.codex/AGENTS.mdを~/.agents/AGENTS.mdへ向けるシンボリックリンクにすれば、Codexは標準の入口から読み、人間は1つの実体ファイルだけを編集できます。
これは「置き場所を偽る」方法ではなく、入口と正本を分けるためのOS標準の仕組みです。

Codexが探す入口: ~/.codex/AGENTS.md
                    ↓ シンボリックリンク
人間が編集する正本: ~/.agents/AGENTS.md

この設計の利点は、複数のAIツールに同じ全文を複製せず、正本を1つに保てることです。
ただしリンク先を移動または削除すると入口が壊れます。
設定を変えた後は、リンク先の存在と、実際にCodexが新しい内容を読むことを確認しましょう。

ルールを詰め込みすぎると、下の具体的な指示が届かなくなります

KiBはキビバイトと読みます。
1KiBは1,024バイトです。
したがって32KiBは32×1,024で、32,768バイトです。

バイトは、ファイルのデータ量を数える単位です。
文字数とは同じではありません。
特に日本語は、1文字を表すために複数バイトを使うことが多いため、32KiBを「約32,000文字」と考えるのは誤りです。

Codexの標準設定では、プロジェクト指示の連なりに使える合計量に32KiBの上限があります。
設定名はproject_doc_max_bytesで、既定値は32,768です。
これは1つのAGENTS.mdだけの上限ではなく、プロジェクト側で発見されたAGENTS.mdやoverrideの連なりの合計予算です。
Codexの個人設定にある指示、Skillの初期一覧、SKILL.md本文、会話全体の情報量とは別の予算です。

上位のAGENTS.mdが予算を使い切ると、その後に見つかる深いフォルダの指示が読み込み対象から外れる可能性があります。
つまり、最も具体的な案件ルールが届かない事故が起こり得ます。

32KiBの上限で案件固有の指示が外れる可能性が、文章量を整理する一番大きな理由です。
上位のAGENTS.mdへ全てを書き足し続けると、下位に置いた大切な案件ルールが、容量の箱に入らなくなる可能性があります。

似た数字が出てくるため、3つの「情報量の箱」を分けて考えてください。

Skillが選ばれた後に読むSKILL.md本文も、最初のSkill一覧とは別です。
「32KiBを超えたから会話全体が終わる」「Skillを増やすとAGENTS.mdの32KiBが直接減る」という意味ではありません。

ファイル単体の大きさは、パソコンのファイル情報画面で確認できます。
次のコマンドを使えるターミナル環境では、バイト数を数値で確認できます。

wc -c AGENTS.md

ただし安全かどうかは1ファイルだけでなく、プロジェクトの最上部から作業開始フォルダまでに採用されるファイルの合計で判断します。
上限値は設定で変更できますが、数値を増やす前に、AGENTS.mdを案内役へ絞り、作業手順をSkillへ移し、事実を正本へ分ける方が、指示の競合も見つけやすくなります。

この上限への対策は、重要なルールを削ることではありません。
Codexの個人設定にあるAGENTS.mdには全体の安全原則だけを残し、Vault最上部には仕事別の入口を置き、反復工程はSkillへ、事実は正本へ移します。
過去の議論、終わった例外、他ツール専用の手順をAGENTS.mdに積まないことで、必要な指示が深い場所まで届く余白を作れます。

GPT-6 Astraでは、指示を短くするより「関係あるものだけを見せる」

GPT-6 Astraは従来モデルより指示追従が強く、SkillやAGENTS.md内の指示にも敏感です。
OpenAIは、モデルが参照できる指示ファイルを監査することを推奨しており、不明確または競合したSkill指示は、作業を早く停止させる原因にもなると説明しています。

結論は「常に短いほど良い」ではありません。
仕事に必要な明確なルールは残し、不要な背景、古い例外、別用途の手順、二重の正本を外すことが重要です。
軽量化とは情報を薄くすることではなく、必要な時に必要な情報だけへ到達できるようにすることです。

Codexの個人設定、Vault最上部、案件フォルダのAGENTS.md、Skill、正本を役割で分ける設計は、モデルの能力を制限するためではなく、判断に必要な文脈を濁らせないためのものです。
ルールを書き足すほど、AIが賢くなるという誤解も、同じ問題を「指示の圧縮」という観点から扱っています。

まず15分で、1つの仕事だけ地図にしてみる

いきなり全Vaultの指示を作り直す必要はありません。
最初は、手戻りが多い仕事を1つだけ選びます。

たとえば「A社の提案書を作る」「noteの記事を書く」「Webサイトの機能を修正する」のどれか1つです。
紙やメモへ、次の5つを書き出してください。

1. Codexで新しいタスクを始めた時、中心にしているフォルダはどこか。
2. Codexの個人設定にあるAGENTS.mdには、何が書かれているか。
3. 選んだ仕事が入っているVaultまたは開発プロジェクトの最上部から、対象フォルダまでの間に、どのAGENTS.mdがあるか。
4. 今回使う作業手順はSkillになっているか。
5. 最新の数字、顧客情報、原稿、決定事項は、どの正本を見るか。

次に、AGENTS.mdにある1文ずつを、冒頭の置き場所表と照らします。
Codexの個人設定、Vault全体、対象案件、繰り返す工程、最新の事実という5つのどれかへ仕分けてください。

同じ1文が2か所にあれば、どちらを正本にするか決めます。
終わった例外や過去の議論なら、現在の指示から外します。
ここまで行うだけでも、上位と下位の役割はかなり見えるようになります。

「書いたのに伝わらない」時は、まず4つだけ確認する

AIがルールを守らなかった時、すぐに文章を追加しないでください。
最初は次の4つを確認します。

1. 今回、Codexはどのフォルダを中心に新しいタスクを始めたか。
2. ルールを書いたAGENTS.mdは、プロジェクト最上部から作業開始フォルダまでの経路上にあるか。
3. 同じ話題について、作業場所に近いAGENTS.mdへ別の指示がないか。
4. AGENTS.mdを変更した後、目的のフォルダから新しいタスクで確認したか。

それでも直らない時に見る8つ

1. Gitで管理された場所なら、プロジェクトの最上部はどこか。
2. 同じフォルダのAGENTS.override.mdが、通常のAGENTS.mdを差し替えていないか。
3. 守られなかったルールが、今回のユーザー依頼や実行環境の権限と衝突していないか。
4. プロジェクト指示の合計が32KiBに近く、下位の指示が箱から外れていないか。
5. 詳細な作業手順や長い参照資料を、AGENTS.mdへ詰め込みすぎていないか。
6. 反復作業ならSkillへ分け、名前と説明だけで用途が分かるようになっているか。
7. 事実や本文を、README・AGENTS.md・Skillへ二重にコピーしていないか。
8. 複数Vaultでは、今回使うVaultを中心フォルダにし、追加フォルダのルールまで自動で読まれると思い込んでいないか。

この診断で見つかる問題の多くは、AIの理解力不足ではありません。
ルールが今回の仕事まで届いていない、同じ事実の正本が2つある、または指示と作業手順と事実が1つのファイルに混ざっていることが原因です。

最後に。AGENTS.mdは、巨大な取扱説明書ではなく地図です

「どこに何を書くか」を決めることは、AIのためだけではありません。
未来の自分や共同作業者が、迷わず同じ判断を再現するための設計です。

Codexの個人設定には、全ての作業に共通する短い原則を置く。
Vaultやプロジェクトの最上部には、仕事別の入口を置く。
案件・記事・機能のフォルダには、当該フォルダで初めて必要になる差分だけを書く。
繰り返す工程はSkillへ、最新の事実は正本へ分ける。

AIへ背景を渡す具体的な設計は、AIの手直しを減らす方法も参考にしてください。
大切なのは、全てを最初から読ませることではなく、必要な時に正しい背景へ到達できる地図を作ることです。

探索順や上限の説明は、2026年9月時点のCodex公式仕様を基にしています。
製品は更新されるため、実際の設定変更前には公式ドキュメントも確認してください。