CodexのAGENTS.mdに何を書く？書き直したら毎回同じ説明をする手間が消えた話

👀 結論から

Codex を使っていてさりげなくストレスだったのが、毎回同じ前提を説明していることでした。

「このプロジェクトはこのフォルダは触らないで」「テストはこのコマンドで」みたいな話を、セッションのたびに書いていたんですよね(´･ω･`)

これを解決するのが AGENTS.md で、Codex が作業を始める前に読む指示書にあたります。

真面目に書き直してみたら、説明の手間が消えただけでなく、そもそも余計なことをされる回数が減りました。

ただ、何でも書けば変わるわけではなかったので、変化があったもの・なかったものを分けて書いておきます。

💡 AGENTS.md とはなにか

AGENTS.md は、リポジトリに置いておくテキストファイルです。

Codex が作業に入る前にこれを読むので、「このプロジェクトではこう動いてね」というお願いを置いておく場所になります。

特別な書式があるわけではなく、普通の日本語で書いて問題ありません。

私の場合、最初は3行くらいの雑なメモだったのですが、運用しているうちに「毎回説明していること」がそのまま追記されていき、今は30行くらいになっています。

大事なのは分量ではなく、**「毎回言っていることが書いてあるか」**だと思います。

✨ 書いて変化があったこと

実際に書いてみて、明確に挙動が変わったのはこのあたりでした。

1. 触ってほしくない場所

「このディレクトリは自動生成なので編集しない」と書いておくと、生成物を直接直そうとする動きがほぼなくなりました。

これが一番効果を感じたところです。

2. 検証の手順

「変更後は必ずこのコマンドでビルドを通してから報告する」と書いておくと、確認せずに『できました』と言ってくることが減りました。

3. 既存のやり方に合わせる指示

「同じような処理が既にある場合は新規作成せず流用する」と書いておくのも効きました。

放っておくと似た関数を新しく作りがちなので、車輪の再発明を防ぐ一文は入れておく価値があります。

4. 出力の形式

「変更したファイル・理由・影響範囲を最後にまとめる」と書いておくと、報告の粒度が安定しました(^^)

🤔 書いても効きにくかったこと

逆に、書いてもあまり変わらなかったものもあります。

抽象的な方針

「品質を重視して」「丁寧にやって」みたいな書き方は、判断の基準がないのでほぼ機能しませんでした。

同じことを言うなら「テストを追加せずにロジックを変えない」のように、行動として判定できる形に落としたほうが効きます。

分量の多い背景説明

プロジェクトの歴史や経緯を長く書いても、実際の作業にはあまり影響しませんでした。

その情報を読んで何をしてほしいのかまで書いていないと、読まれても行動に変換されないんだと思います。

このあたりは、人に仕事を頼むときとまったく同じですね(・_・;)

🧭 CLAUDE.md との書き分け

私は Claude Code も併用しているので、CLAUDE.md と AGENTS.md が両方あります。

最初は「二重管理になって面倒だな」と思っていたのですが、運用してみると書き分けの軸ははっきりしていました。

プロジェクト固有のルール（触らない場所・検証コマンド・命名規則）→ 両方に同じ内容を書く
ツール固有の作法（そのCLIの承認モードや実行方法の前提）→ それぞれのファイルに分けて書く

共通部分は同じ内容を書くことになるので、片方を直したらもう片方も直すというのだけ気をつけています。

どちらか一方しか読まれない状況で事故るより、多少冗長でも両方に書いておくほうが安全だと感じています🤔

🔧 私の AGENTS.md の最小テンプレート

いろいろ書いて試した結果、AGENTS.md は短くて具体的なほうが守られると感じています(^^)

今はこのくらいの量に落ち着きました。

# AGENTS.md

## コマンド
- テスト: `php artisan test --parallel`
- 静的解析: `./vendor/bin/phpstan analyse`
- フォーマット: `./vendor/bin/pint`

## 触らないもの
- `database/migrations/` の既存ファイルは編集しない（追加のみ）
- `.env` と `config/services.php` の値は変更しない

## 変更のルール
- 変更したら、上のテストと静的解析を通してから終わる
- 新しいパッケージを入れる前に、理由を書いて確認を取る

ポイントは、「〜しないでください」より、実行できるコマンドと具体的なパスを書くことです👀

あと、AGENTS.md はサブディレクトリにも置けます。

フロントエンドだけルールが違うなら、resources/js/AGENTS.md のように、その場所にだけ追加のルールを書いておくと、ルートの AGENTS.md が長くなりすぎずに済みます✨

パパ系Webエンジニア〜愛用ガジェット一覧 🛍️

AI開発・執筆に使っている作業デスク環境を楽天ROOMにまとめています ✨ デスク周りの参考にどうぞ 🙌

🙌 まとめ

AGENTS.md は、Codex が作業前に読む「プロジェクトの前提」を置いておくファイルでした。

触らない場所・検証手順・既存流用の指示は明確に変化が出る
出力形式の指定で報告の粒度が安定する
「丁寧に」のような抽象的な方針は効きにくい。行動で判定できる形に落とす
CLAUDE.md と併用するなら、プロジェクト固有のルールは両方に書く

毎回同じ説明をしている自覚がある人は、その説明をそのまま AGENTS.md に移すところから始めるのがおすすめです🙌

※ 仕様や読み込みの挙動は今後も変わる可能性があります。最新情報は Codex 公式ドキュメントをご確認ください👀