AGENTS.mdとは？Codexにルールを伝えるための指示書
AGENTS.md とは、AI コーディングエージェントに対して「このプロジェクトではこう動いてほしい」という指示をまとめた Markdown ファイルです。人間の開発者が README（プロジェクトの説明書）を読んでから作業に入るのと同じように、Codex はこのファイルを読み込んでからコードを書き始めます。
ファイル名は大文字の AGENTS.md で統一されており、リポジトリのルートなどに置いておくだけで Codex が自動的に参照します。特別なコマンドや拡張子は不要で、中身は普通の Markdown で書けます。
関連記事：Codexとは？OpenAIのAIエージェントの仕組み・使い方・作り方を整理
AGENTS.mdの役割｜Codex向けの「プロジェクト説明書」
AGENTS.md の役割は、プロジェクト固有の前提を AI エージェントに先に伝えておくことです。使う言語やフレームワーク、ビルド・テストの実行方法、コミットメッセージの書き方といった「チームの暗黙のルール」を文章にしておくと、Codex はそれに沿ってコードを生成します。
人間にとっての README が「このプロジェクトは何か」を説明するのに対し、AGENTS.md は「このプロジェクトでどう作業すべきか」を AI 向けに説明するファイルだと考えると分かりやすいです。両者を分けることで、人間向けのドキュメントを AI 向けの指示で汚さずに済みます。
なぜAGENTS.mdが必要なのか
AGENTS.md がないと、Codex はプロジェクトの事情を知らないまま、一般的なやり方でコードを書きます。その結果、命名規則がばらついたり、使っていないライブラリを勝手に導入したりと、レビューで指摘する手間が増えていきます。
規約を毎回プロンプトに書いて伝える方法もありますが、会話のたびに同じ説明を繰り返すのは非効率です。AGENTS.md に一度書いておけば、チーム全員の Codex が同じルールを参照するようになり、生成結果のばらつきとレビューコストを同時に抑えられます。
AGENTS.mdに書く設定｜記述すべき内容と避けたい内容
AGENTS.md の設定でもっとも迷うのが「何を書けばよいか」です。基本の考え方はシンプルで、新しくチームに入った開発者に最初に伝えたいことを、そのまま書けば十分です。網羅性よりも、AI が判断に迷いやすいポイントを優先して書くのがコツです。
書いておきたい内容
Codex が手戻りなく作業するために、次のような項目を書いておくと効果が出やすいです。いずれも「このプロジェクト特有のルール」に絞るのがポイントになります。
- プロジェクト概要（何を作っているか、主要なディレクトリ構成）
- コーディング規約（命名規則、フォーマッタ、使用を避けたい書き方）
- ビルド・テストコマンド（
npm testなど、変更後に必ず実行してほしいもの） - コミット・プルリクエスト（PR、変更内容をまとめてレビュー依頼する単位）の書き方
- セキュリティ上の注意（触ってはいけないファイル、扱いに気をつける情報）
これらを箇条書きと短い説明で書いておくと、Codex は作業の前提として読み取ってくれます。特に「変更後に必ずテストを実行する」といった手順は、明文化しておくと品質が安定します。
書かないほうがよい内容
一方で、AGENTS.md に詰め込みすぎると逆効果になります。ファイルが長くなるほど Codex が重要な指示を見落としやすくなり、かえって精度が落ちることがあるためです。次のような内容は避けるか、別の場所に分けるのが無難です。
- 長大な仕様書や設計ドキュメント（必要なら別ファイルに分けてリンクする）
- API キーやパスワードなどの機密情報
- めったに変わらない一般的な技術解説（一般論は AI も既に知っている）
- 自動生成される巨大なログやデータ
実際の AGENTS.md は、次のような骨格から始めると書きやすいです。最初から完璧を目指さず、運用しながら育てていく前提で作ります。
### プロジェクト概要
ECサイトのフロントエンド。Next.js + TypeScript。
### コーディング規約
- コンポーネントは関数コンポーネントで書く
- 型は any を避け、明示的に定義する
### ビルド・テスト
- 変更後は必ず `npm run test` と `npm run lint` を実行する
### コミット・PR
- コミットメッセージは日本語、1行目に要約を書く
AGENTS.mdの配置場所と階層構造（Cascading Rules）
AGENTS.md は 1 か所だけでなく、複数の場所に置いて使い分けられます。これは「全体に効かせたいルール」と「特定のディレクトリだけに効かせたいルール」を分けるためのしくみで、Cascading Rules（段階的に適用されるルール）と呼ばれます。
代表的な配置場所は次の 3 種類です。それぞれ適用される範囲が異なります。
| 配置場所 | 適用範囲 | 主な用途 |
|---|---|---|
| ホーム配下（`~/.codex/AGENTS.md`） | 自分が扱う全プロジェクト共通 | 個人の好み、共通の作業スタイル |
| リポジトリのルート | そのリポジトリ全体 | チーム共通の規約、ビルド・テスト手順 |
| サブディレクトリ | その配下のみ | 特定モジュール固有のルール |
このように層を分けておくと、共通ルールはルートにまとめつつ、例外的な事情はサブディレクトリ側で上書きできます。たとえばリポジトリ全体は TypeScript でも、特定の検証用ディレクトリだけは別の方針にしたい、といった調整がしやすくなります。
優先順位とマージのされ方
複数の AGENTS.md が見つかった場合、Codex はそれらを破棄し合うのではなく、組み合わせて読み込みます。基本の考え方は「より近い場所にあるファイルが優先される」ことです。作業対象のファイルに近いサブディレクトリの指示が、ルートの指示よりも優先して反映されます。
そのため、ルートには変わりにくい全体ルールを置き、変化しやすい個別事情はサブディレクトリに置くと、運用が安定します。優先順位を意識して階層を設計しておくことが、AGENTS.md を増やしても破綻させないコツです。
Codex CLIでAGENTS.mdが読み込まれる仕組み
Codex CLI（コマンドラインから Codex を操作するツール）を使うと、AGENTS.md がどう効いているかを把握しやすくなります。Codex は作業を始めるときに、ホーム配下・リポジトリルート・作業中ディレクトリの AGENTS.md を探し、見つかったものをまとめて前提知識として読み込みます。
読み込まれた指示は、その後の生成や修正の方針に反映されます。たとえば「変更後にテストを実行する」と書いておけば、Codex はコードを直したあとにテストコマンドを走らせようとします。書いた指示が効いているか不安なときは、簡単なタスクを与えて、規約どおりに動くかを試すと確認できます。
なお、Codex には AGENTS.md とは別に ~/.codex/config.toml という設定ファイルもあります。こちらは承認モードやモデルの選択といった Codex 自体の動作設定を担うもので、プロジェクトの規約を伝える AGENTS.md とは役割が異なります。AGENTS.md は「プロジェクトでどう作業してほしいか」、config.toml は「Codex をどう動かすか」と覚えておくと混同せずに済みます。読み込みの順序としては、グローバル設定から始まり、リポジトリルート、作業中ディレクトリの順に近い場所のファイルが重ねて反映されます。
うまく反映されない場合は、指示が長すぎて埋もれていないか、表現が曖昧でないかを見直します。「きれいに書く」のような抽象的な指示よりも、「1 関数は 50 行以内にする」のように具体的な基準で書くほうが、AI には伝わりやすくなります。
関連記事：Codex CLI とは？できること・料金・Claude Code との違いを整理
AGENTS.mdとSkills・CLAUDE.mdの違い
AGENTS.md と混同しやすいものに、Codex の Skills や、別の AI エージェント向けの CLAUDE.md があります。役割が重なる部分もありますが、目的が異なるため整理しておきましょう。下表は、適用のされ方と主な用途で 3 つを比べたものです。いずれも AI に指示を渡すしくみですが、「常に効く前提」か「特定の場面で呼び出すもの」かで性質が分かれます。
| 観点 | AGENTS.md | Skills | CLAUDE.md |
|---|---|---|---|
| 位置づけ | 常に適用されるチームの指示 | 特定の状況で発動する再利用可能な手順 | 別エージェント（Claude 系）向けの指示ファイル |
| 適用のタイミング | 作業開始時に常に読み込まれる | 必要なときに呼び出して使う | 対応するエージェント利用時に読み込まれる |
| 主な用途 | 規約・ビルド手順などの前提共有 | 定型ワークフローの部品化 | 同じ目的を別ツールで実現 |
ざっくり言えば、AGENTS.md は「いつも守ってほしい約束ごと」、Skills は「必要なときに取り出す道具」です。CLAUDE.md は名前のとおり Claude 系のツール向けで、AGENTS.md と書く内容は近いものの、参照するエージェントが異なります。複数のツールを併用する場合は、後述するように内容を共通化しておくと管理が楽になります。
関連記事：Codex Skills とは？AIに業務手順を覚えさせる仕組みと使い方を解説
AGENTS.mdを長く運用するためのコツ
AGENTS.md は一度書いて終わりではなく、プロジェクトの変化に合わせて育てていくファイルです。放置すると実態と合わなくなり、かえって誤った指示で AI を縛ってしまいます。長く使い続けるための運用のコツを 3 つの観点で整理します。
長くなりすぎを防ぐ
もっとも起きやすい失敗が、AGENTS.md の肥大化です。あれもこれもと書き足すうちにファイルが長くなり、肝心の指示が埋もれて Codex に伝わりにくくなります。詳しい背景説明や設計の経緯は、docs/ などの別ディレクトリに切り出し、AGENTS.md からは要点とリンクだけを残すと読みやすさを保てます。
目安として、AGENTS.md 本体は「ざっと目を通せる長さ」に収めると安全です。書き足したくなったら、まず既存の記述で代用できないかを考えると、肥大化を防げます。
CLAUDE.mdなど他ツールとの共通化
Codex と Claude 系ツールを併用していると、AGENTS.md と CLAUDE.md の二重管理が負担になります。この場合、共通のルールは 1 つのファイルにまとめ、もう一方からはそれを参照する形にすると、内容のずれを防げます。ツールごとに毎回同じ規約を書き直す必要がなくなり、更新漏れも起こりにくくなります。
完全に統一できない部分は、各ファイルにツール固有の差分だけを書きます。共通部分と差分を分けておくのが、複数エージェントをまたいで運用する際の基本です。
いつ・どう更新するか
更新のきっかけは、「同じ指摘を繰り返している」と気づいたときです。Codex の生成結果を直すたびに同じ修正をしているなら、その内容を AGENTS.md に書き足せば、次からは自動で守られるようになります。レビューでの指摘を AGENTS.md に反映していくサイクルを回すと、ファイルが自然と実態に近づきます。
逆に、使われていない古い指示は思い切って削ります。更新を特別な作業にせず、日々のレビューの延長で少しずつ直していくのが、長く運用する現実的なやり方です。
Codexを業務に取り入れるときに陥りがちな3つの落とし穴
AGENTS.md を整えたうえで Codex を業務に取り入れていく際、つまずきやすいポイントがあります。多くの導入の現場で見られる 3 つの落とし穴と、その避け方を整理します。
落とし穴1 いきなり全てをやろうとする
最初から全プロジェクト・全工程に AI を適用しようとすると、AGENTS.md も巨大になり、設定だけで疲れてしまいます。まずは 1 つのリポジトリ、1 つの作業から始めるほうが確実です。
落とし穴2 壮大な方針から考えて手が止まる
「AI 活用の全体設計をしてから」と考え始めると、検討ばかりが続いて実際の導入が進みません。完璧な設計を待たず、小さく試して学びながら整えるほうが、結果的に早く前に進めます。
落とし穴3 既製のチャット型AIでは業務フローに組み込めない
汎用のチャット型 AI は手軽ですが、自社のリポジトリ構成や規約に合わせた作業までは任せきれません。AGENTS.md のようにプロジェクト前提を読み込ませて初めて、実際の開発フローに組み込めるレベルになります。
スモールスタートで1業務をAIに任せる
これらの落とし穴に共通する対策は、スモールスタートです。まず 1 つの業務やリポジトリに絞って Codex と AGENTS.md を試し、効果を確かめてから対象を広げると、無理なく定着します。GiftX では、こうしたスモールスタート前提の AI エージェント構築を 1 業務単位から伴走支援しています。詳細は AIエージェント構築支援サービス をご覧ください。
AGENTS.mdに関するよくある質問
最後に、AGENTS.md を使い始める際によく出る疑問をまとめます。
AGENTS.md は必須ですか？
必須ではありませんが、あると生成結果のばらつきとレビューの手間を減らせます。小規模なプロジェクトでも、ビルド・テストコマンドだけ書いておくと効果を感じやすいです。
書き始めは何から手をつければよいですか？
プロジェクト概要・コーディング規約・ビルドとテストの実行方法の 3 点から始めるのがおすすめです。運用しながら、繰り返し指摘している内容を足していくと無理がありません。
AGENTS.md はいつ更新すべきですか？
Codex の生成結果に同じ修正を繰り返していると気づいたときが更新のタイミングです。その内容を書き足せば、次回以降は自動的に守られるようになります。
複数の階層に置いても大丈夫ですか？
問題ありません。ルートに全体共通のルール、サブディレクトリに個別の事情を置くと使い分けられます。作業対象に近いファイルの指示が優先されます。
まとめ
AGENTS.md は、Codex にプロジェクトの前提とルールを伝え、生成結果を自社の規約に沿わせるための設定ファイルです。書くべきはプロジェクト固有の規約・ビルド/テスト手順・PR ルールで、機密情報や長大なドキュメントは避けます。配置場所と優先順位を理解し、肥大化を防ぎながらレビューの延長で更新していくと、長く使えるファイルになります。
重要なのは、最初から完璧な設定を目指さないことです。まず 1 つのリポジトリと 1 つの業務から、スモールスタートで Codex と AGENTS.md を試し、効果を確かめながら対象を広げていくのが、もっとも着実な進め方です。
AI活用の伴走支援をご検討の方へ
本記事で紹介した AGENTS.md や Codex の活用を、自社の業務でも具体的に進めたい・相談したいとお考えの方は、ぜひ GiftX AIエージェント構築支援までお問い合わせください。
GiftX AIエージェント構築支援では、貴社の業務に合わせて1業務単位のスモールスタートから本番運用まで、AIエージェント構築をワンストップで支援します。ユースケースの洗い出しから、PoC、本番運用、社内ナレッジ化まで伴走します。
AI活用にご関心のある方は、ぜひ一度ご相談ください。
▶ GiftX AIエージェント構築支援の詳細・お問い合わせはこちら
