CodexのAGENTS.mdの書き方｜階層・override・プロジェクトルールの実例

CodexのAGENTS.mdは、プロジェクトの構成、テストコマンド、コード規約、変更してはいけない領域などを、Codexへ継続的に伝えるための指示ファイルです。

1つの大きなAGENTS.mdへすべてを書くより、リポジトリ直下には全体ルール、サブディレクトリにはその領域だけのルールを置く方が管理しやすくなります。Codexは作業ディレクトリまでの階層を順に読み、より近い指示を後から適用します。

この記事では、AGENTS.mdの探索順、AGENTS.override.md、モノレポでの階層設計、実際に使えるテンプレート、ルールが読み込まれないときの確認方法を解説します。

情報確認日：2026年7月11日（日本時間）

結論：全体ルールはルート、領域固有ルールは近いディレクトリへ置く

CodexのAGENTS.mdとは？

AGENTS.mdは、Codexが作業を始める前に読むプロジェクト指示です。毎回のプロンプトへ同じルールを貼らなくても、リポジトリ内の作業方法を共有できます。

書く内容の例です。

• プロジェクトの目的と主要ディレクトリ
• インストール、Lint、型チェック、テスト、ビルドのコマンド
• コード規約と既存パターン
• 変更してよい範囲、変更してはいけない範囲
• 生成ファイル、マイグレーション、依存追加の扱い
• Pull Request前の確認項目
• 秘密情報や本番操作に関するルール

AGENTS.mdの読み込み順

Codexは、個人のグローバル設定と、現在の作業ディレクトリまでにあるプロジェクト指示を順に探索します。

1. ホームディレクトリの~/.codex/AGENTS.override.mdを確認する
2. なければ~/.codex/AGENTS.mdを確認する
3. プロジェクトのルートから現在の作業ディレクトリまで、各階層の指示ファイルを確認する
4. 各階層ではAGENTS.override.md、AGENTS.md、設定したフォールバック名の順に候補を確認する
5. ルート側から作業ディレクトリ側へ結合し、近い指示が後から適用される

repo/
├─ AGENTS.md                 # 全体ルール
├─ apps/
│  ├─ web/
│  │  ├─ AGENTS.md          # フロントエンド固有
│  │  └─ src/
│  └─ api/
│     ├─ AGENTS.md           # API固有
│     └─ src/
└─ packages/
   └─ ui/
      ├─ AGENTS.override.md  # この領域だけ一時的に上書き
      └─ src/

apps/webで作業する場合は、ルートのルールにapps/web/AGENTS.mdが追加されます。互いに矛盾する場合は、より近いディレクトリの指示が優先されるよう設計します。

最初に作るルートAGENTS.md

リポジトリ直下へ、必要最小限の全体ルールを書きます。

# Project instructions

## Repository overview

- `apps/web`: React frontend
- `apps/api`: Node.js API
- `packages/ui`: shared UI components
- `packages/config`: shared TypeScript and ESLint settings

## Setup

- Install dependencies with `npm ci`.
- Do not replace the package manager.
- Do not update dependencies unless the task explicitly requires it.

## Required checks

Run the smallest relevant checks while working.

Before finishing:
1. `npm run lint`
2. `npm run typecheck`
3. Relevant unit tests
4. `npm run build` when build configuration or shared packages change

Report every command and whether it passed.

## Change rules

- Follow existing patterns before introducing a new abstraction.
- Keep changes within the requested scope.
- Do not edit generated files directly.
- Do not modify `.env*`, secrets, deployment credentials, or production data.
- Do not run migrations against shared or production databases.
- Ask before adding a runtime dependency.

## Final response

Include:
- Summary
- Files changed
- Tests run
- Known limitations
- Follow-up work not included

「高品質なコードを書く」のような抽象表現より、「依存追加前に確認する」「最終的に実行するコマンド」の方がCodexの行動を安定させます。

フロントエンド用AGENTS.mdを追加する

apps/web/AGENTS.mdの例です。

# Web application instructions

These rules apply under `apps/web`.

## Architecture

- Use function components and TypeScript.
- Keep server communication in `src/api`.
- Reuse components from `packages/ui` before creating local copies.
- Do not put secrets or privileged API calls in browser code.

## Styling

- Follow the existing CSS Modules naming pattern.
- Do not introduce a new styling library.
- Verify keyboard focus and responsive layout.

## Tests

For component changes:
- Run the closest Vitest test file.
- Add a test for changed behavior.
- Run Playwright smoke tests when navigation, authentication, or checkout changes.

## Browser safety

- Treat API responses as untrusted input.
- Do not use `dangerouslySetInnerHTML` without an existing sanitization utility.
- Do not persist access tokens in localStorage.

このファイルには、APIやDBの詳細を書かず、ブラウザ側に関係するルールだけを置きます。

API用AGENTS.mdを追加する

apps/api/AGENTS.mdの例です。

# API instructions

These rules apply under `apps/api`.

## Request handling

- Validate request params, query, headers, and body at the route boundary.
- Authentication is not authorization. Check resource ownership server-side.
- Return the existing error envelope.
- Do not expose stack traces or secret values.

## Database

- Use existing repository functions.
- Do not execute destructive SQL.
- Do not create or run migrations unless explicitly requested.
- Wrap multi-step writes in the existing transaction helper.

## Logging

- Use the project logger.
- Never log passwords, tokens, cookies, authorization headers, or full request bodies.

## Tests

- Add route tests for success, validation failure, unauthenticated, and unauthorized cases.
- Use test fixtures; do not connect to shared environments.

AGENTS.override.mdは何に使う？

AGENTS.override.mdは、同じ階層の通常のAGENTS.mdより優先する指示です。移行作業、インシデント対応、特定ディレクトリの凍結など、通常ルールを一時的に置き換える場合に使えます。

# Temporary migration rules

This directory is under migration.

- Read files and report findings only.
- Do not edit source code.
- Do not run generators or migrations.
- Do not update snapshots.
- Return a proposed migration plan with affected files and rollback steps.

個人共通のAGENTS.md

~/.codex/AGENTS.mdには、特定プロジェクトに依存しない自分の共通ルールを置きます。

# Personal defaults

- Explain the plan before broad changes.
- Prefer the repository's existing formatter and test framework.
- Never print secret values.
- Do not use destructive git commands.
- Do not push, publish, deploy, or open a pull request unless asked.
- When unsure about a command's side effects, ask first.

チーム共通ルールはリポジトリ側へ置きます。個人設定だけに重要ルールがあると、他の開発者やCI上のCodexで再現されません。

モノレポでの設計方法

ルートには共有事項だけを書く

パッケージマネージャー、全体コマンド、共有禁止事項、変更報告形式などを置きます。

アプリごとにコマンドを分ける

Web、API、モバイル、インフラでテストコマンドが違う場合は、各ディレクトリのAGENTS.mdへ書きます。

近い指示で矛盾を明示する

たとえばルートでは「既存ライブラリを使う」、レガシー領域では「新しい共有ライブラリへ依存しない」のように、例外理由を具体的に書きます。

大量の重複を避ける

共通ルールを各ファイルへコピーすると、更新漏れが起きます。下位ファイルには追加・上書きする内容だけを書きます。

AGENTS.mdへ書かない方がよい内容

• APIキー、パスワード、接続文字列
• 頻繁に変わる担当者名や一時URL
• コードから自動判定できる詳細なフォーマット規則
• 数百行のAPI仕様や社内文書全文
• 相互に矛盾する長い理想論
• 実行すると危険な本番操作の具体的な認証情報

長い手順や専門知識はCodex Skills、外部データはMCP、必ず実行する検査はCIやHookに分けると、AGENTS.mdを短く保てます。

良い指示と曖昧な指示の違い

コマンドは目的と範囲を一緒に書く

リポジトリ全体のテストが重い場合は、作業中と完了時のコマンドを分けます。

## Verification

During implementation:
- Run the nearest test file.
- Run package-level typecheck for the changed workspace.

Before finishing:
- `npm run lint`
- `npm run typecheck`
- `npm run test -- --changed`
- Run the full build only when shared config, package exports, or build files change.

If a command cannot run, report the exact reason. Do not claim it passed.

存在しないコマンドを推測させないため、package.jsonやMakefileを読むよう指示してもよいでしょう。

変更禁止領域を具体的にする

## Protected paths

Do not modify:
- `.env*`
- `secrets/`
- `production/`
- generated API clients under `src/generated/`
- lockfiles unless a dependency change is approved
- database migration history

Do not run:
- `git push`
- `git reset --hard`
- deployment commands
- production database commands

AGENTS.mdは行動指針です。実際に危険操作を防ぐには、CodexのSandbox、Approval、CI権限、秘密管理も設定します。

指示が読み込まれているか確認する

Codexへ次のように質問します。

この作業ディレクトリに適用されているAGENTS.mdの要点を、
ファイルごとに分けて説明してください。

まだファイル変更やコマンド実行はしないでください。

確認する項目です。

• 想定したルートがプロジェクトルートとして認識されているか
• 現在の作業ディレクトリがどこか
• 上位・下位のAGENTS.mdが読み込まれているか
• overrideが通常ファイルを置き換えていないか
• ファイルが空でないか
• 合計サイズの上限を超えて切り捨てられていないか

サイズ上限とフォールバック名

Codexは読み込むプロジェクト指示の合計サイズに上限を設けています。初期値は設定で変更でき、project_doc_max_bytesで調整できます。長くする前に、Skillsや通常のドキュメントへ分割できないか検討してください。

組織で別のファイル名を使っている場合は、設定でフォールバック候補を追加できます。ただし、標準のAGENTS.mdを使う方が、開発者とツールの両方に伝わりやすくなります。

AGENTS.mdとCodex Skillsを使い分ける

レビュー時のチェックリスト

• 新しいルールは全体か特定ディレクトリだけか
• 既存の上位ルールと矛盾していないか
• コマンドが実際に存在し、ローカルで安全に実行できるか
• 秘密情報や個人情報が含まれていないか
• プロンプトではなくCIや権限で強制すべき内容ではないか
• 長い説明をSkillやdocsへ移せないか
• 期限切れのoverrideが残っていないか

あわせて読みたい記事

• Codex Skillsおすすめ
• CodexのSandbox・Approval設定
• Gitのブランチの使い方

よくある質問

まとめ

CodexのAGENTS.mdは、プロジェクトの作業方法を階層的に伝えるためのファイルです。ルートには共有ルール、各ディレクトリには追加・上書きする固有ルールだけを置くと、モノレポでも管理しやすくなります。

指示は、実在するコマンド、対象パス、禁止操作、完了報告の形式まで具体化してください。長い手順はSkills、強制すべき検査はCI、危険操作の防止はSandboxとApprovalへ分けることで、AGENTS.mdを短く、実行可能なルールとして保てます。

参考リンク

• OpenAI Codex – Custom instructions with AGENTS.md
• OpenAI Codex – Basic configuration
• OpenAI Codex – Advanced configuration
• OpenAI Codex – Skills
• OpenAI Codex – Best practices