直接回答
AGENTS.md と CLAUDE.md はどちらもリポジトリの規約をコーディングセッションに持ち込めるが、読み込みルールと周辺設定が異なる。高品質な指令ファイルは短く実行可能であり、テストコマンドや境界を検証可能なルールとして記述する。
このガイドで解決できること
2つのコーディングエージェント向け指令ファイルを同時に保守するチームが、重複やルールのドリフトを避けるための支援。
共通目標：口頭の取り決めをリポジトリのコンテキストに変換する
どちらのファイルも、保守者がエージェントに長期で遵守してほしい情報（リポジトリ構造、ビルドコマンド、テストのエントリ、コードスタイル、変更禁止領域など）を記録するのに適している。ただし README の全文を複製したり、シークレットを格納したりすべきではない。
あるルールを書き込む価値があるかの判断基準は単純だ。複数のタスクで繰り返し現れるか、そしてコマンド・パス・レビュー結果で検証できるか。一時的な要件は現在のプロンプトに留める。
AGENTS.md は階層化可能なリポジトリ規約に重視
Codex は作業ディレクトリとリポジトリ階層に従って AGENTS.md を検出する。ルートファイルはグローバル規約に、サブディレクトリのファイルは言語・サービス・パッケージ単位のルールに適している。保守者は各コマンドをどのディレクトリから実行するかを明示し、深い階層のファイルで上位の全内容を繰り返し記述しないこと。
monorepo では、ルートファイルに汎用的なセキュリティとコミットのルールを残し、フロントエンド・バックエンド・インフラの各ディレクトリにはそれぞれのビルドとテスト要件を配置できる。
CLAUDE.md のプロジェクトメモリとインポート機構の組み合わせ
Claude Code は異なるスコープの CLAUDE.md をサポートし、インポートで大規模な指令セットを整理できる。チーム共有の内容と個人の好みは分離すべきだ。リポジトリファイルはバージョン管理に、ローカルやユーザー単位のファイルはマシンや個人の習慣に残す。
インポートは重複を減らすが、依存チェーンも増やす。インポートされる各ファイルには明確な所有者を設け、ディレクトリ調整時に検証して、サイレントな無効化を防ぐ必要がある。
両ツールを同時にサポートする際のリポジトリレイアウト
チームは2つのエントリファイルで共通の信頼できる情報源を共有できる。言葉どおり同じ長文を2部保守する必要はない。README または docs/engineering.md に安定した人間向けドキュメントを記録し、AGENTS.md と CLAUDE.md にはそれぞれの読み込み機構に必要なルールと参照だけを残す。
repository/
├── AGENTS.md
├── CLAUDE.md
├── docs/
│ └── engineering.md
├── frontend/
│ └── AGENTS.md
└── backend/
└── AGENTS.md
保守可能な指令チェックリスト
スタイルの好みよりも先に、コマンドと境界を書く。「品質を保つ」といった曖昧な記述は検収できないが、「変更前に pnpm typecheck を実行し、変更後に pnpm build を実行する」ならそのまま実行できる。
- リポジトリの用途と主要ディレクトリ。短い段落1つ以内。
- インストール、開発、型チェック、テスト、ビルドのコマンド。
- 変更を許可する／禁止するファイルの範囲。
- 依存関係、データベース、デプロイなど、人の確認が必要なブレークポイント。
- 最終回答で報告すべき検証結果と残余リスク。
指令ファイルをコードレビューに組み込む
ビルド、権限、リリースフローに影響する指令の変更はすべて、コードと同様にレビューすべきだ。少なくとも四半期ごとにコマンドがまだ存在するかを確認し、CI で主要コマンドを実行して、ドキュメントと実際のスクリプトが乖離しないようにする。
エージェントが特定のルールを頻繁に違反する場合、まずルール同士の競合、配置の正しさ、説明が実行可能かを確認する。より長い文章をただ追加し続けることで解決しようとしない。
公式情報と検証範囲
本ガイドは公開されている公式ドキュメントを根拠にしています。コマンドや設定はクライアントのバージョンにより変わるため、実行前に参照元も確認してください。
技術検証方法を見る