AGENTS.md: 配置場所とツールでの読み込み方

AGENTS.md は、ほとんどのコーディングエージェントが特別な設定なしで読み込む、プレーンな Markdown 形式のプロジェクト指示ファイルです。OpenAI はこれを Linux Foundation 傘下の Agentic AI Foundation に寄贈しており、6万を超えるオープンソースプロジェクトで使われています。

配置場所

• リポジトリのルートに置く AGENTS.md。プロジェクト全体に適用されます。
• サブディレクトリやパッケージに置く、ネストされた AGENTS.md。エージェントはツリー内で最も近いファイルを使います。
• OpenAI Codex: グローバル設定の ~/.codex/AGENTS.override.md。空または存在しない場合は ~/.codex/AGENTS.md。
• Cline: グローバル設定の ~/.agents/AGENTS.md。
• Claude Code は .claude/AGENTS.md にも対応しています。

形式

frontmatter も必須フィールドもないプレーンな Markdown で、見出しは自由に設定できます。形式上のサイズ制限はありませんが、OpenAI Codex はデフォルトで 32 KiB の project_doc_max_bytes に達すると読み込みを停止します。

# Acme web app

Customer-facing web app with an admin area and a REST API.

## Commands

- Install: `pnpm install`
- Test: `pnpm test`
- Lint and type-check: `pnpm lint && pnpm tsc --noEmit`

## Code style

- TypeScript strict mode; no `any` in new code.
- Keep database access in `src/db/`.

## Never

- Never commit secrets or .env files.
- Never edit files under `src/generated/` by hand.

優先順位と統合

編集対象のファイルに最も近い AGENTS.md が優先され、チャットで明示された指示はどのファイルよりも優先されます。OpenAI Codex はプロジェクトルートから作業ディレクトリまで、各ディレクトリにつき 1 ファイルを連結するため、より近いファイルほど後に追加され、優先されます。CLAUDE.md がある場合、Claude Code はデフォルトで AGENTS.md を読み込みません。

読み込むツール

ヒント

• 既存の AGENT.md の名前を変更する場合は、agents.md が mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md を提案しています。これにより、どちらの名前でも使い続けられます。
• テストと lint のコマンドを記載しましょう。エージェントは見つけたチェックを実行し、完了前に失敗を修正しようとします。
• モノレポでは、ルートのファイルを長くするのではなく、パッケージごとに短い AGENTS.md を追加しましょう。
• OpenAI Codex では、同じディレクトリにある AGENTS.override.md が AGENTS.md より優先されます。

その他の指示ファイル