ちょくちょく他の記事内でも言及していますが・・・笑
私はいまだに、スタートレックの艦内コンピューターに憧れている。
呼べば答えるだけではない。艦の状態を知っていて、乗員の役割を理解していて、危険な操作には止めに入り、必要な手順を必要な時に呼び出してくれる。あの感じを、私はずっとコンピューターの理想形のひとつだと思っている。
そして最近、Codex の AGENTS.md を本気で設計しているうちに、これはただの便利メモではなく、かなり OS化 に近い話なのではないかと思うようになった。
そして昨今SNSでよく見かける投稿で
「Codexが最近急にアホになってきた」
「今までできていたことが急にできなくなったのはなぜ？ナーフされたのか？」
こういった投稿目につきませんか？
実は私のCodex環境はそういった現象は皆無です。
Codexのアホ化していない理由は多分この記事の内容がかなり影響していると考えてます。
もちろん、AGENTS.md は魔法の設定ファイルではない。書いた瞬間に Codex が完全な艦内コンピューターになるわけでもない。けれど、ここに優先順位、禁止事項、検証条件、ツール選択、停止条件をきちんと置くと、Codex の使い心地は明らかに変わる。毎回その場で口頭説明する相手ではなく、あなたの作業環境に常駐している判断層のように振る舞い始める。
この記事では、AGENTS.md を「作業メモ」ではなく 憲法 や カーネル として扱う考え方を整理する。特に、肥大化した AGENTS.md を小さな boot kernel と full kernel に分ける時、何を守らないと Codex が急に頼りなくなるのかを、実際の運用感から書いてみたい。
AGENTS.mdをOS化する目的は、Codexに毎回同じ注意を言うことではなく、優先順位、停止条件、検証条件を常駐させることだ。
AGENTS.mdは作業メモではなくCodexのOSになる
AGENTS.md という名前だけを見ると、最初は「このプロジェクトではこうしてください」という作業メモに見える。テストコマンド、パッケージマネージャ、コミット前の確認、コーディング規約。そういうものを書く場所だと理解している人は多いと思う。
それは間違いではない。むしろ入口としては正しい。ただ、そこで止めるには少しもったいない。
AGENTS.mdを好みリストで終わらせない
AGENTS.md に「pnpmを使って」「テストを走らせて」「このディレクトリは触らないで」と書くと、Codex はその指示を作業前提として扱いやすくなる。これは便利だ。けれど、便利な好みリストのままだと、Codex の振る舞いはまだその場その場のチャットに強く依存する。
一段深く使うなら、AGENTS.md には「どう動くか」だけでなく「何を勝手に判断してはいけないか」を書く必要がある。
たとえば、作業前に source of truth を確認する。ユーザーの未コミット変更を戻さない。専用 skill や plugin があるなら汎用 shell に逃げる前に契約を読む。生成物と source を混同しない。検証できない時は、なんとなく通ったことにしない。
こういう規則は、単なる好みではない。Codex の判断の土台になる。ここまで来ると、AGENTS.md は「お願いリスト」ではなく、実行環境のルールセットになってくる。
憲法として書くとCodexの判断が変わる
私は AGENTS.md を 憲法 と呼ぶことがある。少し大げさに聞こえるかもしれないが、使い方としてはかなり近い。
憲法には、日々の細かな手順だけでなく、優先順位と禁止事項が書かれている。何が上位にあり、何が下位にあるのか。どこで止まるべきか。どの権限を持っていて、どの権限は持っていないのか。
AGENTS.md も同じだ。
「ユーザーの明示要求がある時だけ外部送信する」「破壊的操作の前に止まる」「source repo と cache を混同しない」「専用 workflow がある領域では generic fallback しない」。これらは、単なる文章ではなく Codex の行動を縛る運用契約になる。
そして、Codex はこの手の契約がある時のほうが、明らかに安定する。毎回のプロンプトで「気をつけてね」と言わなくても、どこに足場を置いて判断すべきかが決まるからだ。
OS化で毎回の説明コストが減る
AGENTS.md を OS化 する最大のメリットは、毎回の説明コストが減ることだ。
人間同士でも、長く一緒に仕事をしている相手には、いちいち全部を説明しない。「いつもの基準で」「この種類の作業ならあの手順で」「そこは触らないでおいて」で通じる。これは相手が賢いからだけではなく、共有された作業環境があるから成り立つ。
Codex でも同じことをやりたい。
AGENTS.md によって、作業前提、権限、ツール選択、検証基準が常駐していると、Codex は「この場だけの会話」ではなく「この環境の中での作業」として依頼を受け取りやすくなる。ここで使用感が一段上がる。
もちろん、完全な記憶や完全な人格が宿るわけではない。ただ、少なくとも「毎回新人に説明している感じ」は薄くなる。これは大きい。
艦内コンピューターに近づく感覚はどこから生まれるのか
スタートレックの艦内コンピューターに惹かれるのは、単に音声で答えるからではない。あれは、環境に埋め込まれている。船内の状態、権限、文脈、手順、リスクを知っている存在として振る舞う。
Codex に AGENTS.md を設計する時、私が欲しいのもそこだ。会話相手として賢いだけではなく、作業環境の側に立っている感覚が欲しい。
呼べば答えるだけでは足りない
AIチャットは、呼べば答えてくれる。それだけでも十分に便利だ。だが、仕事の中で使うと、だんだん別の不満が出てくる。
「前にも言ったけど、この環境ではそれをやらないでほしい」
「そこは普通の shell ではなく専用ツールを使う約束だった」
「軽い修正だからといって、検証条件を落とさないでほしい」
この不満は、AIが答えられないことへの不満ではない。環境の文脈を常駐させられていないことへの不満だ。
AGENTS.md をOSとして設計すると、この不満がかなり減る。毎回の依頼文に全部書かなくても、Codex がまず参照すべき契約がある。そこに「この艦ではこう動く」が書いてある。
状況を知っていて止めるべき時に止める
艦内コンピューターらしさは、何でも実行することではなく、止まるべき時に止まることにもある。
たとえば、削除、上書き、外部送信、認証、課金、Git履歴変更、cache refresh、plugin activation。こういう操作は、便利だからといって気軽に進めるべきではない。人間なら「これは確認が必要だな」と思う場面で、Codex も止まってほしい。
AGENTS.md に停止条件を書く意味はここにある。
単に「安全にやって」と書くより、「この種類の操作では止まる」「この境界を越えるなら確認する」「検証できないなら未検証として報告する」と書くほうが強い。これがあると、Codex は賢く進むだけでなく、賢く止まれる。
この「止まれること」が、作業相手としての信頼感を作る。
常駐する作業環境としてCodexを見る
Codex をチャット相手として見ると、毎回の会話が主役になる。何を頼むか、どう言うか、どこまで説明するかがすべてになる。
しかし、Codex を作業環境として見ると、発想が変わる。
AGENTS.md がカーネルで、skills や plugins がドライバやサブシステムで、validators がテストや安全装置になる。Atlas のような環境索引があるなら、それは地図になる。hooks があるならイベント処理になる。こうして見ると、Codex は単体のAIではなく、小さな作業OSのように見えてくる。
もちろん比喩だ。だが、比喩としてかなり使える。
なぜなら、この見方をすると「プロンプトをうまく書く」だけではなく、「環境をどう設計するか」に意識が向くからだ。ここが、Codex の使い心地を一段上げるポイントだと思う。
小さなboot kernelとfull kernelを分ける理由
AGENTS.md を本気で育てていくと、いずれ肥大化する。
最初は数行だったものが、作業前提、ツール境界、Git方針、ブラウザ検証、Python runtime、画像生成、UI、WordPress、plugin、skill、subagent、デバッグ方針と増えていく。これは自然なことだ。Codex に任せる作業が広がれば、契約も増える。
問題は、AGENTS.md が大きくなりすぎると、今度は読み込みと文脈管理が苦しくなることだ。
現状の私の Codex内の位置関係を図に書いておく。
この関係を実現した環境は実にうまく動作している事実がある。
肥大化したAGENTS.mdはコンテキストを圧迫する
AGENTS.md は、Codex が作業前に読む重要なファイルだ。だが、何でも入れればよいわけではない。巨大な契約を毎回すべて読み込むと、コンテキストを圧迫する。
これは、実に悩ましい。
契約を削ると安全性や使用感が落ちる。だが、契約を全部常時ロードすると、今度は作業本体に使える文脈が減る。しかも、軽い依頼のたびに巨大な憲法全文を読ませるのは効率が悪い。
そこで、小さな boot kernel と詳細な full kernel を分ける発想が出てくる。
boot kernel には、最初に絶対必要な優先順位、停止条件、参照規則、オンデマンド読み込みの条件だけを置く。詳細な運用規則は full kernel に残す。そして、該当する作業面に触れた時に必要な部分を読む。
この構造は、かなりOSっぽい。
boot layerは削除ではなく読み込み口である
ここで一番大事なのは、boot layer は full kernel の要約ではない、ということだ。
要約にしてしまうと危ない。要約は必ず情報を落とす。落ちた情報が「今回は不要な細部」ならいいが、実際には安全境界や検証条件が落ちることがある。
だから、boot layer は要約ではなく、読み込み口であるべきだ。
「この領域に触れたら full kernel の該当 section を読む」
「判断に迷ったら小さい方の文面だけで決めない」
「詳細が見つからない、読めない、矛盾するなら generic fallback せず止まる」
こういう規則が boot layer に必要になる。
| 層 | 役割 | 失うと起きること |
|---|---|---|
| boot kernel | 最初に読む優先順位と停止条件を置く | 詳細規約を読む入口が曖昧になる |
| full kernel | 実務別の詳しい運用契約を残す | UI、Git、画像、DEBUGなどの判断が薄くなる |
| page fault load | 該当surfaceで必要sectionを読む | 軽い依頼で規約抜けが起きる |
OSで言えば、boot loader が本体を消したわけではない。最小の初期化をして、必要なものを読み込める状態にする。AGENTS.md の小型化も同じで、小さくしたから弱くなるのではなく、小さくしたぶん読み込み規律を強くしないといけない。
必要な規約を必要な時に読む設計
この設計は、ある意味でオンデマンドだ。
UIを作る時はUIの規約を読む。画像生成をする時は画像生成の契約を読む。source/cache/runtime に触れるなら、その境界の規則を読む。AGENTS.mdやSKILL.mdを編集するなら、専用のclarifierやvalidatorを使う。ブラウザ検証なら、どのブラウザ経路を使うかを混同しない。
これを徹底すると、Codex は必要な時に必要な規約へページフォルトするようになる。
私はこの感覚がかなり好きだ。古いOSのメモリ管理みたいで、少し笑える。けれど、構造としてはかなり真面目だ。限られたコンテキストの中で、常駐させるものと必要時に読むものを分ける。これはLLM時代の作業環境設計そのものだと思う。
オンデマンド化で憲法を弱めてはいけない
ただし、ここには落とし穴がある。
full kernel を別ファイルにした瞬間、Codex がそれを「必要な時だけ読めばいい参考資料」と誤解すると、憲法が弱くなる。これはかなり危険だ。
オンデマンド化は、契約を任意化することではない。読み込みタイミングを変えるだけで、拘束力を落としてはいけない。
軽い依頼ほど規約抜けが致命傷になる
「軽い依頼なら、そこまで読まなくていいのでは」と考えたくなる。
しかし、実際には逆だ。軽い依頼ほど危ない。
なぜなら、軽い依頼では人間もCodexも油断しやすいからだ。ちょっと直すだけ。少し確認するだけ。1ファイルだけ。すぐ終わる。こういう時に、source/cache/runtime の境界を間違える。専用 skill があるのに generic shell で済ませる。検証を省く。ユーザーの未コミット変更を巻き込む。
大きな作業では、さすがに慎重になる。だが、小さな作業では「いつもの契約」が勝手に効いてくれないと困る。
だから私は、軽い依頼を full kernel 読み込みの例外にしてはいけないと思っている。軽い実行とは、報告を短くすることや検証範囲を狭くすることであって、契約を弱めることではない。
full kernelは別ファイルでも拘束力を持つ
full kernel を別ファイルに置くなら、boot kernel 側にこう書いておく必要がある。
「ここにない詳細は、存在しないものとして扱ってよい」ではない。
正しくは、「ここにない詳細は、full kernel にある可能性がある。該当 surface に触れるなら読む」だ。
これは小さな違いに見えて、運用上は大きい。
前者だと、Codex は boot layer に書かれていないことを自由裁量として扱いやすい。後者だと、Codex は不足を検知した時に full kernel を取りに行く。まさに page fault load の発想だ。
重要なのは、FULL が旧AGENTS.md時代と同じ意味を保つことだ。ファイルが分かれても、そこに書かれた意図は失われない。むしろ、分割したからこそ、どの条件で読むのかを明確にしないといけない。
fail closedとpage fault loadで守る
オンデマンド構造を安全にするには、私は二つの考え方が必要だと思っている。
ひとつは page fault load。作業が特定の面に触れたら、該当する詳細規約を読む。UI、画像、Git、デバッグ、ブラウザ、Python、plugin、skill、source/cache/runtime。こういう面に触れたら、boot layer だけで判断しない。
もうひとつは fail closed。読むべき full kernel がない、読めない、古い、矛盾する。この場合に、記憶や勘で進めない。generic fallback もしない。止まる。
この二つがあると、オンデマンド化はかなり強くなる。
逆に、これがないと危ない。小さなAGENTS.mdは、単なる薄いAGENTS.mdになってしまう。昔の巨大な憲法を捨てたわけではないのに、実行時には捨てたのと同じになってしまう。
full kernelを別ファイルにしても、拘束力を落としてはいけない。読むべき契約が読めない、古い、矛盾する時は、記憶で進めずfail closedにする。
32KiBの壁が教えてくれるAGENTS.md設計の現実
この話が面白いのは、かなり現代的なAIの話をしているのに、構造としては古のメモリ管理の問題に似ているところだ。
限られた領域に何を常駐させるか。何を必要時に読むか。読み込みに失敗した時どう止まるか。まるで昔のOSやMS-DOS時代の工夫が、LLMのコンテキスト管理として戻ってきたように見える。
笑い話みたいだが、かなり本質的だ。
公式ドキュメントにもあるロード上限
OpenAI の Codex ドキュメントでも、AGENTS.md は global guidance や repository-level instructions として扱われる。さらに、instruction files の combined size は `project_doc_max_bytes` の上限に達すると追加されなくなり、この値は 32 KiB が default だと説明されている。上限に当たる場合は、limit を上げるか nested directories に分けることが案内されている。
これには素直に読むと 設定値(config.toml内)の上限を超えると切り捨てますって意味になる。
しかし現状は私の元々の90KB近い巨大なAGENTS.mdも普通に切れることなくコンテキストに読まれていた。
ただしこの読めるから良いのでは？で終わらせると少々危うい。 公式仕様としてこの上限制限が
存在している以上 現在読めるのは暫定的な処置の可能性も無きにしも非ずだ。
参考: Custom instructions with AGENTS.md – OpenAI Developers
だから 32 KiB という値を見ると、私は正直「いや、それは小さすぎるだろう」と思った。
少なくとも、AGENTS.md を本気でOS化しようとする人間にとっては、かなり厳しい。
ただ、ここで文句だけ言っても仕方がない。むしろ、この制約があるからこそ、AGENTS.md を単なる長文設定ではなく、boot設計として考える必要が出てくる。
DOS的な古い問題がLLM時代に戻ってくる
ならばどうするか。
昔のメモリ管理では、限られた領域に何を置くかが大問題だった。不要なものを常駐させると本体が動かない。必要なものを外しすぎると、今度は機能が足りない。拡張メモリ、ドライバ、設定ファイル、起動順序。そういう工夫が必要だった。
AGENTS.md のOS化も、どこかそれに似ている。
boot kernel には、最初に必要なルールだけを置く。full kernel には、詳細な憲法を残す。Atlas や metadata は地図として使う。skills や plugins は機能モジュールとして呼び出す。validators は、読み込んだ規約が実際に守られているかを見る。
古のテクニックが現代に炸裂している感じがある。
ただし、古いメモリ節約術と同じで、やり方を間違えると破綻する。必要なものまで削ると、軽くなるのではなく、壊れる。
制約を前提にOS設計へ進む
だから、AGENTS.md の設計では「何を書くか」だけでなく、「何をどこに置くか」が大事になる。
常時ロードすべきものは、優先順位、停止条件、full kernel の拘束力、オンデマンド読み込み条件、generic fallback 禁止条件のような、失うと全体が崩れる規則だ。
詳細な実務規則は、該当領域ごとに分けてもよい。UI、画像生成、ブラウザ検証、Git、Python runtime、plugin maintenance、AGENTS編集。これらは必要時に読めばよい。ただし、読む条件は boot kernel 側に明記する。
ここが分かれる。
AGENTS.md を小さくすること自体が目的ではない。小さくしても憲法が効く構造を作ることが目的だ。
Codexを一段上げるAGENTS.md運用の原則
AGENTS.md をOSとして扱うなら、最終的にはいくつかの原則に落ち着く。
難しいことを言っているようで、やることは意外と地味だ。どこがSSOTなのかを書く。何を優先するのかを書く。どこで止まるのかを書く。専用ツールがあるなら、それを先に読む。検証できないなら、できないと報告する。
この地味さが大事だと思う。
AGENTS.mdをOSとして育てる時、最初に見るポイントは次の四つだ。
- SSOTがどこかを明記する
- 優先順位と停止条件を先に置く
- 専用skillやvalidatorの入口を書く
- 軽い依頼でも契約を弱めない
SSOTと優先順位を明文化する
最初に決めるべきは、SSOT と優先順位だ。
どの AGENTS.md が上位なのか。local AGENTS.md がある時はどう扱うのか。ユーザーの明示要求と、既存の運用契約がぶつかった時にどうするのか。README や過去の会話は、どこまで拘束力を持つのか。
ここが曖昧だと、Codex はその場の雰囲気で動きやすくなる。
AGENTS.md を憲法にするなら、優先順位は最初に置く。さらに、詳細な full kernel があるなら、その full kernel が「読まれていないから無効」にならないようにする。boot layer にないことを自由裁量にしない。
この一点だけでも、Codex の挙動はかなり締まる。
ツールとvalidatorをOS部品として扱う
次に、skills、plugins、hooks、MCP tools、validators をOS部品として扱う。
Codex にとって一番危ないのは、専用ルートがあるのに generic fallback してしまうことだ。画像生成には画像生成の契約がある。AGENTS.md編集にはAGENTS.md編集のclarifierがある。UI検証にはブラウザ経路の境界がある。source/cache/runtime にはそれぞれの意味がある。
このあたりを AGENTS.md に書くと、Codex は「とりあえず shell でそれっぽく処理する」前に、専用の契約を探しやすくなる。
さらに validator があるなら、必ず使う。これはOSで言えば、起動時チェックやデバイス確認に近い。動いた気がする、では足りない。通ったか、どこが未検証かを残す。
Codex の出力品質は、賢さだけで決まらない。契約と検証の組み合わせで決まる。
艦内コンピューター感は日々の小さな作業で育つ
最後に、AGENTS.md のOS化は一回で完成しない。
むしろ、日々の小さな作業で育つ。軽い修正で規約抜けが起きたら、なぜ起きたかを見る。専用ツールが見落とされたら、routing metadata を直す。検証が曖昧なら validator に寄せる。ユーザーが毎回同じ注意をしているなら、それはAGENTS.mdへ昇格する候補だ。
こうして少しずつ、Codex はあなたの作業環境に馴染んでいく。
スタートレックの艦内コンピューターにはまだ遠い。だが、AGENTS.md をただのメモではなく、OSのカーネルとして育てると、その方向へ少し近づく感覚がある。
呼べば答えるだけではない。状況を知っていて、止まるべき時に止まり、必要な手順を呼び出し、あなたの作業環境のルールに沿って動く。
私は、そういうCodexの使い方がかなり好きだ。
そして、その入口はたぶん、プロンプトをもっと頑張ることではない。
AGENTS.md を、作業メモではなく、あなたの Codex の小さなOSとして書き始めることだ。
