AGENTS.mdの書き方 — Codexに会社のルールを教える「社内憲法」の作り方と育て方

AGENTS.mdとは — Codexが毎回読む「ルールブック」

AGENTS.mdは、作業フォルダ（プロジェクト）に置くテキストファイルです。ここに書いた内容を、Codexはそのフォルダで仕事をするたびに必ず読み込み、ルールとして守ろうとします。「毎回の依頼文で説明していたこと」がファイル側に移るため、依頼はどんどん短く、成果物のブレはどんどん小さくなります。

当社はこれを「新人が古参社員に変わり始める分岐点」と呼んでいます。何も知らない新人（初期状態のCodex）に毎回口頭で指示するのをやめ、就業規則とマニュアルを渡す——AGENTS.mdを置くことは、それと同じ意味を持ちます。

置き場所 — 作業フォルダの直下に1枚から

基本は、Codexにプロジェクトとして選択している作業フォルダの直下に、AGENTS.md という名前で1枚置くだけです。ただし置ける場所は1か所ではありません。実際には「自分の共通ルール」「プロジェクト全体」「フォルダごと」の3階層に置けます。

~/.codex/
└── AGENTS.md                ← 自分の共通ルール

my-project/
├── AGENTS.md                ← このプロジェクト全体
│
├── sales/
│   └── AGENTS.md            ← 営業資料固有
│
└── marketing/
    └── AGENTS.md            ← マーケ固有

読み込み順 — 下の階層ほど優先される

Codexはセッション開始時に、該当するAGENTS.mdを上の階層から順に1本へ連結して読み込みます。たとえば marketing/ でCodexを起動すれば、次の順番です。

グローバル AGENTS.md
↓
プロジェクト AGENTS.md
↓
marketing/AGENTS.md

下位の指示ほど後に入るため、競合する指示は下位側が優先されます。書き分けのコツは、共通の仕事のやり方はグローバルに、プロジェクト全体の前提はプロジェクト直下に、その領域だけの事情は各フォルダに——という切り分けです。

何を書くか — 最初は3項目で十分

最初から立派なルールブックを作る必要はありません。当社が研修でおすすめしている初期構成は、次の3項目だけです。

1. 1会社・仕事の前提 — 何をしている会社／チームか、誰に向けた成果物か
2. 2成果物のトーンと形式 — 文体（です・ます調など）、分量の目安、ファイル名や保存場所のルール
3. 3やってはいけないこと — 使ってはいけない表現、触ってはいけないファイル、確認なしで送信・公開しない、など

書き方のイメージとして、非エンジニアの業務フォルダに置く最小構成の例を挙げます。

# AGENTS.md

## この作業フォルダについて
- 株式会社◯◯の営業企画チームの作業フォルダ
- 成果物の読み手は社内の経営会議メンバー

## 成果物のルール
- 文体は「です・ます調」、A4で1〜2枚に収める
- 数字は必ず元資料の値を使い、推測で補完しない
- ファイル名は「YYMMDD_内容.md」の形式で保存する

## やってはいけないこと
- 顧客名を成果物に書かない（社名はイニシャル表記）
- 完成前のファイルをフォルダ外にコピーしない

重要なのは、これが依頼文から「毎回同じ説明」を消すためのファイルだという目的意識です。1回しか使わない指示は依頼文に、毎回守らせたいことだけをAGENTS.mdに——この線引きさえ守れば、書く内容は自然に決まっていきます。

次の一歩 — 文系タスクなら、この4項目まで

公式ドキュメントでは、AGENTS.mdに書くとよい内容として6つの項目が挙げられています。ただし半分はプログラミングを前提とした項目です。資料作成や調査といった文系タスクでは、次の4つを書いておけば十分です。上の3項目で運用を始めたら、この4つに揃えていくイメージで育ててください。

4つ目の「完了の定義と、確かめ方」は、抜けやすいわりに効き目が大きい項目です。ここが書いてあるかどうかで、成果物が「それらしいもの」で止まるか、検算まで済んだ状態で返ってくるかが変わります。

育て方 — 「同じ指摘を2回したら1行追記」

AGENTS.mdは最初に完成させるものではなく、運用しながら育てるものです。当社のルールはシンプルで、「Codexの成果物に同じ指摘を2回したら、その場でAGENTS.mdに1行追記する」。これだけです。

たとえば「また文末が体言止めになっている」と2回直させたら、「文末は体言止めにしない」と1行足す。この積み重ねが数週間で効いてきて、レビューでの指摘がみるみる減っていきます。ルールファイルの価値は初期の完成度ではなく、運用の中で実際の失敗から学ばせた蓄積で決まります。

前提として知っておきたいのは、Codexが自分から気を利かせてAGENTS.mdを書き足すことはないという点です。書かれるのは、こちらが依頼したときだけ。だからこそ「2回目の指摘」を合図に、その場で頼んでしまうのが確実です。

今のルールは、今後もずっと守ってほしいので AGENTS.md に書き足してください。

このプロジェクトだけの話なのか、どの作業でも共通の話なのかを判断して、
どこに書き足すか（グローバル / プロジェクト / フォルダ）を先に教えてください。

肥大化させない — 精度と料金の両方に効く

育てる一方で、増やしすぎには注意が必要です。AGENTS.mdはCodexが毎回読み込むため、長くなるほど毎回の利用枠の消費が増え（公式ドキュメントも節約術として「AGENTS.mdを小さく保つ・ネストで分割する」ことを挙げています）、また指示が多すぎると重要なルールが埋もれて守られにくくなります。

上限は32KiB — 超えても警告は出ない

感覚論ではなく、明確な上限があります。3階層を連結した合計には project_doc_max_bytes という上限があり、既定は 32KiB（32,768バイト）です。厄介なのは、上限に達するとそれ以降のファイルは読み込まれないのに、警告もエラーも出ないことです。「書いたのに守られない」の原因がここにあるケースは珍しくありません。

バイト数と言われてもピンとこないので、目安に直します。日本語は1文字3バイトなので、すべて日本語なら合計でおよそ1万文字。1行30〜40文字として、250〜350行あたりが天井です。

• 定期的に棚卸しする — もう起きていない失敗のルールは削る・統合する
• 詳細はネストに逃がす — 特定業務だけのルールはサブフォルダのAGENTS.mdへ
• 「ルール」と「手順」を分ける — 毎回守る原則はAGENTS.md、特定業務の手順はSkillsに登録する（役割分担はCodexの応用機能まとめを参照）

組織で書く場合 — AGENTS.mdは「合意形成の成果物」

個人の作業フォルダなら自分の好みで書けばよい一方、チームの共有フォルダに置くAGENTS.mdは「会社として成果物に何を求めるか」の合意そのものです。トーン・禁止事項・確認フローを言語化する過程は、実はAI導入以前に曖昧だった業務基準を明文化する機会でもあります。当社のCodex研修・導入伴走支援では、貴社の実業務を題材にAGENTS.mdの初版を一緒に作り、育てる運用ルールまで含めて伴走しています。