AGENTS.mdの書き方｜Codex設定ファイル実践ガイド

OpenAI Codexを使い始めて、「毎回同じ説明を打ち込んでいる」「指示通りに動かない」と感じていませんか。プロジェクトのルールやビルド手順を毎回伝えるのは手間ですし、伝え忘れると的外れな結果が返ってきます。

結論から言うと、その悩みはAGENTS.mdというファイルをリポジトリに1枚置くだけで大きく改善します。AGENTS.mdはCodexがプロジェクト単位で自動的に読み込む「AIへの指示書」で、ここに書いたことはセッションのたびに毎回反映されます。

株式会社FyveはAI業務効率化の受託開発と専属AI活用顧問を手がけており、私たち自身もCodexを日常業務で使い込んでいます。この記事では、CLAUDE.md（Claude Code側の同等ファイル）の運用で蓄積した知見を踏まえつつ、AGENTS.mdの書き方・置き場所・「書きすぎると逆効果になる」といった実務的な勘所まで、非エンジニアの方にもわかる言葉で解説します。

AGENTS.mdとは何か

AGENTS.mdは、AIコーディングエージェントに対する「プロジェクトの取扱説明書」です。普通のMarkdownファイルで、開発環境のセットアップ方法・テストの流し方・守ってほしいルールなどを書いておきます。

公式は「エージェント向けのREADME」と表現しています。人間の新メンバーが入社したときに渡す業務マニュアルを、AI向けに用意するイメージだと考えるとわかりやすいです。

重要なのは、これが特定の製品だけのものではないという点です。AGENTS.mdは現在、Linux Foundation傘下のAgentic AI Foundationが管理するオープンな共通フォーマットになっており、OpenAI Codexだけでなく、GitHub Copilot・Cursor・Windsurf・Devin・Google製のJulesなど多くのツールが同じファイルを読み込みます。1枚書けば複数のAIツールで使い回せるわけです。

正体はただのMarkdownファイル。決まったスキーマや必須項目はない
見出しは自由。AIはテキストをそのまま読んで解釈する
OpenAI Codex・Copilot・Cursorなど複数ツールが共通で読む業界標準になりつつある

なお、Claude Codeでは同じ役割をCLAUDE.mdというファイルが担っています。私たちは社内のモノレポをCLAUDE.mdで運用していますが、その設計思想はそのままAGENTS.mdに翻訳できます。本質は「AIに毎回伝えたい前提を、ファイルに固定する」という一点だからです。

AGENTS.mdの置き場所と読み込みの仕組み

AGENTS.mdは置く場所が重要です。Codexは賢く探してくれますが、その探し方を理解しておくと、意図通りに指示を効かせられます。

基本はリポジトリのルートに1枚

もっともシンプルな運用は、Gitリポジトリの一番上の階層（ルート）にAGENTS.mdを1枚置くことです。プロジェクト全体に効かせたいルールはここに書きます。

Codexはセッションを開始すると、リポジトリのルートから現在の作業フォルダまでのパスをたどり、その途中にあるAGENTS.mdをすべて読み込みます。読み込んだ内容は、あなたが何か指示を出す前にAIの「頭の中（コンテキスト）」へ先に注入されます。

フォルダごとに細かいルールも置ける（階層構造）

大きなプロジェクトでは、フォルダごとに別々のAGENTS.mdを置けます。これを階層（カスケード）構造と呼びます。

たとえばapps/webというフォルダの中身を編集するとき、Codexはまずapps/web/AGENTS.mdを読み、そこに書かれていないことだけルートのAGENTS.mdで補います。Codexはルートから順に内容をつなげ、現在の作業フォルダに近いファイルほど優先されます（後から読まれるため上書きの形になる）。

全社共通のルール → ルートのAGENTS.mdに書く
特定の領域だけ違うルール → そのフォルダのAGENTS.mdに「差分だけ」書く
個人の好み（自分の環境固有の設定）→ ~/.codex/AGENTS.mdに書くと全プロジェクトで共通適用される

ポイントは、フォルダ別のファイルには「そのフォルダ特有の違い」だけを書くことです。ルートと同じことを各フォルダに繰り返し書くと、メンテナンスが破綻します。

AGENTS.mdに書くべき内容

では具体的に何を書けばよいのか。公式や実例で推奨されている構成は、おおむね次の要素です。

概要（Overview）：このプロジェクトが何なのか、技術スタックは何か
コマンド（Commands）：依存関係のインストール・ビルド・テスト・整形（lint）の具体的なコマンド
規約（Conventions）：コーディングスタイル・命名規則・使うライブラリの方針
境界・禁止事項（Boundaries / Never）：触ってはいけないファイル、やってはいけない操作
品質ゲート（Quality gates）：「PR前にテストを通すこと」など、完了条件
確認してほしいこと（Ask first）：勝手に進めず一度相談してほしい作業
参照（References）：詳しい仕様書やドキュメントへのリンク

書き方の実例

難しく考える必要はありません。Codexに対しては、たとえば次のように自然な言葉で頼めば、AGENTS.mdのたたき台を作ってくれます。

「このリポジトリのAGENTS.mdを作ってください。Node.js 20以上を使うこと、依存関係はnpm installで入れること、テストはnpm testで実行し全部通ってからPRを出すこと、を含めてください」

このように頼むと、Codexは中身を理解した上で次のようなファイルを生成します。実際の中身はこんな形です。


## 開発環境
- Node.js 20以上を使う
- 依存関係のインストール: npm install

## テスト
- テスト実行: npm test
- すべてのPRはテストが通っていること

## やってはいけないこと
- 本番環境の設定ファイルは変更しない
- 認証情報をコードに直接書かない

見ての通り、特別な記法はありません。普通の箇条書きで「やってほしいこと」「やってほしくないこと」を書くだけです。生成された内容は必ず人間が目を通し、自社の実態に合わせて手直ししてください。AIが推測で埋めた部分が混じることがあるためです。

書きすぎは逆効果になる（最重要の落とし穴）

ここが、私たちがCLAUDE.md運用で痛感した最大の教訓です。AGENTS.mdは「書けば書くほど良い」ものではありません。むしろ書きすぎると性能が落ちます。

理由は2つあります。1つ目は、AGENTS.mdはセッションのたびに毎回読み込まれるため、長すぎるとAIの「考える容量（コンテキスト）」を圧迫します。容量が埋まるほどAIの出力品質は下がっていきます。2つ目は、曖昧で冗長な指示はかえってAIを混乱させるからです。

たとえば「きれいなコードを書いて」「丁寧にコメントして」のような抽象的な指示は、具体性がなく逆効果とされています。人間にとっても指示が曖昧だと動きにくいのと同じです。

目安は150行程度まで。これを超えそうなら内容を見直す
READMEや他のドキュメントに既にある情報は重複させず、リンクで参照する
抽象論（「良いコードを」等）は書かず、検証可能な具体ルールだけ書く
肥大化してきたら、計画・レビュー・設計などは別ファイルに切り出し、AGENTS.md本体は簡潔に保つ

なお、Codexが読み込むAGENTS.mdには上限サイズもあります。デフォルトでは合計32KiB（約32キロバイト）に達すると、それ以上のファイルは読み込みが打ち切られます。この上限値や挙動はバージョンで変わる可能性があるため、正確な数値は最新の公式情報で確認してください。

私たちの実感として、AGENTS.mdは「最初に大きく書く」のではなく、運用しながら本当に効いたルールだけを残して削っていくのが正解です。AIが繰り返し同じミスをしたときに1行追加し、不要になったら削る。この往復で精度が上がっていきます。

CLAUDE.md運用から翻訳した実務の勘所

私たちが社内のモノレポをCLAUDE.mdで運用してきて、そのままAGENTS.mdにも通用すると確信した勘所をまとめます。

「禁止事項」を最優先で明文化する：触ってほしくないファイル、コミットしてほしくない情報（認証情報や顧客名など）は、最初に明確に書く。これが一番効く
コマンドは正確にコピペ可能な形で：「テストを流して」ではなく実際のコマンドを書く。AIが推測で間違ったコマンドを打つのを防げる
完了条件を書く：「PR前にテストとlintを通すこと」のように、何をもって作業完了とするかを示すと、中途半端な状態で止まらない
ルールは育てるもの：最初から完璧を狙わず、運用で見つかった問題を1行ずつ追記していく

非エンジニアの経営者・管理者の方にとっても、AGENTS.mdの考え方は応用が利きます。これは要するに「業務マニュアルの整備」と同じ営みです。優秀な新人（AI）に渡す指示書を、簡潔に・具体的に・最新に保つ。この運用力そのものが、AI活用の成否を分けます。

よくある質問

AGENTS.mdはどこに置けばいいですか

基本はGitリポジトリの一番上の階層（ルート）に1枚置きます。フォルダごとに異なるルールが必要な場合のみ、そのフォルダにも追加で置きます。自分の環境固有の個人設定は~/.codex/AGENTS.mdに置くと全プロジェクトで共通適用されます。

AGENTS.mdとCLAUDE.mdは何が違いますか

役割は同じ「AIへの指示書」です。AGENTS.mdはOpenAI CodexやCopilot・Cursorなど複数ツールが読む共通フォーマット、CLAUDE.mdはClaude Code向けのファイルです。両方のツールを使う場合は、共通ルールをAGENTS.mdに書き、ツール固有の設定だけをそれぞれのファイルに分ける運用が実用的です。