はじめに

OpenAI Codexは高性能なソフトウェアエンジニアリングエージェントですが、プロジェクト固有の知識がなければ、期待どおりの出力を得られないことがあります。新しいチームメンバーに「この手順で開発してください」とオンボーディング資料を渡すように、Codexにもプロジェクト固有のルールやコンテキストを伝える仕組みが必要です。

それがAGENTS.mdファイルです。

AGENTS.mdは、AIコーディングエージェントへの指示を記述するための標準化されたフォーマットで、OpenAI CodexだけでなくGitHub Copilot、Cursor、Windsurf、Aiderなど多くのAIコーディングツールで共通して利用できます。本記事では、AGENTS.mdの基本的な役割から、効果的な指示の書き方、スコープと優先順位のルールまでを解説します。

AGENTS.mdとは何か

AGENTS.mdは、AIコーディングエージェントに対してプロジェクト固有のコンテキストと指示を提供するためのMarkdownファイルです。READMEが人間向けのドキュメントであるのに対し、AGENTS.mdはエージェント向けの「作業マニュアル」として機能します。

READMEとの役割の違い

ファイル 対象読者 主な内容
README.md 人間の開発者 プロジェクト概要、クイックスタート、貢献ガイドライン
AGENTS.md AIエージェント ビルド手順、テストコマンド、コーディング規約、開発フロー

AGENTS.mdをREADMEと分離することで、以下のメリットが得られます。

  • 予測可能な場所: エージェントが指示を探す明確な場所を提供
  • READMEの簡潔さ維持: 人間向けドキュメントに詳細な開発手順を詰め込む必要がない
  • エージェント特化の指示: 人間には不要だがエージェントには必要な詳細情報を記述可能

広がるエコシステム

AGENTS.mdは、2025年5月のOpenAI Codexリリース以降、急速に普及しています。2026年1月時点で、GitHubには60,000以上のAGENTS.mdファイルがコミットされており、以下のツールが対応しています。

  • OpenAI Codex
  • GitHub Copilot（Coding Agent）
  • Google Jules
  • Cursor
  • Windsurf
  • Aider
  • Zed
  • VS Code

プロプライエタリなフォーマットではなく、オープンな標準として設計されているため、特定のツールにロックインされる心配がありません。

AGENTS.mdの配置場所とスコープ

基本的な配置ルール

AGENTS.mdは、リポジトリ内の任意のディレクトリに配置できます。最も一般的な配置場所はリポジトリのルートディレクトリです。

my-project/
├── AGENTS.md          # プロジェクト全体に適用
├── src/
│   └── components/
├── tests/
└── package.json

発見プロセス

Codexは実行開始時に、以下の順序でAGENTS.mdファイルを検索します。

flowchart TD
    A[Codex起動] --> B[グローバルスコープを確認]
    B --> C{~/.codex/AGENTS.override.md<br/>存在する？}
    C -->|はい| D[グローバルオーバーライドを読み込み]
    C -->|いいえ| E{~/.codex/AGENTS.md<br/>存在する？}
    E -->|はい| F[グローバル設定を読み込み]
    E -->|いいえ| G[グローバル設定なし]
    D --> H[プロジェクトスコープを確認]
    F --> H
    G --> H
    H --> I[Gitルートから現在のディレクトリまで<br/>各階層をチェック]
    I --> J[各階層で AGENTS.override.md → AGENTS.md<br/>の順で検索]
    J --> K[見つかったファイルを連結]
    K --> L[指示チェーン完成]
  1. グローバルスコープ: ~/.codex/AGENTS.override.mdまたは~/.codex/AGENTS.md
  2. プロジェクトスコープ: Gitルートから現在のディレクトリまでの各階層

スコープと優先順位

複数のAGENTS.mdファイルが存在する場合、以下の優先順位ルールが適用されます。

優先度 スコープ 説明
最高 ユーザーのプロンプト Codexへの直接的な指示
高 現在のディレクトリ 作業ディレクトリに最も近いファイル
中 上位ディレクトリ ルートに近いディレクトリのファイル
低 グローバル設定 ~/.codex/AGENTS.md

重要なルール: より深いネスト（現在のディレクトリに近い）のAGENTS.mdファイルが、上位ディレクトリの設定を上書きします。

オーバーライドファイルの使い方

AGENTS.override.mdは、同じディレクトリのAGENTS.mdよりも優先されます。一時的なルール変更やデバッグ時に便利です。

my-project/
├── AGENTS.md              # 通常の設定
├── AGENTS.override.md     # 一時的なオーバーライド（gitignore推奨）
├── services/
│   └── payments/
│       ├── AGENTS.md      # 支払いサービス固有の設定
│       └── AGENTS.override.md  # 支払いサービスの一時的なオーバーライド

AGENTS.mdの基本構造

AGENTS.mdは標準的なMarkdownファイルであり、必須のフィールドや特定のフォーマットは存在しません。ただし、効果的な指示のために以下のセクションを含めることを推奨します。

推奨される構造

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# AGENTS.md

## プロジェクト概要
プロジェクトの目的、アーキテクチャの概要、主要コンポーネントの説明

## 開発環境のセットアップ
依存関係のインストール、環境変数の設定、起動コマンド

## テスト実行方法
単体テスト、統合テスト、E2Eテストの実行コマンド

## コーディング規約
命名規則、ディレクトリ構造、コードスタイル

## PRとコミットのルール
コミットメッセージのフォーマット、PRの作成ガイドライン

## セキュリティ考慮事項
機密情報の取り扱い、禁止事項

コードベースのナビゲーション指示

Codexがプロジェクトを効率的に理解できるよう、コードベースの構造とナビゲーション方法を明記します。

ディレクトリ構造の説明

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

## ディレクトリ構造

プロジェクトは以下の構造に従っています。

- `src/` - アプリケーションのソースコード
  - `components/` - 再利用可能なUIコンポーネント
  - `pages/` - ルーティングされるページコンポーネント
  - `hooks/` - カスタムReact Hooks
  - `services/` - APIクライアントとビジネスロジック
  - `utils/` - ユーティリティ関数
- `tests/` - テストファイル
  - `unit/` - 単体テスト
  - `integration/` - 統合テスト
  - `e2e/` - E2Eテスト
- `docs/` - ドキュメント

主要ファイルの説明

1
2
3
4
5
6

## 主要ファイル

- `src/config/index.ts` - アプリケーション設定の集約
- `src/services/api.ts` - バックエンドAPIクライアントの基底クラス
- `src/store/index.ts` - 状態管理のセットアップ
- `src/types/index.ts` - 共通型定義

パッケージ間のナビゲーション（モノレポ向け）

モノレポ構成の場合、パッケージ間の移動方法を明記すると効果的です。

1
2
3
4
5

## モノレポナビゲーション

- `pnpm dlx turbo run where <package_name>` でパッケージディレクトリに移動
- `pnpm install --filter <package_name>` で特定パッケージの依存関係をインストール
- 各パッケージの `package.json` 内の `name` フィールドでパッケージ名を確認

テスト実行コマンドの指定

AGENTS.mdに記載されたテストコマンドは、Codexによって自動的に実行されます。テストが成功するまでCodexは修正を繰り返すため、正確なコマンドの記載が重要です。

基本的なテストコマンド

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

## テスト

### 全テストの実行
\`\`\`bash
npm test
\`\`\`

### 単体テストのみ
\`\`\`bash
npm run test:unit
\`\`\`

### 統合テストのみ
\`\`\`bash
npm run test:integration
\`\`\`

### E2Eテストのみ
\`\`\`bash
npm run test:e2e
\`\`\`

### 特定のテストファイルを実行
\`\`\`bash
npm test -- --testPathPattern="<pattern>"
\`\`\`

### 特定のテスト名で実行
\`\`\`bash
pnpm vitest run -t "<test name>"
\`\`\`

リンターと型チェック

テストだけでなく、リンターと型チェックのコマンドも記載しておくと、Codexがコード品質を自動的に検証できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

## コード品質チェック

### リンター
\`\`\`bash
npm run lint
\`\`\`

### 型チェック
\`\`\`bash
npm run type-check
\`\`\`

### フォーマット
\`\`\`bash
npm run format
\`\`\`

### 全チェックを一括実行
\`\`\`bash
npm run check-all
\`\`\`

コミット前に必ず `npm run check-all` を実行してください。

CI/CDとの整合性

ローカルで実行するコマンドがCIパイプラインと一致していることを明記すると、Codexの出力がCI失敗を引き起こすリスクを減らせます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

## CI/CD

CIパイプラインは `.github/workflows/ci.yml` で定義されています。
ローカルで以下のコマンドが成功することを確認してからPRを作成してください。

\`\`\`bash
npm run lint
npm run type-check
npm test
npm run build
\`\`\`

プロジェクトのコーディング規約

Codexが生成するコードをプロジェクトのスタイルに合わせるため、コーディング規約を明確に記述します。

命名規則

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

## 命名規則

### ファイル名
- コンポーネント: PascalCase（例: `UserProfile.tsx`）
- ユーティリティ: camelCase（例: `formatDate.ts`）
- 定数: SCREAMING_SNAKE_CASE（例: `API_ENDPOINTS.ts`）
- テスト: `*.test.ts` または `*.spec.ts`

### 変数・関数
- 変数: camelCase
- 定数: SCREAMING_SNAKE_CASE
- 関数: camelCase（動詞から開始）
- クラス: PascalCase
- インターフェース: PascalCase（`I`プレフィックスは使用しない）
- 型: PascalCase

### 禁止パターン
- `any`型の使用は原則禁止
- `var`キーワードは使用しない
- マジックナンバーは定数として定義

コードスタイル

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

## コードスタイル

- TypeScript strictモードを使用
- シングルクォートを使用、セミコロンなし
- インデントは2スペース
- 最大行長は100文字
- 可能な限り関数型パターンを使用

### インポート順序
1. Node.js組み込みモジュール
2. 外部パッケージ
3. 内部パッケージ（`@/`エイリアス）
4. 相対インポート

各グループ間に空行を入れてください。

アーキテクチャパターン

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

## アーキテクチャ

### コンポーネント設計
- プレゼンテーショナルコンポーネントとコンテナコンポーネントを分離
- カスタムフックでロジックを抽出
- コンポーネントは単一責任の原則に従う

### 状態管理
- グローバル状態: Zustand
- サーバー状態: TanStack Query
- ローカル状態: useState/useReducer

### エラーハンドリング
- API呼び出しは必ずtry-catchで囲む
- ユーザー向けエラーメッセージは`src/constants/errors.ts`で定義
- 予期しないエラーはError Boundaryでキャッチ

PRとコミットのルール

Codexが作成するPRやコミットのフォーマットを指定できます。

コミットメッセージ

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

## コミットメッセージ

Conventional Commitsフォーマットに従ってください。

\`\`\`
<type>(<scope>): <subject>

<body>

<footer>
\`\`\`

### type
- feat: 新機能
- fix: バグ修正
- docs: ドキュメントのみの変更
- style: コードの意味に影響しない変更（フォーマット等）
- refactor: バグ修正でも機能追加でもないコード変更
- test: テストの追加・修正
- chore: ビルドプロセスやツールの変更

### scope
変更が影響するモジュール名（例: auth, api, ui）

### subject
- 命令形で記述（"changed"ではなく"change"）
- 最初の文字は小文字
- 末尾にピリオドを付けない

PRの作成ガイドライン

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

## プルリクエスト

### タイトル形式
`[<module>] <簡潔な説明>`

例: `[auth] パスワードリセット機能を追加`

### 本文に含める内容
1. 変更の概要
2. 変更理由
3. テスト方法
4. 影響範囲
5. 関連Issue（あれば）

### チェックリスト
- [ ] テストが通ることを確認
- [ ] リンターエラーがないことを確認
- [ ] 型エラーがないことを確認
- [ ] 必要に応じてドキュメントを更新

実践的なAGENTS.md例

以下は、TypeScript + Reactプロジェクト向けの実践的なAGENTS.md例です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# AGENTS.md

## プロジェクト概要

このプロジェクトは、React + TypeScript + Viteで構築されたWebアプリケーションです。
状態管理にZustand、APIクライアントにTanStack Queryを使用しています。

## セットアップコマンド

依存関係のインストール:
\`\`\`bash
pnpm install
\`\`\`

開発サーバーの起動:
\`\`\`bash
pnpm dev
\`\`\`

## テスト

テストの実行:
\`\`\`bash
pnpm test
\`\`\`

特定のテストを実行:
\`\`\`bash
pnpm vitest run -t "<test name>"
\`\`\`

## コード品質

リンターとフォーマッターを実行:
\`\`\`bash
pnpm lint
\`\`\`

型チェック:
\`\`\`bash
pnpm type-check
\`\`\`

コミット前に必ず `pnpm lint` と `pnpm test` を実行してください。

## コーディング規約

- TypeScript strictモードを使用
- シングルクォート、セミコロンなし
- 関数コンポーネントとカスタムフックを優先
- `any`型の使用は禁止

## ディレクトリ構造

- `src/components/` - UIコンポーネント
- `src/hooks/` - カスタムフック
- `src/services/` - APIクライアント
- `src/stores/` - Zustandストア
- `src/types/` - 型定義

## PRルール

- タイトル形式: `[<module>] <説明>`
- `pnpm lint` と `pnpm test` が通ることを確認
- 変更に対応するテストを追加または更新

グローバル設定とプロジェクト設定の使い分け

グローバル設定（~/.codex/AGENTS.md）

個人の作業習慣やチーム共通のルールは、グローバル設定に記述します。

1
2
3
4
5
6
7

# ~/.codex/AGENTS.md

## 作業規約

- JavaScriptファイルを変更した後は必ず `npm test` を実行
- 依存関係のインストールには `pnpm` を優先
- 本番依存関係を追加する前に確認を求める

プロジェクト設定（リポジトリ内のAGENTS.md）

プロジェクト固有のルールは、リポジトリ内に配置します。グローバル設定を継承しつつ、プロジェクト固有の指示を追加できます。

1
2
3
4
5
6

# AGENTS.md

## リポジトリ規約

- PRを開く前に `npm run lint` を実行
- 動作を変更した場合は `docs/` 内のドキュメントを更新

サブディレクトリでのオーバーライド

特定のチームやサービスに異なるルールが必要な場合、サブディレクトリにAGENTS.mdを配置してオーバーライドします。

1
2
3
4
5
6

# services/payments/AGENTS.override.md

## 支払いサービスのルール

- `npm test`の代わりに `make test-payments` を使用
- APIキーのローテーションはセキュリティチャンネルに通知してから実行

設定の検証とトラブルシューティング

設定の確認方法

Codex CLIを使用して、現在読み込まれている指示を確認できます。

1

codex --ask-for-approval never "現在の指示をまとめてください"

特定のディレクトリでの指示を確認する場合:

1

codex --cd services/payments --ask-for-approval never "アクティブな指示ファイルを表示してください"

よくある問題と解決策

問題 原因 解決策
指示が読み込まれない ファイルが空、または配置場所が間違っている codex statusでワークスペースルートを確認
間違った指示が適用される 上位ディレクトリにAGENTS.override.mdがある オーバーライドファイルを確認し、不要なら削除
フォールバックファイルが無視される 設定にファイル名が登録されていない config.tomlのproject_doc_fallback_filenamesを確認
指示が途中で切れる ファイルサイズが上限を超えている project_doc_max_bytesを増やすか、ファイルを分割

サイズ制限

AGENTS.mdの合計サイズには制限があります（デフォルト32KB）。大規模なプロジェクトでは、以下の対策を検討してください。

  • 指示をサブディレクトリに分散
  • config.tomlでproject_doc_max_bytesを増加
1
2

# ~/.codex/config.toml
project_doc_max_bytes = 65536

まとめ

AGENTS.mdは、Codexの出力品質を大きく向上させる強力なツールです。本記事のポイントを整理します。

  • AGENTS.mdはエージェント向けのREADME: プロジェクト固有のコンテキストと指示を提供
  • 配置場所が優先順位を決定: より深いディレクトリの設定が上位を上書き
  • テストコマンドは自動実行される: 正確なコマンドを記載することで、Codexが品質を自動検証
  • コーディング規約で一貫性を確保: 命名規則やスタイルを明記することで、プロジェクトに馴染むコードを生成
  • グローバルとプロジェクトの使い分け: 個人の習慣はグローバル、プロジェクト固有のルールはリポジトリ内に配置

次回の記事では、フロントエンド、バックエンド、フルスタックなど、プロジェクト構成別のAGENTS.md実践例を詳しく解説します。

参考リンク