AGENTS.mdパターン：エージェントの行動を実際に変えるものは何か

私が最初に作ったAGENTS.mdは、チームのスタイルガイドを200行コピー＆ペーストしたものでした。命名規則、コードレビューのチェックリスト、デプロイ手順、アーキテクチャの原則が含まれていました。エージェントはそのほとんどを無視しました。指示が間違っていたからではなく、それがドキュメントであってオペレーションではなかったからです。

この区別は、この記事で紹介するどのパターンよりも重要です。AGENTS.mdはAIエージェントのための運用ポリシーであり、人間向けのREADMEではありません。エージェントは、なぜコンベンショナルコミットを使うのかを理解する必要はありません。実行すべき正確なコマンドと、「完了」がどのような状態かを知る必要があるのです。

TL;DR

AGENTS.mdの問題のほとんどは、エージェントのオペレーションではなく人間向けのドキュメントを書いてしまうことに起因します。効果的なファイルは、コマンドファースト（説明ではなく正確な実行コマンド）、タスク別構成（コーディング、レビュー、リリースのセクション）、完了定義の明確化（明示的な「完了」の基準）が特徴です。確実に無視されるアンチパターンは、散文の段落、曖昧な指示（「注意して」）、矛盾する優先事項です。AGENTS.mdは60,000以上のプロジェクトで採用されているオープンスタンダード ¹ であり、Codex、Cursor、Copilot、Amp、Windsurf などで動作します ²。

背景： AGENTS.mdはLinux Foundation傘下のAgentic AI Foundationによって管理されており ³、Anthropic、Google、Microsoft、OpenAIがプラチナメンバーとして参加しています。この記事では実践的なパターンを扱います。Codex固有の設定についてはCodexガイドを、Claude Codeの同等機能（CLAUDE.md）についてはClaude Codeガイドをご覧ください。

無視されるもの

以下のパターンは、エージェントの行動に観察可能な変化をもたらしません。それぞれ、指示の有無で同一のタスクを実行し、パターンごとに10回以上の実行でタスク完了精度を比較することで特定しました。GitHubがAGENTS.mdファイルを持つ2,500以上のリポジトリを分析した結果も同じ結論に達しています：「ほとんどのエージェントファイルが失敗するのは技術的な制限のためではなく、曖昧すぎるためです」¹¹。以下のパターンは、いかなる測定可能な方法でも精度を向上させませんでした。

コマンドを伴わない散文の段落

<!-- BAD: Agent skips this -->
We value clean, well-tested code. Our team follows TDD principles
and believes in comprehensive test coverage. Please ensure all
changes are properly tested before submitting.

エージェントはこれを読み、曖昧な好みとして表現し、テストを書かずにコードを進めます。実行可能な指示がなく、実行すべきコマンドもなく、閾値もなく、「properly tested」の定義もありません。

曖昧な指示

<!-- BAD: "Careful" means nothing to an agent -->
- Be careful with database migrations
- Optimize queries where possible
- Handle errors gracefully

「Careful」は制約ではありません。「Where possible」はトリガー条件ではありません。「Gracefully」は動作仕様ではありません。これらは人間同士のガイダンスであり、エージェントへの指示ではありません。効果のある指示と比較してみてください：「alembic checkをマイグレーション適用前に実行する。ダウングレードパスがない場合は中止する。」

矛盾する優先事項

<!-- BAD: Which one wins? -->
- Move fast and ship quickly
- Ensure comprehensive test coverage
- Keep the runtime budget under 5 minutes
- Run the full integration test suite before every commit

エージェントは4つすべてを同時に満たすことができません。明示的な優先順位なしに指示が矛盾すると、モデルは検証ステップをスキップしてコード生成に急ぎます。ICLR 2026の研究（AMBIG-SWE）では、エージェントは「明示的な促しがなければ非対話的な行動をデフォルトとする」ことが判明しており、確認の質問をせずに黙々と進めることで、解決率が48.8%から28%に低下しました ¹²。矛盾する指示は、優先順位に番号を付けて修正します：「優先度1：テストが通ること。優先度2：5分以内。優先度3：素早くリリース。」

強制手段のないスタイルガイド

<!-- BAD: No way to verify compliance -->
Follow the Google Python Style Guide for all code.
Use numpy-style docstrings for public functions.

スタイルを強制する正確なリントコマンド（ruff check --select Dやpylint --rcfile=.pylintrc）を含めない限り、エージェントには自身のコンプライアンスを検証する手段がありません。ここでのパターンは普遍的です：検証コマンドのない指示は、ルールではなく提案です。

効果のあるもの

以下のパターンは、エージェントの行動に一貫した測定可能な変化をもたらします。

コマンドファーストの指示

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

コマンドは曖昧さがありません。エージェントは何を実行すべきか、どの引数を渡すべきかを正確に把握し、終了コードをチェックして成功を検証できます。AGENTS.mdのすべての指示は、「これが正しく行われたことを証明するコマンドは何か？」という問いに答えるべきです。

完了の定義

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

明示的な完了の定義は、最も一般的な失敗モード — エージェントが検証せずに「完了」と報告すること — を排除します。「完了」が特定の終了コードとして定義されていれば、エージェントは完了を報告する前に各チェックを実行します。この定義がなければ、「完了」は「完了したと思う」を意味し、エージェントが導入するバグの一般的な原因となります。

タスク別に整理されたセクション

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions
- Test command: `pytest tests/ -v -k "test_<module>"`

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`
- List changed files: `git diff --name-only HEAD~1`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`
- Tag: `git tag -a v<version> -m "Release v<version>"`

タスク別に整理されたファイルは、エージェントが現在行っている作業に基づいて関連する指示を選択できるようにします。フラットなリストでは、エージェントはコンテキストに関係なくすべての指示を解析しなければなりません。「When…」というプレフィックスは、エージェントがタスクコンテキストについて推論する方法に直接対応しています。

エスカレーションルール

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- If you encounter merge conflicts: stop and show the conflicting files
- Never: delete files to resolve errors, force push, or skip tests

エスカレーションルールがなければ、エージェントはブロックされた時にますます創造的な回避策をデフォルトとします — ロックファイルの削除、チェックのバイパス、サイレントな失敗の無視などです。「Never」リストはエスカレーションパスと同じくらい重要です。破壊的なリカバリーパターンを明示的に禁止することで、最悪の失敗モードを防ぎます。

モノレポのためのディレクトリスコーピング

AGENTS.mdは仕様のコア機能として階層的なスコーピングをサポートしています ²。作業ディレクトリに近いファイルが優先されます：

/repo/AGENTS.md                        ← Project-wide rules
  └─ /repo/services/AGENTS.md          ← Service defaults
      ├─ /repo/services/api/AGENTS.md  ← API-specific rules
      └─ /repo/services/web/AGENTS.md  ← Frontend-specific rules

ルートレベルの指示は、より深いファイルと連結されます。ツールはプロジェクトルートから現在の作業ディレクトリまでを走査し、パスに沿って見つかったすべてのAGENTS.mdを結合します ⁴。OpenAI自身のCodexリポジトリは、モノレポに88個の個別のAGENTS.mdファイルを使用しています — サービスとパッケージごとに1つずつです ⁴。

Codexでは、任意のレベルでAGENTS.override.mdを使用して、親の指示を拡張ではなく置換することもできます ⁴。オーバーライドメカニズムはCodex固有であり、他のツールでは実装されていません。

<!-- /repo/services/payments/AGENTS.override.md (Codex only) -->
# Payment Service Rules (OVERRIDE)

This service has additional security requirements.
All changes require: `bandit -r . -ll` passing with zero findings.
No dependency updates without explicit approval.
Test with: `pytest -v --tb=long -x` (fail fast, full tracebacks)

オーバーライドを使用するタイミング： リリースフリーズ、インシデントモード、またはプロジェクト全体のデフォルトを上書きするセキュリティ要件を持つサービスの場合です。

クロスツール互換性

AGENTS.mdは60,000以上のプロジェクトで採用されており ¹、すべての主要なAIコーディングツールで認識されています。同じファイルがエコシステム全体でどのように動作するかを示します：

チームで複数のツールを使用する場合： AGENTS.mdを正規のソースとして作成してください。ツール固有のファイル（CLAUDE.md、.cursorrules）は、関連するセクションをインポートまたはミラーリングするようにしてください。乖離する並行した指示セットを維持しないでください。

記述順序：最初に追加すべきもの

AGENTS.mdをゼロから書く場合は、この優先順位でセクションを追加してください。各レイヤーは前のレイヤーの上に構築されます：

1. ビルドとテストのコマンド — エージェントが何か有用なことをする前にこれが必要です
2. 完了の定義 — 「完了したと思う」という誤った完了報告を防ぎます
3. エスカレーションルール — エージェントが行き詰まった時の破壊的な回避策を防ぎます
4. タスク別のセクション — タスクごとの不要な指示の解析を削減します
5. ディレクトリスコーピング（モノレポのみ）— サービス固有の指示を分離して保持します

最初の4つが機能するまで、スタイルの好みはスキップしてください。ほとんどのAGENTS.mdファイルが失敗するのは、スタイルガイダンスから始めてコマンドにたどり着かないからです。

AGENTS.mdのテスト

エージェントが実際に指示を読んで従っているかを検証します：

# Codex: Show the full instruction chain
codex --ask-for-approval never "Summarize your current instructions"

# Codex: Generate a scaffold (slash command inside an active session)
# Type /init at the Codex prompt, not as a shell command
codex  # then type: /init

# Claude Code: Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
codex --ask-for-approval never "What is your definition of done?"

最終テスト： エージェントにビルドコマンドを説明させてみてください。そのまま再現できない場合、指示が読まれていないか、コンテキストに保持するには冗長すぎます。長いAGENTS.mdファイルはコンテキストウィンドウで切り詰められます — 各セクションを50行以内に抑え、最も重要な指示を先頭に配置してください。

FAQ

AGENTS.mdファイルはどのくらいの長さにすべきですか？

各セクションを50行以内、ファイル全体を150行以内に収めてください ¹³。Codexはデフォルトで32KiBの制限（project_doc_max_bytes）を適用します ⁴。長いファイルはコンテキストウィンドウで切り詰められるため、最も重要な指示 — コマンドと完了の定義をスタイルの好みよりも先に — 先頭に配置してください。

AGENTS.mdはツール固有の指示ファイルを置き換えますか？

いいえ。AGENTS.mdはCLAUDE.md、.cursor/rules、その他のツール固有のファイルと併用できます。AGENTS.mdを正規のソースとして作成し、関連するセクションをツール固有のファイルにミラーリングしてください。AGENTS.mdのパターン（コマンドファースト、完了定義の明確化）は、ツールに関係なくどの指示ファイルでも機能します。

エージェントがAGENTS.mdを無視する場合はどうすればよいですか？

エージェントにビルドコマンドを説明させてテストしてください。そのまま再現できない場合、ファイルが冗長すぎるか（コンテンツがコンテキストから押し出されている）、曖昧すぎるか（エージェントが実行可能な指示を抽出できない）、または検出されていないか（ファイルの場所とツールのドキュメントを確認してください）のいずれかです。GitHubの2,500リポジトリの分析では、技術的な制限ではなく曖昧さがほとんどの失敗の原因であると判明しています ¹¹。

重要なポイント

個人開発者向け：

• 散文をコマンドに置き換えてください。すべての指示は、何かを実行することで検証可能であるべきです。
• 完了を明示的に定義してください。「完了」とは特定の終了コードを意味し、感覚ではありません。
• エージェントにAGENTS.mdを暗唱させてテストしてください。暗唱できないものは、従いません。

チーム向け：

• AGENTS.mdを唯一の信頼できるソースとして使用してください。ツール固有のファイルにミラーリングし、並行したコピーを維持しないでください。
• カテゴリ（スタイル、テスト、デプロイ）ではなく、タスク（コーディング、レビュー、リリース）ごとに整理してください。
• エスカレーションルールを含めてください。これがなければ、ブロックされたエージェントは望まない方法で即興的に対処します。
• モノレポではディレクトリごとにスコープを設定してください。サービス固有のルールがグローバルな指示を汚染すべきではありません。

参考文献