AGENTS.mdは、マルチエージェントAIワークフローを実行する人にとって静かに必須インフラになりつつある新しい規約です。シングルエージェントプロジェクトにCLAUDE.mdを使ってきた方なら、AGENTS.mdはそのパターンをより難しい問題に拡張するものです：複数のAIエージェントが同じコードベースで、場合によっては同時に、異なる役割で実行されているとき何が起きるか？
このガイドでは、AGENTS.mdとは何か、CLAUDE.mdとどう違うか、そしてノイズを追加するのではなくマルチエージェントワークフローを実際に改善するAGENTS.mdの書き方を説明します。
AGENTS.mdとは（そして何でないか）
AGENTS.mdは、AIコーディングエージェント——特にCodex、OpenAIのエージェントシステム、そしてClaudeCodeも——がコードベースに触れる前に読む指示ファイルです。本番コードに触れる前に新しいコントラクターに渡すブリーフィングドキュメントだと考えてください。
ファイルは3つの目的を果たします：
- 役割の明確化 — 各エージェントが担当することと触れるべきでないことを伝える
- ワークフローの調整 — エージェントが共有リソース、テストスイート、デプロイをどう処理すべきかを説明
- 環境の事実 — ビルドコマンド、テストランナー、リンティング設定、ファイル規約
CLAUDE.mdとの実際の違い：CLAUDE.mdは主にClaude Code用のプロジェクトコンテキストファイルです。プロジェクトの歴史、規約、ルールを含むプロジェクトをClaudeに説明します。AGENTS.mdはより明示的に調整ドキュメントです——複数のエージェントがそれを読む可能性を前提に書かれ、役割ベースのシナリオを処理する必要があります。
実際には、多くのチームが両方を使います。CLAUDE.mdはClaude固有の設定（hooks、ツール、メモリ設定）を処理し、AGENTS.mdは共有マルチエージェント調整レイヤーを処理します。
良いAGENTS.mdの解剖
ファイルに何を、どの順序で含める必要があるかを見てみましょう。
1. 必須コマンドブロック
すべてのAGENTS.mdはコマンドブロックから始まるべきです。これはエージェントがリポジトリで作業するたびに毎回必要とするもので、最高優先度のセクションです。
## コマンド
- **ビルド**: `npm run build`
- **テスト**: `npm test`
- **リント**: `npm run lint`
- **フォーマット**: `npm run format`
- **型チェック**: `npm run typecheck`
- **開発サーバー起動**: `npm run dev`明白に見えますが、ほとんどのチームが犯す間違いはこの情報をREADMEに埋めるか完全に省略することです。エージェントはREADMEを確実に読みません。AGENTS.mdを読みます。コマンドを前に置いてください。
モノリポの場合はより具体的に：
## コマンド
指定がない限りリポジトリルートから実行。
- **全パッケージビルド**: `pnpm run build --recursive`
- **単一パッケージビルド**: `cd packages/api && pnpm run build`
- **全テスト**: `pnpm run test --recursive`
- **単一パッケージテスト**: `cd packages/api && pnpm test`
- **リント**: `pnpm run lint`（全パッケージにESLintを実行）
- **型チェック**: `pnpm run typecheck`（プロジェクト参照を使用）
`npm` コマンドは実行しない——このリポジトリはpnpmワークスペースを使用。最後の行が重要です。指定しなければエージェントはデフォルトで npm を使います。
2. ファイル規約とプロジェクト構造
エージェントはどこに何があるか、なぜそこにあるかを理解する必要があります。なければ、コード検査だけでは明らかでない規約を破って間違った場所にファイルを作成します。
## プロジェクト構造
src/ api/ # Expressルートハンドラー — リソースごとに1ファイル services/ # ビジネスロジック — ここはDB接続なし repositories/# すべてのデータベースクエリはここ models/ # TypeScript型とZodスキーマ utils/ # 副作用のない純粋関数のみ tests/ unit/ # src/構造をミラー integration/ # 実際のDBに接続するテスト e2e/ # Playwrightテスト
**重要なルール:**
- ServicesはRepositoriesから直接インポートしない——サービスコンストラクター経由の依存性注入を使用
- Repositoryファイルはビジネスロジックを含まない
- トップレベルに `utils.ts` ファイルを追加しない——適切なサブディレクトリを見つける「重要なルール」パターン——エージェントが間違えることを明示的にフラグ——は包括的なドキュメントより有用です。エージェントはギャップを埋めるのが得意です。ガードレールが必要であり、手取り足取りの指示ではありません。
3. テスト要件
ここがほとんどのAGENTS.mdが不足する場所です。「新しいコードにテストを書く」のようなあいまいな文はエージェントには機能しません。どのカバレッジが必要か、どのテストファイルを実行するか、何がパスしたとみなされるかを具体的に説明してください。
## テスト
**変更を送信する前に：**
1. フルテストスイートを実行: `pnpm test`
2. 新しいリントエラーがないことを確認: `pnpm lint`
3. 型チェックがパス: `pnpm typecheck`
**新機能の場合:** `src/` と同じファイルパス構造を使って `tests/unit/` にテストを書く。`src/services/invoices.ts` の新しいファイルには `tests/unit/services/invoices.test.ts` のテストが必要。
**バグ修正の場合:** 修正前にバグを再現する回帰テストを追加する。
**統合テスト（`tests/integration/`）:** 実際のPostgreSQLインスタンスに接続する。CIで実行されるが、ローカルでは低速。データベースクエリまたはRepositoryコードを変更した場合のみ `pnpm test:integration` で実行。
**テスト設定ファイルを変更しない**（`jest.config.ts`、`playwright.config.ts`）——明示的な承認なしに。最後の行——テスト設定を変更しない——はほぼすべてのAGENTS.mdに必要です。エージェントはテストが失敗すると設定を「修正」しようとする傾向があり、これがはるかに大きな問題に連鎖することがあります。
4. リンターを超えたコードスタイル
リンターはフォーマットと構文を検出します。AGENTS.mdはそれ以外のすべてを処理します。
## コードスタイル
**TypeScript:**
- オブジェクト形状には `type` より `interface` を使う
- `any` の代わりに `unknown` を使う——`any` が必要なら `// eslint-disable-next-line @typescript-eslint/no-explicit-any` コメントと正当化を追加
- 非同期関数には明示的な戻り型アノテーションが必要
- ネストの深さを減らすためにearly returnを使う
**命名:**
- ファイル: `kebab-case.ts`
- Reactコンポーネント: `PascalCase.tsx`
- 変数と関数: `camelCase`
- データベースカラム: `snake_case`（ORMマッパーが処理、手動変換しない）
- 定数: `SCREAMING_SNAKE_CASE`（環境変数のみ）
**インポート:**
- 順序: 組み込み → 外部パッケージ → 内部モジュール → 相対インポート
- src/のインポートにはパスエイリアス（`@/services/...`）を使う——`../../../`チェーンなし
**エラーハンドリング:**
- エラーをサイレントに飲み込まない
- 型付きエラーを使う——エラークラス階層は `src/errors/` を参照
- 再スローする前にコンテキスト付きでエラーをログスタイルルールはポジティブな文（「Xを使う」）として明確な論拠とともに書かれることに注意。これはリンティングルール——エージェントが絶対的な制約として解釈する——とは異なります。スタイルルールは設定ファイルではなく、シニア開発者のガイダンスのように感じるべきです。
5. エージェントが決してやってはいけないこと
これは最も過小評価されているセクションです。エージェントは一般的に依頼されたことをやるのが得意ですが、何を避けるべきかを知ることは信頼性が低いです。
## 制限事項
**決してやってはいけないこと:**
- `main` または `release/*` ブランチに直接コミット
- `migrations/` のファイルを変更——新しいマイグレーションファイルのみ作成
- 対応するマイグレーションなしにデータベーススキーマを変更
- 最初に確認せずにファイルを削除
- 既存の代替を確認せずに `package.json` に新しい依存関係を追加
- ユニットテストでネットワークリクエストを作成——`tests/mocks/` のモックを使う
- 認証情報、APIキー、環境固有の値をハードコード
**承認が必要なこと:**
- 新しいデータベースインデックスを追加
- 既存のAPIレスポンス形状を変更
- 認証または認可ロジックを変更
- 破壊的変更を含む依存関係を更新2段階の構造（「決してやってはいけないこと」vs「承認が必要」）は防ぎたい2つのタイプのミスに対応します：壊滅的なものと、ループに人間が必要な元に戻せるもの。
マルチエージェント調整のためのAGENTS.md
シングルエージェントのAGENTS.mdは洗練されたCLAUDE.mdのように見えます。複数のエージェントが同時に実行されるとき、興味深い課題が現れます。
役割ベースのセクション
マルチエージェント調整で最も効果的なパターンは、明示的な役割セクションを持つAGENTS.mdを構成することです：
## 役割
### オーケストレーターエージェント
責任:
- ユーザーリクエストをサブタスクに分解
- スペシャリストエージェントに委任
- 結果の集約と競合の処理
- あいまいなケースの最終意思決定
オーケストレーターがやってはいけないこと:
- コードを直接書く（コーディングエージェントに委任）
- テストスイートを実行（テストエージェントに委任）
- 一方的にデプロイを決定
### コードエージェント
責任:
- オーケストレーターからのスペックに基づいた機能実装
- 既存コードのバグ修正
- 新しいコードのユニットテスト作成
- スタイル要件を満たすためのコードリファクタリング
境界:
- CI/CD設定を変更しない
- ドキュメントを更新しない（オーケストレーターに委任）
- アーキテクチャ決定をしない——オーケストレーターにエスカレート
### レビューエージェント
責任:
- プロジェクト標準に対するコードレビュー
- セキュリティスキャン
- パフォーマンス分析
- レビューレポートの生成
境界:
- コードを直接変更しない——所見のみを報告
- パイプラインをブロックしない——人間のレビューのための問題をフラグ共有状態の処理
マルチエージェント調整での最も難しい問題は共有状態です。同じファイルに同時に書き込む複数のエージェントはそれを破損させます。
## 共有状態の規約
**ファイルロック:** 共有設定ファイル（`config/app.ts`、`package.json`）を変更する必要がある場合は、同じディレクトリの `.lock` ファイルを探して別のエージェントが現在変更中かどうか確認。編集前にロックファイルを作成し、後で削除。
**Gitの規律:** 変更を行う前に必ずpull。小さな単位で頻繁にコミット。大量の変更を数分以上コミットせずに保持しない。
**ステートファイル:** 以下のファイルは競合が高い——ミューテックスが必要なように扱う:
- `src/routes/index.ts`（すべてのエージェントがここにルートを追加）
- `src/models/index.ts`（すべてのエージェントがここにモデルエクスポートを追加）
- `package.json`
これらのファイルに追加するときは最低限の変更を行い、すぐにコミット。エスカレーションプロトコル
マルチエージェントシステムには、エージェントが処理できないものに遭遇したときの明確なプロトコルが必要です：
## エスカレーション
オーケストレーター（またはユーザー）にエスカレートするとき:
1. タスクが10以上のファイルの変更を必要とする
2. 説明できないテスト失敗に遭遇した
3. 仕様があいまいでパブリックAPIに影響する
4. 新しい依存関係を追加する必要がある
5. コードベースのどこかがこの指示と矛盾している
エスカレーションの方法:
- 作業を中止（部分的な作業をコミットしない）
- 何をしていたか、何を発見したか、なぜエスカレートするかの簡単なサマリーを書く
- 問題に関連する具体的なファイルと行番号を含める
- 進む前に説明を待つAGENTS.md vs CLAUDE.md: 実際の違い
両方を使う場合、何をどこに書くか：
| 懸念事項 | CLAUDE.md | AGENTS.md |
|---|---|---|
| Claude固有ツール（WebSearch、Bash） | はい | いいえ |
| フック設定 | はい | いいえ |
| ビルドコマンド | はい | はい |
| コードスタイルルール | はい | はい |
| マルチエージェント役割 | いいえ | はい |
| 調整プロトコル | いいえ | はい |
| セキュリティ境界 | 両方 | 両方 |
| プロジェクト履歴/コンテキスト | はい | いいえ |
| ファイル命名規約 | 両方 | 両方 |
CLAUDE.mdはAGENTS.mdを参照できます：
# CLAUDE.md
このプロジェクトはマルチエージェント設定を使います。調整ルールはAGENTS.mdを読んでください。
Claude固有の設定については:
- フック: `.claude/settings.json` を参照
- カスタムコマンド: `.claude/commands/` を参照AGENTS.mdもCLAUDE.mdを参照できます：
# AGENTS.md
あなたがClaude Codeの場合は、Claude固有の設定のためにCLAUDE.mdも読んでください。
一般的なエージェントルールは以下の通りです。実際のAGENTS.mdパターン
最小限のAGENTS.md（単一開発者プロジェクト）
# AGENTS.md
## ビルド＆テスト
- インストール: `npm install`
- ビルド: `npm run build`
- テスト: `npm test`（Jestを実行）
- リント: `npm run lint`（ESLint + Prettier）
- 型チェック: `npm run tsc`
変更を送信する前にこれらすべてを実行する。
## ルール
- TypeScript strictモードが有効。`any` なし。
- 新しいAPIエンドポイントは `src/__tests__/api/` にテストが必要。
- 環境変数は `.env.example` に（実際の値は絶対コミットしない）。
- `drizzle.config.ts` または `migrations/` のファイルを変更しない。小さく、集中的で、本当に有用。包括的なドキュメントを書きたくなる誘惑があります。抵抗してください——エージェントは包括的ではなく正確なものが必要です。
チームのAGENTS.md（中規模コードベース）
# AGENTS.md
## クイックリファレンス
| タスク | コマンド |
|---|---|
| インストール | `pnpm install` |
| ビルド | `pnpm build` |
| テスト | `pnpm test` |
| リント | `pnpm lint` |
| フォーマット | `pnpm format` |
| DBマイグレーション | `pnpm db:migrate` |
## 3層アーキテクチャ
1. **Routes**（`src/routes/`）— リクエストのバリデーションとレスポンスフォーマットのみ
2. **Services**（`src/services/`）— ビジネスロジック、DB接続なし
3. **Repositories**（`src/repositories/`）— データベースクエリのみ
## 重要なルール
1. `.env.production` を変更しない
2. マイグレーションファイルは追記のみ——既存を編集しない
3. すべてのAPIレスポンスは `ApiResponse<T>` ラッパー型を使う
4. DBカラムは snake_case、TypeScriptプロパティは camelCase——ORMがマッピングを処理
5. 使用前に新しい環境変数を `src/config/env.ts` バリデーションスキーマに追加するよくある間違い
間違い1: エージェントではなく人間向けに書く
AGENTS.mdはドキュメントではありません。READMEのように書かないでください。エージェントはプロジェクトが存在する理由やチームの哲学についてのコンテキストを必要としません。正確な指示が必要です。すべての文はアクション可能であるべきです。
間違い2: あいまいな指示を使う
「ベストプラクティスに従う」はエージェントには意味がありません。「すべてのAPIレスポンスに ApiResponse<T> ラッパー型を使う——src/types/api.ts を参照」は意味があります。具体的に。実際のファイルと型を参照してください。
間違い3: コードが既に示しているものを文書化する
エージェントがコードを読んで推測できるものは文書化しないでください。AGENTS.mdはコード検査では明らかでないことを捉えるべきです：恣意的に見える規約、歴史的な決定、異なる方法で行うと壊れるもの。
間違い4: 更新しない
AGENTS.mdは書いた翌日から陳腐化し始めます。新しいツールを追加したり、ビルドコマンドを変更したり、新しい規約を確立したときは、ファイルを更新してください。古くなったAGENTS.mdは積極的に害を与えます——エージェントは古い指示に自信を持って従います。
間違い5: 長くなりすぎる
AGENTS.mdのすべての行がエージェントの注意を競います。5,000語のAGENTS.mdは500語のものより効果が低いです。エージェントが1回しか遭遇しないトピックについての包括的なセクションを書いていたら、カットしてください。
階層的なAGENTS.mdファイル
CLAUDE.mdと同様に、AGENTS.mdは階層をサポートします。リポジトリルートのファイルはどこでも適用されます。サブディレクトリのファイルはそのサブツリーのみに適用され、ルートファイルを拡張します（置き換えません）。
.
├── AGENTS.md # グローバルルール
├── packages/
│ ├── api/
│ │ └── AGENTS.md # API固有のルール、ルートを拡張
│ └── web/
│ └── AGENTS.md # フロントエンド固有のルール、ルートを拡張
└── infrastructure/
└── AGENTS.md # IaCルール——異なる規約infrastructure/AGENTS.md の例：
# infrastructure/AGENTS.md
このディレクトリはTerraform設定を含みます。
## インフラ固有のルール
- すべての変更は適用前に `terraform plan` 出力が必要
- `terraform apply` を直接実行しない——CIパイプラインを使う
- ステートファイルはS3にある——`.terraform/` や `*.tfstate` をコミットしない
- モジュールバージョンはピン留め——明示的な指示なしに更新しない
## コマンド
- バリデート: `terraform validate`
- フォーマット: `terraform fmt -recursive`
- プラン: `terraform plan -var-file=vars/staging.tfvars`
（ルートAGENTS.mdのグローバルルールも適用されます。）末尾の括弧内の注記は重要です——ルートルールがまだ適用されることを明示することで、エージェントがサブディレクトリファイルを完全な置き換えとして扱うことを防ぎます。
AGENTS.mdの動作確認
AGENTS.mdをテストする最良の方法は、エージェントにそれを読んで何をするか・しないかをサマリーするよう依頼することです。エージェントのサマリーが意図と一致しない場合は、あいまいなセクションを書き直してください。
具体的には、次のチェックを実行します：
-
「新しいエンジニア」テスト: AGENTS.mdに、優秀な開発者が質問なしに貢献を始めるために必要なすべてが含まれているか？なければ何が足りないか？
-
「最悪のケース」テスト: AGENTS.mdを文字通りに従いながらエージェントができる最悪のことは何か？答えが壊滅的なら、制限が不足しています。
-
「陳腐化」テスト: AGENTS.md内のすべてのコマンドとファイルパスを実際のリポジトリと照合。1つでも間違っていれば、エージェントはファイル全体の信頼を失います。
-
「長さ」テスト: 意味のある情報を失わずにコンテンツの20%をカットできるか？できるなら、カットしてください。
始め方
ゼロから始めるならこのテンプレートを使ってください：
# AGENTS.md
## ビルド＆テスト
- インストール: `[インストールコマンド]`
- ビルド: `[ビルドコマンド]`
- テスト: `[テストコマンド]`
- リント: `[リントコマンド]`
## プロジェクト構造
[主なディレクトリと何がどこに置かれるかを説明する2〜3文]
## コードルール
[3〜5の具体的でアクション可能なルール——コードから明らかでないこと]
## 制限事項
決してやってはいけないこと:
- [事項1]
- [事項2]
確認が必要なこと:
- [事項3]これから始めてください。エージェントが間違ったことをしているのを発見したときのみセクションを追加する。これが、リポジトリで無視されるのではなく、実際に役立つAGENTS.mdに行き着く方法です。