あらゆるAIコーディングエージェントにプロジェクトを理解させるAGENTS.mdファイルの書き方

AIコーディングエージェントが間違ったテストコマンドを実行したり、プロジェクトで禁止されているスタイルでコードを整形したり、すでに存在するヘルパーを再発明したりするのを見たことがあるなら、その解決策はたいてい、より賢いモデルではなくコンテキストだ。AGENTS.mdは、エージェントにそのコンテキストを与えるための標準的な方法であり、ほぼすべてのツールで機能する。

AGENTS.mdとは実際に何なのか

AGENTS.mdは「エージェント向けのREADME」だ。プロジェクトの動作の仕組みをAIコーディングツールに伝えるために、リポジトリのルートに置くプレーンなMarkdownファイルである（agents.md）。これは新しい設定言語ではなく、必須フィールドも特別な構文も存在しない。好きなMarkdownの見出しを使ってかまわない。

このフォーマットが重要なのは、それが本当にツールをまたいで機能するからだ。2026年半ばの時点で、OpenAI Codex、GitHub Copilot、Cursor、Windsurf、Devin、Aider、Zed、VS Code、JetBrains Junie、そしてほかにも数十のツールがネイティブに読み込む――28以上のツールと60,000以上のオープンソースリポジトリで使われている（agents.md、Codersera）。現在はLinux FoundationのAgentic AI Foundationによって、AnthropicのModel Context Protocolと並んで運営されている。Claude CodeもAGENTS.mdを読むが、より表現力の高いネイティブフォーマットは依然としてCLAUDE.mdだ（DeployHQ）。

1つのファイルで、ほとんどのツールが一貫した振る舞いをするようになる。

チャットで繰り返すより、ファイルが優れている理由

指示をチャットメッセージに貼り付けても、それはまさにその会話1回きりしか存在しない。次のセッション――あるいは次のチームメイト、あるいは夜通しあなたのタスクを実行するクラウドエージェント――はゼロから始まる。AGENTS.mdは毎回の実行開始時に自動的に読み込まれるため、あなたが言及するのを覚えていたかどうかに左右されることなく、規約がデフォルトで強制される。それこそが要点だ。プロジェクトの知識を、頭の中や使い捨てのチャットから取り出して、ツールが毎回読むファイルの中へ移すのである。

何を書くべきか

有能な新しいチームメイトが初日に必要とするものを考えてみよう――それがまさにエージェントに必要なものだ。最も役立つセクションは次のとおり。

• プロジェクト概要 — これが何であり、技術スタックは何かを1段落で。
• セットアップとビルドのコマンド — インストール、実行、ビルドの正確なコマンド。
• テスト — テストの実行方法と、変更が完了とされる前にテストが通らなければならないというルール。
• コードスタイル — フォーマッタ、リンター、命名規則、優先すべき／避けるべきパターン。
• コミットとPRのガイドライン — メッセージの形式、ブランチのルール、触ってはいけないもの。
• 落とし穴（Gotchas） — 人がつまずく、自明でないあらゆること。

具体的に書くこと。「きれいなコードを書け」ではエージェントには何も伝わらない。「npmではなくpnpmを使うこと。完了前にpnpm testを実行すること。src/generated/内のファイルは決して編集しないこと」なら、実際に守らせることができる。

具体的な例

以下は、典型的なWebアプリ向けのコンパクトなAGENTS.mdだ。

# AGENTS.md

## Project
Next.js 15 + TypeScript storefront. Package manager is pnpm.

## Setup & commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`

## Testing
- Run all tests: `pnpm test`
- All tests must pass before a task is considered done.

## Code style
- TypeScript strict mode; no `any`.
- Format with Prettier (`pnpm format`) — do not hand-format.
- Prefer named exports. Reuse helpers in `src/lib/` before writing new ones.

## Do not touch
- `src/generated/**` is auto-generated. Never edit by hand.
- Never commit `.env` files.

これをClaude Code、Cursor、Copilotのいずれに渡しても、それぞれが同じルールを拾い上げる。

モノレポ：ネストしたファイルを使う

モノレポでは、ルートに1つ置くのに加えて、各パッケージにもAGENTS.mdを配置できる。エージェントがサブディレクトリ内で作業するとき、最も近いファイルが優先される（agents.md）。共有の規約はルートに、パッケージ固有のコマンドはネストしたファイルに置いておけば、packages/api/を編集するエージェントは、そのパッケージのビルドおよびテストのコマンドを自動的に取得できる。

AGENTS.md 対 CLAUDE.md 対 Cursorのルール

すでにCLAUDE.mdや.cursor/rulesのようなツール固有のファイルを持っているかもしれない。それらを捨てる必要はない。実際には、チームは共有されたツール非依存の規約――どのエージェントにも必要なもの――をAGENTS.mdに置き、ツール固有の追加事項は、より豊かな機能をサポートするツールのネイティブファイルに残している（DeployHQ）。たとえばClaude Codeは両方を読み、CLAUDE.mdをより表現力の高いフォーマットとして扱う。よくあるパターンは、正典となるAGENTS.mdを1つ保ち、ツールに独自のファイルが必要な場合は、そのファイルをAGENTS.mdに向けておくことで、単一の信頼できる情報源を保つというものだ。まずはAGENTS.mdから始め、そのツールだけがサポートする機能が必要になったときにのみ、ツール固有のファイルに手を伸ばそう。

短く、具体的に保つ

多ければよいというものではない。スタイルガイド全体を繰り返す巨大なAGENTS.mdは、モデルの注意を奪い合い、実際に重要なルールを埋もれさせてしまう。指針がなければエージェントが間違えるであろう、ほんの一握りのこと――自明でないコマンド、触ってはいけないディレクトリ、あなたのコードベースが好むパターン――を狙おう。あるルールがコードからすでに自明であるなら、おそらくそれを書き留める必要はない。

役立ち続けさせる方法

AGENTS.mdは、真実であり続けてこそ、その価値を発揮する。コードと同じように扱おう。コマンドや規約が変わったら、同じコミットの中でファイルを更新する。そして、エージェントが同じ間違いを二度したら、チャットで訂正するだけで済ませず、ルールを書き留めよう。そのひとつの習慣が、あらゆるつまずきを恒久的な修正へと変える。そしてそれは、AIエージェントをあなたのプロジェクトで信頼できるものにするために、あなたができる最もレバレッジの高い、たったひとつのことなのだ。