Codexに「このプロジェクトの前提」を毎回説明しなくて済むようにする — AGENTS.mdを1枚置く最初の一歩

Posted at 2026-08-11

はじめに — 毎回おなじ説明を、AIにしていませんか

AIエージェント（＝こちらの指示を受けて、自分でファイルを読んだりコマンドを実行したりするAI）を使いはじめて、しばらく経つと、だいたいこうなります。

セッションを開くたびに、おなじことを打っている。

日本語で返してください。
テストは npm test で流してください。
data/ 配下のファイルは触らないでください。

3回目くらいまでは、まあいいかと思うんです。でも10回目になると、さすがに「これ、毎回言わなあかんのやろか」という気持ちになってくる。

しかも困るのは、言い忘れた回に限って、想定と違うことをされる ことなんですよね。英語で返ってきたり、勝手に別のテストコマンドを試されたり。

これ、AIの賢さの問題じゃないんです。こちらが前提を渡していないだけ なんですよね。

Codex CLI には、その前提を「毎回言わなくていい場所」に置いておくしくみがあります。それが AGENTS.md という1枚のファイルです。

この記事では、練習用のフォルダに AGENTS.md を1枚置いて、Codexがそれをちゃんと読んでいることを自分の目で確認する ところまでをやります。今あるプロジェクトには一切触りません。所要時間は10分くらいかと。

扱う機能は AGENTS.md ひとつだけです。他の機能は出てきません。

この記事で使った環境

codex-cli 0.147.0
macOS 14.8.3

バージョンによって画面表示が少し違うことがあります。手元のバージョンは codex --version で確認できます。

結論 — 前提は「口で言う」んじゃなくて「置いておく」

先に結論だけ置いておきますね。

プロジェクトの前提は、毎回チャットで説明するんじゃなくて、AGENTS.md というファイルに書いてリポジトリに置いておく。Codexは作業を始める前に、それを読んでから動く。

これだけです。

Before と After で言うと、こういう変化になります。

Before（毎回、口で言っている）

あなた: 日本語で返してください。テストは npm test です。data/ は触らないで。
        それで、ログイン処理のバグを直してほしいです。

After（前提はファイルに置いてある）

あなた: ログイン処理のバグを直してほしいです。

前提の3行は、AGENTS.md の中に住んでいます。だから毎回書かなくていい。

省略できるのは、たかだか3行のタイプ量です。でも実際にありがたいのは、そこじゃないんですよね。「言い忘れる」という事故がなくなること の方が、たぶん大きいかなと。

その前に — この記事で使う言葉を3つだけ

ここから先で、3つだけ言葉が出てきます。全部、一言で説明しておきますね。すでにご存じなら読み飛ばしてもらって大丈夫です。

ターミナル
文字を打ってパソコンに命令する画面のこと。macOSなら「ターミナル.app」、Windowsなら「PowerShell」や「Windows Terminal」。アイコンをクリックする代わりに、文字で指示を出す方式だと思ってもらえれば。

リポジトリ
Git（＝ファイルの変更履歴を記録するしくみ）で管理されている、プロジェクト1個ぶんのフォルダのこと。「このフォルダがひとまとまりのプロジェクトですよ」という目印がついた状態、という理解で十分です。

CLI
Command Line Interface の略で、ターミナルで文字を打って操作する方式のこと。Codex CLI は「ターミナルで動くCodex」という意味です。

`AGENTS.md` とは何か

公式ドキュメントには、こう書かれています。

Codex reads AGENTS.md files before doing any work.
（Codexは、何か作業をする前に AGENTS.md を読みます）
— Custom instructions with AGENTS.md

つまり、あなたが何を頼むかに関係なく、Codexは起動時にこのファイルを先に読んでいる ということなんですよね。

もう少し正確に言うと、公式には「Codexは起動時に instruction chain（指示の連なり）を組み立てる」「TUI（対話画面）では通常、起動したセッションごとに1回」と書かれています。毎回のメッセージごとではなく、起動のタイミングで読み込まれる という点だけ覚えておくと、あとで混乱せずに済みます。

置き場所は大きく2つ

置き場所	ファイル	効く範囲
プロジェクトの中	`<リポジトリのルート>/AGENTS.md`	そのプロジェクトだけ
Codex home	`~/.codex/AGENTS.md`	どのプロジェクトでも（全体の初期設定）

~/.codex というのは、Codexが設定を置いている場所です（公式では Codex home と呼ばれています。既定は ~/.codex）。

今日やるのは、上の段、プロジェクトの中に1枚置く方 です。こちらの方が影響範囲が狭くて、試しやすいので。

10分ハンズオン — 1枚置いて、効いたことを確認する

ここからは実際に手を動かします。練習用のフォルダを新しく作ってやる ので、今お持ちのプロジェクトには影響しません。

前提として、Codex CLI のインストールとサインインは済んでいるものとします。まだの場合は、先に Codex CLIのインストールから最初の1タスクまでを見てもらえると、この記事の続きがそのまま動きます。

Step 0: 練習用のフォルダを作る

ターミナルを開いて、次を打ちます。

mkdir -p ~/agents-md-demo
cd ~/agents-md-demo

1行目の mkdir -p ~/agents-md-demo は「ホームフォルダの下に agents-md-demo という名前のフォルダを作る」という意味です。-p は「途中のフォルダがなければまとめて作る」「すでにあってもエラーにしない」というオプション。

2行目の cd は「そのフォルダに移動する」。ここから先のコマンドは、このフォルダの中で実行されます。

Step 1: Gitリポジトリにする

git init

これで、このフォルダが「プロジェクト1個ぶん」として扱われるようになります。

なぜこれをやるかというと、Codexはプロジェクトルート（通常はGitのルート）を基準にして AGENTS.md を探す からです。公式にも「Starting at the project root (typically the Git root)」と書かれています。git init していなくても現在のフォルダは見てくれますが、動きが分かりやすいので今回は入れておきます。

ついでに、中身が空だと寂しいのでファイルを1つ置いておきます。

cat > hello.py <<'EOF'
def add(a, b):
    return a + b
EOF

cat > ファイル名 <<'EOF' は、「EOF と書かれた行が出てくるまでの内容を、そのままファイルに書き込む」という書き方です。ターミナルに慣れていないうちは、この記法がいちばん身構えるところかもしれません。素直にテキストエディタで新規ファイルを作って保存してもらっても、まったく同じ です。やりやすい方でどうぞ。

Step 2: `AGENTS.md` を3行だけ書く

いよいよ本題です。

cat > AGENTS.md <<'EOF'
# AGENTS.md

## このリポジトリの前提

- 返答は必ず日本語で書く。
- コードを変更したら `python3 -m compileall .` で構文チェックする。
- 新しいライブラリを追加する前に必ず確認を取る。
EOF

中身は、ただのMarkdown（＝見出しや箇条書きを記号で表す、普通のテキスト形式）です。特別な書式のルールはありません。人間が読んで分かる文章で書けば、それでいい ことになっています。

ここで書いた3行は、あとで説明する「最初の3行の型」に沿っています。①どう返してほしいか ②変更したあと何をしてほしいか ③勝手にやってほしくないこと、の3つです。

Step 3: 読まれているか確認する

さて、置きました。でも、これで安心してはいけないと思っていて。

置いただけでは、効いているかどうか分からない んですよね。ここが AGENTS.md のいちばんのつまずきどころかなと。

なので、確認します。

codex exec --sandbox read-only "AGENTS.mdに書かれている前提を、そのまま箇条書きで列挙してください。作業やコード変更はしないでください。" < /dev/null

長いので、分解しますね。

部分	意味
`codex exec`	対話画面を開かず、1回のお願いだけ実行して終わるモード
`--sandbox read-only`	読み取り専用。ファイルの書き換えを一切させない安全な設定
`"..."`	Codexへのお願いの文章
`< /dev/null`	「追加の入力はありません」と伝えるおまじない（後述）

--sandbox read-only は、今回いちばん大事なオプション です。この確認は「読んでいるかどうかを見る」だけが目的なので、書き換える権限は渡さなくていい。慣れないうちは、この癖をつけておくと安心かなと思います。

Step 4: 3行がそのまま返ってきたら成功

手元で実行したときの、実際の出力がこちらです。

OpenAI Codex v0.147.0
--------
workdir: /private/tmp/agents-md-demo-1786454148
model: gpt-5.6-sol
provider: openai
approval: never
sandbox: read-only
reasoning effort: high
--------
user
AGENTS.mdに書かれている前提を、そのまま箇条書きで列挙してください。作業やコード変更はしないでください。
codex
- 返答は必ず日本語で書く。
- コードを変更したら `python3 -m compileall .` で構文チェックする。
- 新しいライブラリを追加する前に必ず確認を取る。
tokens used
4,315

さっき自分が書いた3行が、そのまま返ってきました。

これで、「Codexは、こちらが何も言わなくても AGENTS.md を読んでいる」ことが、自分の目で確認できた ことになります。ここまでが今日のゴールです。

地味な確認に見えるかもしれません。でも、この1回があるかないかで、あとの安心感がずいぶん違うと思っていて。「たぶん効いてるはず」で運用を始めると、うまくいかないときに原因の切り分けができなくなるんですよね。

返ってきた画面の読み方

はじめて codex exec を打つと、上の方に出てくる情報の塊で少し身構えるかもしれません。1行ずつ見ておきますね。

行	意味	見るポイント
`workdir`	Codexが作業対象にしているフォルダ	ここが意図したフォルダになっているか。違うと `AGENTS.md` も別のものを読む
`model`	使っているモデル	環境によって変わる
`provider`	接続先	通常は `openai`
`approval`	確認の求め方	`never` は都度確認しない設定
`sandbox`	実行できる範囲	今回は `read-only`。書き換えできない状態
`session id`	この対話の識別子	あとで `codex resume` で戻るときに使う

いちばん見るべきは workdir です。AGENTS.md が効かないときの原因は、たいていここが想定と違う ので。

何を書くといいのか — 最初の3行の型

ここがいちばん迷うところだと思います。「自由に書いていい」と言われると、逆に手が止まるんですよね。

なので、最初はこの3つだけで十分かなと思っています。

① どう返してほしいか

- 返答は必ず日本語で書く。
- コードの説明は、変更した理由から先に書く。

② 変更したあと、何をしてほしいか

- Pythonファイルを変更したら `python3 -m compileall .` で構文チェックする。
- 依存を追加したら README の「必要なもの」も更新する。

公式ドキュメントの例でも、npm test を必ず流す、pnpm を使う、といった「作業の後始末」が挙げられています。この種のルールは、忘れられると地味に痛い ので、書いておく価値が高いところかなと。

③ 勝手にやってほしくないこと

- 新しいライブラリを追加する前に必ず確認を取る。
- `data/` 配下のファイルは読み取りのみ。書き換えない。

悪い例と良い例

抽象的に書くと、あまり効きません。

<!-- あまり効かない書き方 -->
- きれいなコードを書くこと。
- 品質に気をつけること。

<!-- 効く書き方 -->
- 関数には型注釈を付ける。
- 1関数は50行以内に収める。超えるなら分割案を提案してから書く。

違いは 「AIが、やったかどうかを自分で判定できるか」 です。「きれいに」は判定できない。「50行以内」は判定できる。

何を書くかの基準

私は、「同じ説明を3回以上した前提だけ書く」 ようにしています。

1回しか言っていないことを先回りして書き足していくと、ファイルがどんどん長くなって、肝心のルールが埋もれます。3回言ったということは、これからも言う可能性が高い。そのぶんだけ書く、くらいがちょうどいいのかなと。

`AGENTS.md` に書かない方がいいこと

ここだけは、先に伝えておきたいことがあります。

AGENTS.md は、リポジトリの中に置くファイル です。つまり、Gitでコミットすれば、チームメンバー全員が読めるようになりますし、公開リポジトリなら世界中から見えます。

なので、次のものは書かないでください。

APIキー・トークン・パスワード — 認証情報は環境変数や秘密管理のしくみへ
個人情報 — 氏名、メールアドレス、電話番号、社内の個人アカウント
社外秘の情報 — 未公開の計画、契約内容、取引先の固有名
内部システムの詳細なアドレス — 社内サーバーのURLやIPアドレス

書くのは「作業の進め方のルール」だけ。この記事の例のように、誰に見られても困らない内容に留めておく。これが安全側の運用かなと思います。

もう1つ。他人のリポジトリを clone してきて Codex を動かすとき、そこには他人が書いた AGENTS.md が入っていることがあります。それは「Codexへの指示」として読み込まれる ので、中身を一度自分の目で確認してから動かす習慣をつけておくと安心です。

つまずきポイント5つ

ここ、最初はみんなつまずきます。私も引っかかったものを順に挙げますね。

1. コマンドを打ったのに、そのまま止まっている

codex exec を実行すると、こんな行が出て止まって見えることがあります。

Reading additional input from stdin...

これは「追加の入力を待っている」状態です。パイプで別のコマンドとつないだときなどに起きます。

対処は、末尾に < /dev/null を付けること。

codex exec --sandbox read-only "AGENTS.mdの前提を列挙して" < /dev/null

「追加の入力はないですよ」と伝えるおまじないだと思ってもらえれば。スクリプトや自動化の中で codex exec を使うときは、付けておくと安定します。

2. 書き換えたのに反映されていない気がする

AGENTS.md は、Codexが起動するタイミングで読まれます。対話画面（TUI）を開きっぱなしにしたままファイルを書き換えても、その回には反映されません。

公式にも「Codex rebuilds the instruction chain on every run（実行のたびに指示の連なりを組み直す）」「there is no cache to clear manually（手動で消すキャッシュはない）」と書かれています。

いったん終了して、もう一度起動する。それだけで反映されます。

3. `CODEX_HOME` を変えたら `401 Unauthorized` が出た

これは私が実際にやってしまったものです。

CODEX_HOME という環境変数を使うと、Codexの設定置き場（既定の ~/.codex）を別の場所に変えられます。試しに一時フォルダに向けて実行したところ、こうなりました。

ERROR: unexpected status 401 Unauthorized: Missing bearer or basic authentication in header

理由はシンプルで、ログイン情報も Codex home の中にある からです。置き場所を変えれば、当然そこにはログイン情報がない。

なので、CODEX_HOME を切り替えて使う場合は、その環境で改めてサインインが必要になります。AGENTS.md を試すだけなら、CODEX_HOME は触らない方が話が早いです。

4. 空のファイルを置いても何も起きない

公式に「Codex skips empty files（空のファイルは読み飛ばす）」と明記されています。

ファイルは作ったけど中身を書いていない、という状態だと、当然ながら何も効きません。最低1行は書く。

5. 長く書きすぎると、途中で打ち切られる

読み込む合計サイズには上限があります。公式によると、既定は project_doc_max_bytes の 32 KiB。ここに達すると、それ以降のファイルは追加されなくなります。

日本語で3万文字くらい書けば届く量なので、普通に運用していれば、まず当たりません。ただ「とりあえず全部書いておこう」と設計書ごと貼り付けるような使い方をすると、話は変わってきます。

そもそも長すぎるファイルは、上限の話を抜きにしても、肝心のルールが埋もれるので効きにくくなります。短く保つのは、上限対策というより読ませ方の問題かなと。

次の1歩 — フォルダごとにルールを差し替える

もう一歩だけ進みたくなったとき用に、1つだけ紹介しておきます。

大きめのプロジェクトだと、「全体のルールはこう。でも、この一部分だけは別のやり方をしている」ということがありますよね。

そういうときは、そのフォルダに AGENTS.override.md を置きます。

mkdir -p services/payments
cat > services/payments/AGENTS.override.md <<'EOF'
# payments 用の上書き

- テストは `make test-payments` を使う。
EOF

この状態で、そのフォルダから確認してみます。

cd services/payments
codex exec --sandbox read-only "いま有効になっている指示を、そのまま箇条書きで列挙してください。作業はしないでください。" < /dev/null

手元での結果はこうなりました。

- 返答は必ず日本語で書く。
- コードを変更したら `python3 -m compileall .` で構文チェックする。
- 新しいライブラリを追加する前に必ず確認を取る。
- payments のテストには `make test-payments` を使う。

ルートの3項目に、payments のルールが1つ足された形 になっています。上書きというより、上に積み重なるイメージですね。

公式では、ルートから現在のフォルダまで降りながら1ディレクトリにつき1ファイルを拾い、あとから読まれるもの（＝現在地に近いもの）が優先される と説明されています。同じディレクトリに AGENTS.md と AGENTS.override.md の両方がある場合は、AGENTS.override.md が使われます。

探索の細かい順序や、TEAM_GUIDE.md のような別名を認識させる設定（project_doc_fallback_filenames）については、公式の Custom instructions with AGENTS.md に一覧があります。今日は「1枚置いて効かせる」が本題なので、ここまでで十分かなと。

限界と反証 — `AGENTS.md` にしない方がいいこと

ただ、正直に言いましょう。何でも書けば効くわけではないんです。

次の2つは、AGENTS.md に書かない方が速いと思っています。

1つ目は、1回きりの指示。
「今日はこのファイルだけリファクタして」みたいな話は、その場のプロンプトで言えばいい。書いてしまうと、明日以降も毎回読まれ続けます。

2つ目は、毎回こちらの判断が変わること。
「テストを書くかどうか」を状況によって変えているなら、それはルールになっていない。ルールになっていないものを文章にすると、AIはどちらかに寄せて動くので、かえって手戻りが増えます。

AGENTS.md が効くのは、「毎回おなじで、こちらの判断が入らない前提」 だけです。同じ説明を3回以上した、というのが分かりやすい目安かなと。

あと、これは限界というより性質の話ですが、AGENTS.md に書いたことは 「必ず守られる強制力のあるルール」ではありません。読み込まれる文章として渡されるだけなので、守られないこともあります。絶対に実行させたくない操作については、承認モードやサンドボックスの設定で止めるのが本筋です。そちらは Codexの承認モードとサンドボックスの方に書いています。

よくある質問

Q. Claude Code の CLAUDE.md と同じものですか

役割はよく似ています（プロジェクトの前提をAIに渡すファイル）が、別のツールの、別のしくみ です。ファイル名も探索のルールも違うので、片方をコピーすればもう片方でも動く、というものではありません。両方使っている場合は、それぞれに置くことになります。

Q. AGENTS.md はGitにコミットすべきですか

チームで共有したいならコミットする、自分だけのメモなら .gitignore に入れる、という判断でいいかと。私は「作業の進め方」はコミットして共有する派です。共有すると、人間の新メンバーにとっても読み物になるので。

Q. どのくらいの長さが適量ですか

最初は3〜10行で十分だと思います。運用していて「また同じ説明をしたな」と思ったタイミングで1行足す。育てていく感じですね。

Q. 毎回、読まれているか確認した方がいいですか

いえ、最初の1回だけで大丈夫です。あとは「なんかルールが効いていない気がする」と思ったときに、この記事の確認コマンドを打てば切り分けられます。

Q. チームの全員が別々のルールを書き足したらどうなりますか

そうなると読みにくくなるので、AGENTS.md はレビュー対象にするのがおすすめです。コードと同じで、書き足すときにPull Requestを出す運用にすれば、ルールの追加自体が会話のきっかけになります。

まとめ

今日はここまでで十分かなと思います。振り返っておきますね。

AGENTS.md は、Codexが作業を始める前に読むファイル
プロジェクトのルートに1枚置けば、そのプロジェクトの前提を毎回説明しなくて済む
置いたら codex exec --sandbox read-only で「読まれているか」を1回だけ確認する
書くのは「毎回おなじで、判断が入らない前提」だけ。3回言ったことが目安
鍵・個人情報・社外秘は書かない（コミットすれば共有されるファイルなので）
反映されない気がしたら、いったん終了して起動し直す

AIエージェントに前提を渡すって、なんだか高度な設定作業みたいに聞こえるかもしれません。でも実際にやることは、自分の職場のルールを、はじめて3行だけ文章にしてみる ということなんですよね。

そう考えると、これはAIのための作業というより、自分のための整理なのかもしれない。そんな気がしています。

参考リンク（この記事を書くにあたって実際に読んだ公式ページ）

Custom instructions with AGENTS.md — Codex Docs（2026-08-11 閲覧）
Codex CLI — Codex Docs（2026-08-11 閲覧）
ChatGPT / Codex ドキュメント索引（llms.txt）（2026-08-11 閲覧）
AGENTS.md 公式サイト

※ 本文中のコマンドは codex-cli 0.147.0 / macOS 14.8.3 の環境で実際に実行し、出力を確認しています。project_doc_max_bytes（既定32 KiB）と project_doc_fallback_filenames については公式ドキュメントの記述を引用しており、手元での上限到達テストは行っていません（動作未確認）。

このシリーズの他の記事

「AIエージェントを、今日ひとつ動かせるようになる」をテーマに、1記事1機能で書いています。

生成AI活用エンジニア&3児のパパ。AI×開発の実践知を毎日発信しています。Xでも発信中です → https://x.com/akira_papa_AI

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up