4-1 AGENTS.md の書き方｜毎回の説明をなくす

このレッスンでわかること

同じ説明を毎回繰り返していませんか。「金額は税込で」「元ファイルは変更しないで」——それをファイルに書いておけば、二度と説明しなくて済みます。

• AGENTS.md が何をするファイルかがわかる
• 何を書くべきかがわかる
• 育て方の型が身につく

AGENTS.md とは

作業フォルダに置いておくと、Codex が毎回自動で読む指示ファイルです。

新しく入った人に渡す「申し送りメモ」だと考えてください。そこに書いてあることは、毎回口頭で説明しなくて済みます。

作り方は簡単です。対話画面に入力します。

このフォルダに AGENTS.md を作ってください。
中身は、これから相談しながら決めます。まずは空のひな形でお願いします。

何を書くか：4つの定番項目

1. 仕事の背景

このフォルダで何をしているのかを書きます。Codex はフォルダ名から推測しますが、当然のことでも書いてあったほうが精度が上がります。

## このフォルダについて

営業部の月次レポート作成用のフォルダです。
毎月初に、前月の売上データから報告書を作ります。

2. 用語

社内でしか通じない言葉を書きます。ここが効きます。

## 用語

- 「速報値」= 月初3営業日以内に出す暫定の数字。確定値とは別
- 「A案件」= 年間契約の顧客。単発の顧客とは集計を分ける

これがないと、Codex は一般的な意味で解釈します。

3. ファイルの構成

どのファイルが何なのかを書きます。

## ファイル構成

- `sales-YYYY-MM.csv` — 月次の生データ。**編集しない**
- `report-YYYY-MM.md` — 出力する報告書
- `template.md` — 報告書のひな形

4. してほしいこと・してほしくないこと

**4項目の中でもっとも効果が大きいのがこれです。**とくに「してほしくないこと」は事故防止の安全網になります。

## ルール

- 金額は必ず税込で書き、括弧で税抜も併記する
- 集計する前に、対象データの件数を報告する
- 数字が合わない箇所があれば、勝手に補わず質問する

## してほしくないこと

- 生データ（`sales-*.csv`）を書き換えない
- 確定版のファイルを上書きしない
- 推測で数字を埋めない

Codex 特有：階層は「連結」される

ここが Claude Code との明確な違いです。

フォルダに階層がある場合、Codex は 経路上のすべての AGENTS.md を連結します。

会社/              AGENTS.md ← 全社共通のルール
└ 経理/            AGENTS.md ← 経理部のルール
  └ 2026年度/      AGENTS.md ← 今年度のルール

2026年度/ で作業すると、3つすべてが積み上がって適用されます。

Claude Code の CLAUDE.md は「近いものが優先」ですが、Codex は「全部足す」です。会社→部門→案件とルールを積み重ねたい場合、Codex の方式は素直です。

その代わり、**上位のルールを打ち消したい場合は工夫が要ります。**上書き専用のファイルを使う方法がありますが、まずは「積み上がる」とだけ覚えてください。

育て方：2回説明したら書く

最初から完璧なものを書こうとしないでください。運用しながら育てるものです。

判断の目安はシンプルです。

同じ説明を2回したら、AGENTS.md に書く。

1回目は事故、2回目はパターンです。パターンになったものを塞いでいきます。

Codex 自身に書かせる

自分でファイルを開いて編集する必要はありません。対話画面に入力します。

いまの決め事を AGENTS.md に追記しておいてください。

会話の中で決まったことを、そのまま申し送りに残せます。

長くしすぎない

**使われていないルールは、重要なルールを埋もれさせます。**定期的に見直して、不要なものは削ってください。

AGENTS.md を読んで、実際には使われていなさそうなルールがあれば指摘してください。

書いてはいけないこと

**パスワード・APIキー・顧客の個人情報は書かないでください。**AGENTS.md は毎回読み込まれるファイルで、チームで共有することもあります。

必要なら「認証情報は別途管理している」とだけ書き、実際の値は入れません。

やってみよう

1. ひな形を作る：作業フォルダに AGENTS.md を作らせてください
2. 4項目を埋める：背景・用語・ファイル構成・ルールを、自分の仕事に合わせて書いてください。Codex に「こういう仕事です」と説明して、代わりに書いてもらって構いません
3. 効いているか確認する：新しい会話を始めて「このフォルダのルールを要約して」と聞き、書いた内容が反映されているか確認しましょう
4. わざと破らせてみる：「してほしくないこと」に書いた操作を頼んでみてください。止められるか、あるいは確認されるかを見ます

演習4で、ルールが「お願い」であって「強制」ではないことが分かります。絶対に防ぎたいことは、第3章の設定で仕組みとして止めてください。

まとめ

• AGENTS.md は毎回自動で読まれる申し送りファイル
• 書くのは 背景 / 用語 / ファイル構成 / してほしいこと・してほしくないこと の4項目
• もっとも効くのは「してほしくないこと」
• **Codex は階層のすべてを連結する。**Claude Code の「近いものが優先」とは違う
• **同じ説明を2回したら書く。**最初から完璧を目指さない
• Codex 自身に追記させられる
• **長くしすぎない。**使われないルールは重要なものを埋もれさせる
• 機密情報は書かない
• AGENTS.md は「お願い」。絶対に防ぎたいことは第3章の設定で止める

理解度チェック

Q1. フォルダの階層ごとに AGENTS.md を置いたとき、Codex はどう扱うでしょう？

1. いちばん近い階層のものだけを読む
2. 経路上のすべてを連結して適用する
3. いちばん上の階層のものだけを読む
4. 複数あるとエラーになる

答えを見る

正解：2

Codex はプロジェクトルートから現在のフォルダまでの経路上にあるすべての AGENTS.md を連結します。会社全体・部門・案件とルールを積み上げる使い方に向いています。Claude Code の CLAUDE.md は下位が上位を上書きする方式なので、ここは挙動が違います。

Q2. AGENTS.md に書いた「してほしくないこと」について、正しい理解はどれでしょう？

1. 書いておけば、その操作は技術的に実行不可能になる
2. 指示として効くが強制ではない。絶対に防ぎたいことは承認モードやサンドボックスで止める
3. 書いても意味がないので、書く必要はない
4. 有料プランでのみ有効になる

答えを見る

正解：2

AGENTS.md は Codex への指示であり、精度は上がりますが「お願い」の域を出ません。生データを絶対に書き換えさせたくないといった要件は、第3章で扱った承認モードとサンドボックスで仕組みとして止めてください。両方を組み合わせるのが実務的です。