Codex CLIにコードを修正してもらうたびに、「npmではなくpnpmを使ってください」「変更後はテストを実行してください」と伝えていないでしょうか。
パッケージ管理ツール、テスト手順、触ってほしくないディレクトリ、依存関係を追加するときの確認などは、タスクが変わっても繰り返し適用したいルールです。毎回プロンプトに書く代わりに、プロジェクトのAGENTS.mdへまとめておけば、Codexが作業前に読み込み、継続的な指示として利用できます。
この記事では細かな設定を網羅するのではなく、次の3つができる状態を目指します。
AGENTS.mdの役割を説明する- 自分のプロジェクトに最小構成のファイルを作る
- Codex CLIが内容を読み込んだか確認する
AGENTS.mdとは？
AGENTS.mdは、Codexなどのコーディングエージェントへ、プロジェクトの構成、開発ルール、実行コマンド、禁止事項、完了条件を伝えるためのMarkdownファイルです。OpenAIの公式ドキュメントでは、「エージェント向けのREADME」のようなものとして説明されています。
Codexは作業を始める前に指示ファイルを探索し、見つけた内容をタスクの依頼とともにコンテキストへ追加します。そのため、たとえば次のようなルールを毎回入力する必要がなくなります。
- 新しいソースファイルにはTypeScriptを使う
npmではなくpnpmを使う- アプリケーションコードの変更後はテストする
- 許可なく本番用の依存関係を追加しない
- 最後に変更内容と確認結果を報告する
AGENTS.mdは、短く具体的で、Codexが実行または確認できる内容にすることが大切です。
README.mdとの違い
ファイル | 主な読者 | 主な目的 |
|---|---|---|
| 人間の開発者・利用者 | プロジェクトの概要、導入方法、使い方を説明する |
| Codexなどのエージェント | 作業時のルール、コマンド、確認方法を伝える |
これは、CodexがREADME.mdを読めないという意味ではありません。Codexは必要に応じてREADMEやほかの文書も参照できます。重要なのは、AGENTS.mdがプロジェクト指示ファイルとして自動的に探索され、作業コンテキストへ組み込まれる点です。
通常のプロンプトとの違い
通常のプロンプトは、今回のタスクを伝える場所です。AGENTS.mdは、同じプロジェクトで繰り返し守ってほしいルールを伝える場所です。
たとえば、次の依頼はプロンプトに向いています。
ログイン画面にパスワード表示切り替えボタンを追加してください。一方、次の内容はAGENTS.mdに向いています。
- Follow the existing patterns in `src/features/`.
- Do not add production dependencies without asking.
- Run `pnpm test` after changing application code.「何を変更するか」はプロンプト、「どのように作業し、何を確認するか」はAGENTS.mdと分けるのが基本です。
なぜAGENTS.mdが必要なのか
同じ説明を繰り返さなくてよい
プロジェクトが同じなら、使用するパッケージ管理ツールやテストコマンドも通常は変わりません。これらをAGENTS.mdへ置けば、タスクを依頼するたびに長い前置きを入力せずに済みます。
プロンプトを短くできるだけでなく、「今回はlintの指示を書き忘れた」といった抜けも減らせます。
Codexの思い込みを減らせる
Codexはリポジトリ内のファイルから技術構成を調べられますが、コードだけでは判断しにくいチーム独自のルールもあります。
npmではなくpnpmを使う- 結合テストの前にDocker Composeを起動する
- 自動生成されたファイルを直接編集しない
- 公開APIを変更したら関連ドキュメントも更新する
- DBスキーマを変更する前に確認を求める
こうした情報を明記すると、Codexが一般的な慣習や推測だけで作業する余地を減らせます。
チームで同じルールを共有できる
リポジトリルートのAGENTS.mdをGitで管理すれば、そのリポジトリでCodexを使うメンバーが同じ指示を共有できます。テスト手順や禁止事項が、個人のプロンプト履歴だけに残る状態を避けられます。
AGENTS.mdはどこに置く？
初心者なら、まずGitリポジトリのルートにAGENTS.mdを1つ置けば十分です。
my-app/
├── AGENTS.md
├── README.md
├── package.json
├── src/
└── tests/Codexはグローバルな指示を確認した後、プロジェクトルートから現在の作業ディレクトリまでの各階層で指示ファイルを探します。階層ごとの指示はルート側から順に結合されるため、作業ディレクトリに近いファイルの内容が後から適用されます。
この仕組みはモノレポで便利ですが、最初から複雑な階層を作る必要はありません。ルートの1ファイルで不足が明確になってから分割しましょう。
個人共通のルールは~/.codex/AGENTS.md
すべてのプロジェクトで使いたい個人的な方針は、Codexのホームディレクトリに置けます。
~/.codex/AGENTS.mdたとえば、次のような内容です。
# Personal preferences
- Explain important design decisions.
- Keep changes focused on the requested task.
- Report commands that failed.チームで共有すべき技術ルールを個人ファイルだけに書くと、ほかのメンバーには適用されません。pnpmの使用や正式なテストコマンドは、プロジェクト側へ置きましょう。
サブディレクトリにも置ける
特定の領域だけに追加ルールが必要なら、そのディレクトリにもAGENTS.mdを置けます。
my-repository/
├── AGENTS.md
└── services/
└── payment/
└── AGENTS.mdルートには共通ルール、services/payment/AGENTS.mdには決済サービス固有のテスト手順を書く、といった使い分けができます。
同じ階層で通常の指示を置き換えるAGENTS.override.mdもありますが、初心者はまずルートのAGENTS.mdを正確に保つことを優先してください。
最小限のAGENTS.mdを書いてみよう
まずは5つのルールだけでよい
次の内容をプロジェクトルートへ保存してみましょう。
# Project rules
## Development
- Use TypeScript for new source files.
- Use `pnpm` instead of `npm`.
## Verification
- Run `pnpm test` after changing application code.
- Run `pnpm lint` before completing the task.
## Restrictions
- Do not add production dependencies without asking.英語で書く必要はありません。チームが読み書きしやすく、意味が明確なら日本語でも利用できます。
使用する技術やツールを指定する
- Use TypeScript for new source files.
- Use `pnpm` instead of `npm`.この2行は、新規ファイルの言語とパッケージ管理ツールを指定しています。既存コードから推測できると考えず、間違えると困る選択は明記しましょう。
ただし、リポジトリに存在しない技術を無理に指定してはいけません。JavaScriptだけのプロジェクトでTypeScriptへ移行する予定がないなら、最初のルールは不要です。
確認コマンドを指定する
- Run `pnpm test` after changing application code.
- Run `pnpm lint` before completing the task.これにより、「コードを変更したら完了」ではなく、「必要なテストとlintも実行したら完了」だと伝えられます。
コマンドだけでなく、いつ実行するかも書きましょう。ドキュメントだけの変更にテストが不要なら、「アプリケーションコードを変更した後」と範囲を限定できます。
勝手にしてほしくないことを書く
- Do not add production dependencies without asking.依存関係の追加、DB変更、公開APIの変更、生成ファイルの直接編集など、影響が大きい操作には確認条件を設けられます。
「大きな変更をしない」のような抽象的な表現より、次のように対象を明示します。
- Ask before adding a production dependency or changing the database schema.
- Do not edit files in `src/generated/` directly.余裕があればプロジェクト構成も追加する
Codexが最初に確認すべき場所を短く案内すると、リポジトリを理解しやすくなります。
## Repository structure
- `src/components/`: UI components
- `src/features/`: Feature-specific logic
- `src/lib/`: Shared utilities
- `tests/`: Automated testsすべてのディレクトリを列挙する必要はありません。役割が分かりにくい場所や、変更時に参照してほしい既存パターンを優先しましょう。
AGENTS.mdを作成する方法
手動で作成する
プロジェクトルートへ移動し、空のファイルを作成します。
cd path/to/my-app
touch AGENTS.mdエディタで開き、実際に使っているルールを記述します。
code AGENTS.md最初はパッケージ管理ツール、テスト、lint、重要な禁止事項だけでも構いません。記載したコマンドがpackage.jsonなどに本当に存在するか確認してください。
/initでひな形を作る
対話型のCodex CLIを対象ディレクトリで起動している場合は、/initでAGENTS.mdのひな形を生成できます。
/init生成結果は完成版ではありません。実際のビルド、テスト、レビュー手順と照合し、誤ったコマンドや不要な説明を修正してください。
Codexが読み込んでいるか確認する
ファイルを作ったら、プロジェクトルートでCodexへルールの要約を依頼します。
codex "このプロジェクトで守るべきルールを要約してください"対話型セッション内なら、次のように入力しても構いません。
現在読み込んでいるプロジェクトルールを一覧にしてください。サンプルを読み込めていれば、回答にはおおむね次の内容が含まれます。
- 新しいソースファイルにはTypeScriptを使う
- npmではなくpnpmを使う
- アプリケーションコードの変更後にテストする
- 完了前にlintを実行する
- 許可なく本番用依存関係を追加しないCodexは実行時、対話型CLIでは通常セッション開始時に指示チェーンを構築します。作成・編集した内容が反映されない場合は、ファイルが対象リポジトリ内にあることと、正しいディレクトリで起動していることを確認し、セッションを開始し直してください。
AGENTS.mdには何を書くべき？
迷ったときは、次の5カテゴリーで考えると整理できます。
カテゴリー | 記述例 |
|---|---|
プロジェクト構成 | 重要なディレクトリ、その役割、参照すべき既存実装 |
実行方法 | 開発サーバー、ビルド、必要な事前準備 |
品質確認 | テスト、lint、型チェックと実行条件 |
開発ルール | 使用言語、命名規則、設計方針 |
禁止・確認事項 | 依存追加、DB変更、公開API変更前の確認 |
最後の報告形式を指定するのも実用的です。
- At the end, summarize changed files and verification results.
- Report any checks that could not be run and explain why.最初から完璧にしない
AGENTS.mdは、プロジェクト全体を説明する設計書ではありません。Codexに繰り返し守ってほしい、具体的で検証可能なルールを書くファイルです。
最初は短く始めましょう。Codexが同じ間違いを繰り返したときや、チームの共通ルールが変わったときに追加します。長さより、現在のリポジトリと内容が一致していることが重要です。
長い背景説明が必要なら、既存ドキュメントへの案内を書けます。
- Read `docs/architecture.md` before changing module boundaries.初心者がやりがちな失敗
抽象的なルールだけを書く
次の指示では、何をすれば完了なのか判断できません。
- Write good code.
- Follow best practices.
- Be careful.実行または確認できる表現へ置き換えましょう。
- Run `pnpm test` and `pnpm lint` before completing the task.
- Follow the existing patterns in `src/features/`.長い設計書をそのまま貼り付ける
大量の背景情報を複製すると、元の文書との不一致が起きやすくなります。作業に必要な要点と、参照すべき文書への案内だけを置きましょう。
実在しないコマンドを書く
pnpm testと書いても、実際のスクリプトがなければ実行できません。package.json、タスクランナー、CI設定と照合し、利用できる正しいコマンドを書きます。
一度作って放置する
パッケージ管理ツール、ディレクトリ構成、CIの確認項目が変われば、AGENTS.mdも更新が必要です。開発手順を変更するときは、AGENTS.mdの更新要否も確認しましょう。
まとめ
AGENTS.mdは、Codex CLIへ継続的なプロジェクトルールを伝えるためのMarkdownファイルです。最初はリポジトリルートに1つ置き、実際に使うコマンド、確認手順、禁止事項を少量から書けば十分です。
# Project rules
- Follow the existing project structure.
- Use the package manager already configured in this repository.
- Run the relevant tests after changing code.
- Do not add dependencies without asking.
- Summarize the changes and verification results.保存したら、プロジェクトルートで次を実行してください。
codex "現在のプロジェクトルールを要約してください"期待したルールが返れば、最初のAGENTS.mdは機能しています。あとはCodexが迷った場面を手がかりに、具体的なルールを少しずつ育てていきましょう。