Codex AGENTS.md完全ガイド｜プロジェクト指示を書く方法
Codexに何度か作業を頼んでいると、「毎回同じ注意事項を書いているな」と感じる場面が出てきます。たとえば、テストコマンド、使っているパッケージマネージャー、コードの書き方、レビュー時に見てほしい観点、勝手に変更してほしくないファイルなどです。
このようなプロジェクト固有のルールを毎回プロンプトに書くのは大変です。そこで使うのが AGENTS.md です。本記事では、Codexに読み込ませるプロジェクト指示としての AGENTS.md の役割、書くべき内容、書きすぎNG、チーム運用の考え方を解説します。
夕宮たいだふぁ……みんな〜、今日はAGENTS.mdだよぉ。毎回のお願いをちょっと楽にする、プロジェクトの説明書を作っていこ〜。
1. AGENTS.mdとは何か
ひとことで：Codexに自動で読ませる、プロジェクト用の作業ルールです。
AGENTS.md は、Codexに対して「このリポジトリではこう作業してください」と伝えるためのMarkdownファイルです。人間向けの README.md がプロジェクト概要や使い方を書く場所だとすると、AGENTS.md はAIエージェント向けに、作業ルールや確認手順を書く場所です。
OpenAI公式のAGENTS.mdガイドでは、Codexは作業前に AGENTS.md を読み込み、グローバルな指示とプロジェクト固有の指示を重ねて扱うと説明されています。つまり、毎回プロンプトに同じルールを書かなくても、Codexの初期文脈として渡せます。
ただし、AGENTS.md は「何でも自動で正しくしてくれる魔法の設定」ではありません。あくまで、Codexが作業するときの前提を揃えるための文書です。最終的な差分確認、テスト、採用判断は人間が行います。
| 役割 | 書く内容の例 |
|---|---|
| 作業前提 | このプロジェクトの目的、主要ディレクトリ、対象読者 |
| 開発コマンド | lint、test、build、format の実行方法 |
| コード規約 | 命名、設計方針、既存パターンの優先 |
| 安全ルール | 秘密情報を扱わない、本番設定を変更しない |
| 完了条件 | 実行すべき確認、報告してほしい内容 |
夕宮たいだプロンプトに毎回書いていた「うちのルール」を、ファイルにして置いておく感じだねぇ。Codex用の引き継ぎメモだよぉ。
2. いつAGENTS.mdを使うべきか
ひとことで：同じ指示を3回以上書いたら、AGENTS.mdに移す候補です。
最初の数回は、プロンプトだけで十分です。小さなREADME修正や、1回きりの調査なら、CX-04で扱った Goal / Context / Constraints / Done when の形で依頼すれば対応できます。
一方で、次のような指示を何度も書いているなら、AGENTS.md に移す価値があります。
- テストは
npm testではなくpnpm testを使う - UI変更時は既存コンポーネントを優先する
- API仕様は
docs/api.mdを確認してから変更する - 画像や記事本文には特定のトーンを守る
- 秘密鍵、環境変数、本番設定は変更しない
- 差分の最後に実行コマンドと確認結果を報告する
ポイントは、「一度きりの依頼」と「毎回守ってほしい前提」を分けることです。AGENTS.md には後者だけを書きます。今回だけの細かい依頼まで入れると、あとで別作業の邪魔になります。
3. CodexはどのAGENTS.mdを読むのか
ひとことで：グローバル設定とプロジェクト設定を、上から順に重ねて読みます。
公式ガイドでは、Codexは起動時に指示のチェーンを作ると説明されています。大まかには、次の順番です。
- Codexホーム配下のグローバル指示
- リポジトリルートのプロジェクト指示
- 現在の作業ディレクトリに近い下位ディレクトリの指示
つまり、全リポジトリ共通の好みは ~/.codex/AGENTS.md に置き、プロジェクト固有のルールはリポジトリ直下の AGENTS.md に置く、という考え方です。さらに、特定のサブディレクトリだけルールが違う場合は、その近くに追加の AGENTS.md や AGENTS.override.md を置けます。
読み込み順をイメージすると、次のようになります。
~/.codex/AGENTS.md
↓
project-root/AGENTS.md
↓
project-root/services/payments/AGENTS.md後ろに読み込まれる指示ほど、作業場所に近い指示です。広いルールは上に、細かいルールは近くに置くと整理しやすくなります。
夕宮たいだほえ〜、ひとつだけじゃなくて、場所ごとに重ねられるんだねぇ。大きなルールと細かいルールを分けられるの、便利だぁ。
4. 最初に書くべき項目
ひとことで：目的、コマンド、規約、安全ルール、完了条件から始めます。
初心者が最初に作る AGENTS.md は、長くする必要はありません。むしろ、短くて実際に守ってほしい内容だけを書く方が有効です。
おすすめの構成は次の5つです。
| 見出し | 目的 |
|---|---|
| Project overview | 何のプロジェクトかを伝える |
| Commands | よく使う確認コマンドを伝える |
| Code style | 既存コードに合わせるための規約を書く |
| Safety | 触ってはいけないものを明示する |
| Done when | 完了報告に含めてほしい内容を書く |
最小テンプレートです。
# AGENTS.md
## Project overview
This repository is a web application for managing user settings.
Prefer existing patterns over introducing new architecture.
## Commands
- Install: `pnpm install`
- Lint: `pnpm lint`
- Test: `pnpm test`
- Build: `pnpm build`
## Code style
- Use TypeScript for new code.
- Keep changes scoped to the requested feature.
- Reuse existing components before creating new ones.
## Safety
- Do not edit production secrets or `.env` files.
- Do not add new dependencies without asking first.
- Do not run destructive commands unless explicitly requested.
## Done when
- Summarize changed files.
- Report commands run and their results.
- Mention any remaining risks or unverified assumptions.この段階では、完璧な文書を目指さなくて大丈夫です。まずは、Codexに何度も伝えている内容を5〜10個だけ入れます。
5. 書きすぎると逆に使いにくくなる
ひとことで：AGENTS.mdは、長さよりも判断しやすさが大切です。
AGENTS.md に何でも書きたくなる気持ちは分かります。しかし、長すぎる指示は、読む側にも使う側にも負担になります。Codexにとっても、重要なルールが埋もれる原因になります。
書きすぎNGの例です。
- READMEと同じプロジェクト説明を大量に貼る
- 今回だけの作業メモを書く
- 古いコマンドを残したままにする
- 「良い感じに」「丁寧に」など、判断しにくい表現だけを書く
- 禁止事項が多すぎて、何をしてよいか分からなくする
- 実際には守っていない理想論を書く
特に注意したいのは、古い情報です。AGENTS.md に古いテストコマンドや廃止されたディレクトリ構成が残っていると、Codexはその前提で作業します。プロジェクトが変わったら、AGENTS.md も更新します。
夕宮たいだ古いルールが残ってると、Codexも迷っちゃうんだぁ。AGENTS.mdは、短くても新しい方がえらいよぉ。
6. 目的別の指示例
ひとことで：プロジェクトの種類に合わせて、Codexが迷いやすい点を書きます。
AGENTS.md の中身は、プロジェクトによって変わります。Webアプリ、ライブラリ、ブログ運営、ゲーム開発では、Codexに守ってほしいことが違うためです。
Webアプリの例です。
## Frontend rules
- Match existing component patterns in `src/components`.
- Do not create a new design system.
- Keep forms accessible with labels and keyboard support.
- When changing UI, mention what viewport sizes were considered.ライブラリ開発の例です。
## Library rules
- Preserve public API compatibility unless the task says otherwise.
- Add or update tests for behavior changes.
- Do not rename exported functions without asking.
- Update documentation when public behavior changes.記事制作やブログ運営の例です。
## Writing rules
- Use a clear explanatory tone in article bodies.
- Keep character dialogue softer and more casual.
- Add internal links to related articles when relevant.
- Do not publish drafts without human review.テスト運用の例です。
## Testing rules
- Run the narrowest relevant test first.
- If a full test suite is expensive, explain which tests were skipped.
- Never claim a command passed unless it was actually run.
- Include failing output summaries when tests fail.こうした例は、そのまま使うより、自分のプロジェクトに合わせて削るのが大切です。Codexに守ってほしい判断基準だけを残します。
7. AGENTS.override.mdの使いどころ
ひとことで：一時的な上書きや、特定領域だけ違うルールに使います。
公式ガイドでは、AGENTS.override.md という上書き用ファイルも説明されています。通常の AGENTS.md を消さずに、一時的な指示や、特定ディレクトリだけの強いルールを置きたいときに使います。
たとえば、支払い処理のディレクトリでは、通常より厳しい安全ルールを置くことがあります。
# services/payments/AGENTS.override.md
## Payments service rules
- Do not change payment provider credentials.
- Do not alter webhook signature verification without review.
- Run payment-specific tests before reporting completion.
- Ask before changing database migration files.ただし、AGENTS.override.md は強い指示として働くため、置きっぱなしに注意します。一時的な上書きなら、作業後に削除または通常の AGENTS.md に統合するかを判断します。
夕宮たいだoverrideは強めの上書きだよぉ。便利だけど、置いたことを忘れると危ないから、使ったら確認しようねぇ。
8. チームで運用するときの考え方
ひとことで：個人の好みとチームの約束を分けます。
チーム開発では、AGENTS.md に何を書くかを決めること自体が大切です。個人の好みをリポジトリ全体のルールにすると、他のメンバーの作業を邪魔することがあります。
分け方の目安です。
| 置き場所 | 向いている内容 |
|---|---|
~/.codex/AGENTS.md | 個人の作業スタイル、報告形式の好み |
リポジトリ直下の AGENTS.md | チーム全員が守るビルド、テスト、設計ルール |
サブディレクトリの AGENTS.md | 特定領域だけのルール |
AGENTS.override.md | 一時的な上書き、強い局所ルール |
チームで使うなら、AGENTS.md もコードレビュー対象にするのがおすすめです。テストコマンド、依存追加の方針、セキュリティ上の注意、公開前チェックなどは、チームの合意が必要な内容です。
逆に、「私は日本語で返答してほしい」「説明は短めが好き」などの個人設定は、グローバル側に置く方が自然です。
9. まずは小さく導入する手順
ひとことで：いきなり完璧を目指さず、既に繰り返している指示から始めます。
初めて AGENTS.md を導入するなら、次の順番がおすすめです。
- 直近のプロンプトを3〜5件見返す
- 繰り返し書いている指示を抜き出す
- リポジトリ直下に
AGENTS.mdを作る - コマンド、規約、安全ルール、完了条件だけを書く
- Codexに「現在の指示を要約してください」と頼んで確認する
- 実際の作業後に、足りないルールだけ追加する
公式ガイドでも、設定後にCodexへ読み込んだ指示を要約させる確認方法が紹介されています。実際に要約してもらうと、想定どおりのファイルが読まれているか、古い指示が混ざっていないかを確認しやすくなります。
確認用の依頼文例です。
現在のプロジェクトで読み込まれているAGENTS.md系の指示を要約してください。
特に、テストコマンド、安全ルール、完了条件がどう解釈されているかを確認したいです。
ファイル変更はしないでください。この確認は、AGENTS.md を追加した直後だけでなく、プロジェクト構成を変えた後にも有効です。
夕宮たいだまずは短いAGENTS.mdでいいんだぁ。使って、直して、また使う。ほら、育てる感じだねぇ。
10. AGENTS.mdに書かない方がいいもの
ひとことで：秘密情報、長すぎる仕様、今回だけの指示は入れません。
AGENTS.md はリポジトリに置くことが多いため、書いてはいけない情報があります。
- APIキー、トークン、パスワード
- 本番環境の接続情報
- 個人情報や顧客情報
- 一時的な作業メモ
- 未確認の推測
- 変更のたびにすぐ古くなる詳細仕様
- Codexに実行してほしくない危険なコマンド例
秘密情報は、AGENTS.md にもプロンプトにも貼らないのが原則です。必要な場合は、環境変数の名前や、確認すべき設定ファイルの場所だけを書きます。
また、巨大な仕様書を丸ごと AGENTS.md に入れるのも避けます。長い仕様は docs/ に置き、AGENTS.md には「仕様変更時は docs/spec.md を確認してください」のように参照先を書きます。
11. AGENTS.mdを育てるチェックリスト
ひとことで：作業で失敗した理由を、次回のルールに変換します。
AGENTS.md は、最初に書いて終わりではありません。Codexとの作業で「次はこうしてほしい」と感じたら、再利用できるルールだけを追加します。
更新時のチェックリストです。
- その指示は今後も繰り返し使うか
- 具体的なコマンドやファイル名にできるか
- 古い情報と矛盾していないか
- チーム全員に適用してよいか
- 安全ルールと完了条件が増えすぎていないか
- READMEやdocsへの参照で済む内容ではないか
良い AGENTS.md は、Codexの出力を完全に固定するものではありません。Codexがプロジェクトの文脈を早く理解し、人間がレビューしやすい形で作業するための補助線です。
12. 次に読む記事
ひとことで：AGENTS.mdで前提を揃えたら、次は外部ツール連携に進みます。
本記事では、Codexの AGENTS.md について、役割、読み込み順、書くべき項目、書きすぎNG、チーム運用、AGENTS.override.md の使いどころを解説しました。
次に読む記事は、CX-08「Codex MCP入門｜外部ツール連携でできること」です。AGENTS.md がプロジェクト内のルールを伝える仕組みだとすると、MCPは外部ツールやデータソースとつなぐための仕組みです。ここから、Codexの活用範囲を少しずつ広げていきます。
公式情報としては、Custom instructions with AGENTS.md、Codex Best practices、Codex Prompting を確認しておくと、AGENTS.md と日々のプロンプトの役割分担を整理しやすくなります。
夕宮たいだふぁ……これでCodexに渡す前提が整ってきたねぇ。次は、外のツールとつなげるMCPを見ていこ〜。
この記事とあわせて読みたいCodex記事
ひとことで：この記事の理解を深めるための関連回です。
- CX-04 Codexプロンプト設計｜Goal・Context・Done whenの書き方
- CX-06 Codex実践ワークフロー集｜調査・修正・レビューの依頼文例
- CX-09 Codex Skills完全ガイド｜作業手順を再利用する方法
- CX-12 Codexベストプラクティス完全ガイド｜失敗しない使いこなし方
Codexシリーズ記事一覧
ひとことで：Codex編は、導入から専門機能まで順番に読めるシリーズです。
- CX-01 Codex入門｜できること・始め方・Claude Codeとの違い
- CX-02 Codex導入ガイド｜App・IDE・CLIの選び方と初期設定
- CX-03 Codexの使い方｜最初に試すプロンプトと安全な進め方
- CX-04 Codexプロンプト設計｜Goal・Context・Done whenの書き方
- CX-05 Codexの権限と安全設定｜承認・サンドボックス・Git管理
- CX-06 Codex実践ワークフロー集｜調査・修正・レビューの依頼文例
- CX-07 Codex AGENTS.md完全ガイド｜プロジェクト指示を書く方法（本記事）
- CX-08 Codex MCP入門｜外部ツール連携の仕組みと安全な使い方
- CX-09 Codex Skills完全ガイド｜作業手順を再利用する方法
- CX-10 Codex Subagents入門｜複数エージェントで並列作業する方法
- CX-11 Codex Cloud・Automations入門｜作業を任せる運用設計
- CX-12 Codexベストプラクティス完全ガイド｜失敗しない使いこなし方
