AIコーディングエージェントに本当に役立つAGENTS.mdの書き方

実際のプロジェクトでAIコーディングエージェントを使ったことがあるなら、間違ったテストコマンドを実行したり、フォーマッタを無視したり、すでにあるヘルパーを作り直したりする瞬間にぶつかったことがあるだろう。直し方はたいていより賢いモデルではない——推論できないプロジェクト固有のコンテキストをエージェントに与えることだ。それがAGENTS.mdファイルの目的だ。

AGENTS.mdとは何か

AGENTS.mdは、コーディングエージェントがプロジェクトのコンテキストと指示を見つける予測可能な場所を与える、シンプルでオープンなMarkdown形式だ。OpenAI Codex、Amp、Google Jules、Cursor、Factory間の協業として始まり、現在はLinux Foundationの下のAgentic AI Foundationが管理している。25を超えるツールがそれを読む——Codex、Cursor、VS Code、GitHub Copilot、Aider、Windsurf、JetBrains Junie、Zed、gooseを含む——そして6万を超えるオープンソースリポジトリに現れる。

人間ではなくエージェント向けに書かれたREADMEだと考えよう。READMEは新しいコントリビューターにプロジェクトを説明する。AGENTS.mdは、エージェントがそうでなければ間違って推測するであろうことを伝える。（Claude CodeユーザーはCLAUDE.mdを同等物として認識するだろう。多くのチームは両方を保持するか、一方を他方にシンボリックリンクする。）

どこに置くか

AGENTS.mdはリポジトリのルートに置く。モノレポでは、各パッケージ内にネストしたファイルを追加する——エージェントはディレクトリツリーの中で最も近いファイルを読むので、エージェントがそのフォルダで作業しているときpackages/api/AGENTS.mdがルートのものより優先される。これにより、PythonサービスとTypeScriptフロントエンドがそれぞれ調整された指示を得られる。

何を入れるか

形式はただのMarkdownだ——好きな見出しを使えばいい。よく役立つセクションには次のものがある。

• ビルド・テストのコマンド — 近似ではなく、正確なコマンド
• コードスタイル — フォーマッタ、リンター、そしてリンターが捕まえない慣習
• テストの指示 — 単一テストの実行方法、変更が完了する前に通らねばならないもの
• セキュリティ上の考慮 — 決して触れてはいけないファイルや操作
• コミット / PRの慣習 — メッセージ形式、ブランチ命名
• デプロイ手順 — エージェントがそれに触れることが期待される場合のみ

最小限で信号の強い例を示す。

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (do NOT run in CI)
- Test a single file: `pnpm vitest run path/to/file.test.ts`
- Lint + typecheck before any commit: `pnpm check`

## Conventions
- Use the existing `db()` helper in `src/lib/db.ts`; never open a raw client.
- Dates are stored as UTC ISO strings. Never use `Date.now()` in tests.

## Do not touch
- `src/generated/**` is codegen output. Edit the schema, then run `pnpm gen`.

そこにないものに注目してほしい。アーキテクチャの講義もなく、フォルダ構造の再説明もなく、「これはベストプラクティスで作られたモダンなWebアプリです」もない。それは意図的だ。

短い方がたいてい良い

巨大なAGENTS.mdを生成してくれとエージェントに頼みたくなる誘惑がある。抵抗しよう。InfoQが報じた2026年のETH Zurichの研究は、これらのファイルの実際の影響を測定し、効果は限界的でまちまちだと見出した。LLM生成のコンテキストファイルは、実際にはタスク成功率を平均で約3%下げながら、推論コストを20%以上上げた。人間が書いたファイルは控えめに役立った——成功でおよそ4%の上昇——が、それでもエージェントにより多くのステップを取らせ、コストを最大約19%増やした。

その仕組みは示唆的だ。エージェントはファイルが言うことに何であれ忠実に従うので、だらだらと長い文書は、目の前のタスクには不要な追加テストの実行、より多くのファイルの読み取り、品質チェックの実施をエージェントに命じる。研究者の推奨: 自動生成のコンテキストファイルは完全に避け、人間が書く指示は推論不可能な詳細——エージェントが自力で発見できない特定のツーリングやカスタムコマンド——に限定せよ。

言い換えれば、各行は、あなたが実際にエージェントがしでかすのを見た具体的なミスを防ぐことで、その場所を稼ぐべきだ。

うまくいくワークフロー

1. 空から始める。 エージェントが何かを間違えるのを見るまでAGENTS.mdを書かない。
2. 理論ではなく、修正を加える。 間違ったテストコマンドを実行したら、正しいものを加える。ファイルを勝手に再整形してリンターが文句を言ったら、ルールを加える。
3. 引き締めて保つ。 ある行がpackage.jsonやフォルダ名からエージェントが読めることの再説明にすぎないなら、削除する。
4. モノレポにはネストを使うので、各パッケージのファイルが小さく保たれる。
5. 毎月読み返す。 古い指示はないより悪い——時代遅れのビルドコマンドに従うエージェントは、自信満々で失敗する。

最良のAGENTS.mdファイルは、決して忘れないが決して推論もしない唯一のチームメイトのための、簡潔なオンボーディングのカンニングペーパーのように読める。彼らが推測できないことを書き留め、それ以外は何も書くな。