AGENTS.md のパターン：エージェントの挙動を本当に変えるもの

最初に書いた AGENTS.md は、チームのスタイルガイドを200行そのまま貼り付けたものでした。命名規則、コードレビューのチェックリスト、デプロイ手順、アーキテクチャの原則まで詰め込んでいます。エージェントはその大半を無視しました。指示が間違っていたからではありません。あれが 運用 ではなく ドキュメント だったからです。

AGENTS.md に書くべきなのは、正確な呼び出し方まで示したコマンド優先の指示、タスク単位で整理されたセクション（コーディング、レビュー、リリース）、そしてエージェント自身が検証できる明示的な「完了」条件です。 人間向けのドキュメントではなく、運用ポリシーを書きましょう。エージェントが実行しなければならないシェルコマンド、リンター設定、テストコマンドを具体的に含めます。散文の段落、「注意して」のような曖昧な指示、優先順位を明示しないまま矛盾する要求は避けてください。AGENTS.md は6万件を超えるプロジェクトに採用されているオープン標準であり、Codex、Cursor、Copilot をはじめとするエージェントツールで横断的に機能します。

この区別は、本稿で紹介するどの個別パターンよりも重要です。AGENTS.md は AI エージェントのための運用ポリシーであって、人間向けの README ではありません。エージェントは、あなたが Conventional Commits を使う 理由 を理解する必要はないのです。必要なのは、実行すべき正確なコマンドと、「完了」がどういう状態を指すのかという情報だけです。

要点

AGENTS.md にまつわる問題の多くは、エージェントの運用手順ではなく人間向けドキュメントを書いてしまうことに起因します。効果の高いファイルはコマンド優先（説明ではなく正確な呼び出し方）で、タスク単位に整理され（コーディング、レビュー、リリースの各セクション）、完了条件が明示されています。確実に無視されるアンチパターンは、散文の段落、曖昧な指示（「注意して」）、そして矛盾する優先順位です。AGENTS.md は6万件を超えるプロジェクトに採用されたオープン標準であり ¹、Codex、Cursor、Copilot、Amp、Devin Desktop などで動作します ²。

背景： AGENTS.md は Linux Foundation 傘下の Agentic AI Foundation が管理しており ³、プラチナメンバーには Anthropic、Google、Microsoft、OpenAI が名を連ねます。本稿では実践的なパターンを扱います。Codex 固有の設定については Codex ガイド を、Claude Code における対応物（CLAUDE.md）については Claude Code ガイド をご覧ください。

無視されるもの

以下のパターンは、エージェントの挙動に観測可能な変化をまったく生みません。いずれも、同一のタスクを指示ありとなしで実行し、パターンごとに10回以上の試行でタスク完了の正確さを比較して特定しました。AGENTS.md を含む2,500以上のリポジトリを分析した GitHub も同じ結論に達しています。「ほとんどのエージェントファイルが失敗するのは、記述が曖昧すぎるからだ」というわけです ¹¹。以下のパターンは、測定できる形での改善をまったくもたらしませんでした。

コマンドのない散文の段落

<!-- 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.

エージェントはこれを読み、漠然とした好みとして表現したうえで、テストを書かずにコードを書き進めます。実行可能な指示も、実行すべきコマンドも、満たすべき閾値も、「適切にテストされた」の定義も存在しないからです。

曖昧な指示

<!-- BAD: "Careful" means nothing to an agent -->
- Be careful with database migrations
- Optimize queries where possible
- Handle errors 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）によれば、「明示的なプロンプトがなければ、モデルは深刻に仕様が不足した入力に対してさえ、ほとんど対話を行わない」——エージェントは確認の質問をせず黙って処理を進めてしまう——一方で、対話するよう促すと仕様不足のタスクで最大74%の性能向上が得られました ¹²。矛盾する指示は、優先順位に番号を振って解消しましょう。「優先度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 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

エスカレーションのルールがないと、エージェントは行き詰まったときに次第に創造的な回避策へ走ります。ロックファイルを削除する、チェックを迂回する、失敗を黙って無視する、といった具合です。「絶対にしないこと」のリストは、エスカレーション経路と同じくらい重要です。破壊的な復旧パターンを明示的に禁じておけば、最悪の失敗モードを防げます。

モノレポでのディレクトリスコープ

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

ルートレベルの指示は、より深い階層のファイルと連結されます。Codex はプロジェクトルートから現在の作業ディレクトリまで辿り、その経路上で見つかったすべての AGENTS.md を結合します ⁴。一方、仕様自体は最も近いファイルを優先すると定めているため、ツールによって階層の解決方法は異なり得ます ²。OpenAI 自身の codex リポジトリもこれを実践しており、ルートの下に入れ子の AGENTS.md を同梱しています ⁴。

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 は6万件を超えるプロジェクトに採用され ¹、主要な AI コーディングツールのすべてに認識されています。同じファイルが各エコシステムでどう扱われるかを以下にまとめます（表の内容は2026年8月時点で検証済み）。

チームで複数のツールを使っている場合： 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行以内に収め、最も重要な指示を前方に配置しましょう。

よくある質問

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

私の目安は、各セクションを50行以内、ファイル全体を150行以内に収めることです。この考え方の土台にあるのは Marmelab のエージェント体験に関する指針で、エージェントはセッションのたびに冒頭でこのファイルを読むため「短く要点を押さえた」ものであるべきだとされています ¹³。ただし具体的な行数は私自身の基準であり、同社の主張ではありません。Codex は既定で 32 KiB の上限（project_doc_max_bytes）を課します ⁴。長いファイルはコンテキストウィンドウによって切り詰められるため、最も重要な指示、つまりコマンドと完了条件を、スタイルの好みより前に置いてください。

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

いいえ。AGENTS.md は CLAUDE.md や .cursor/rules など、ツール固有のファイルと併存します。AGENTS.md を正典として書き、そこから関連セクションをツール固有のファイルへ反映させましょう。AGENTS.md のパターン（コマンド優先、完了条件の明示）は、ツールを問わずどんな指示ファイルでも機能します。

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

エージェントにビルドコマンドを説明させてテストしてください。一字一句そのまま再現できないなら、そのファイルは冗長すぎる（内容がコンテキストから押し出されている）、曖昧すぎる（エージェントが実行可能な指示を抽出できない）、あるいは検出されていない（ファイルの配置場所とツールのドキュメントを確認してください）のいずれかです。2,500以上のリポジトリを分析した GitHub も、ほとんどのエージェントファイルは曖昧すぎるために失敗すると結論づけています ¹¹。

押さえておきたいポイント

個人開発者向け：

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

チーム向け：

• AGENTS.md を唯一の情報源として使いましょう。ツール固有のファイルへは反映させ、並行するコピーを維持しないことです。
• カテゴリ（スタイル、テスト、デプロイ）ではなく、タスク（コーディング、レビュー、リリース）で整理しましょう。
• エスカレーションのルールを含めましょう。これがないと、行き詰まったエージェントは望ましくない形で即興に走ります。
• モノレポではディレクトリごとにスコープを切りましょう。サービス固有のルールでグローバルな指示を汚染すべきではありません。

参考文献