AGENTS.mdは、AIコーディングエージェント向けの運用ドキュメントです。このツリーでどう働くかを伝えます。地図はどこか、どのコマンドを走らせるか、このリポジトリのgitのやり方、常にやること・先に聞くこと・決してやらないこと。
もう一つのREADMEではありません。READMEは人にプロジェクトを紹介します。スタイルガイドでもありません。コーディング標準はすでにリンタとコードベースが持っています。
フォーマットはプレーンなMarkdownです。必須スキーマもYAMLフロントマターもJSON設定もありません。オープンな約束はagents.mdにあります。ファイル名はAGENTS.md。編集中のファイルにいちばん近いものが勝ち、列挙したコマンドは実行され、チャットのメッセージは常にファイルを上書きします。
2025年12月、このフォーマットはLinux Foundation傘下のdirected fundであるAgentic AI Foundation (AAIF)に寄贈されました。AnthropicのModel Context Protocolと並びます。一つのファイル、多くのエージェント。
ルートは約200行を目安にします。地図、gitルール、境界を書くには足りる長さです。毎セッション読み込める短さでもあります。
ファイルに入れるもの
ブロックは五つです。この順を保ちます。
概要 — このツリーが何か。数文で。
地図と、続きを読む場所 — 重要なフォルダと、耐久知識のインデックスへのポインタ。指す。wikiを貼り付けない。
コマンド — 正確なinstall、test、lintコマンド。書けば、エージェントは試します。
Gitワークフロー — このリポジトリの出荷の仕方。ブランチ名、プルリクエストかmainへのpushか、命令形のコミットメッセージ。Gitはリポジトリ固有です。コーディング標準とは違います。
境界 — Always do。Ask first。Never do。
例: ルートのAGENTS.md
架空の請求モノレポです。名前は例示です。ブロックは残してください。
リポジトリルート — 架空の請求モノレポ
# AGENTS.md
## Project overview
Billing platform monorepo: a Node API (`apps/api`), a React dashboard (`apps/web`), and shared libraries under `packages/`. Root rules apply unless a nested AGENTS.md says otherwise.
## Map
- `apps/api` — invoice and payment API
- `apps/web` — operator dashboard
- `packages/` — shared types and clients
- `infra/` — Terraform for staging and production
- Durable product knowledge: `docs/INDEX.md`. Open that map when you need a service, runbook, or decision.
## Commands
pnpm install
pnpm test
pnpm lint
pnpm --filter @acme/api test
docker compose up -d # before API integration tests
## Git workflow
- Open a pull request against `main`. Do not push commits to `main`.
- Branch names: `feat/<short-name>` or `fix/<short-name>`
- Commit messages: imperative mood, complete sentences.
## Boundaries
### Always do
- Run `pnpm test` and `pnpm lint` before you consider a change done.
- Read `docs/INDEX.md` before inventing a service name or a runbook step.
### Ask first
- Changing auth, billing webhooks, or CI workflows.
- Adding a nested `AGENTS.md`.
- Touching `infra/` production modules.
### Never do
- Commit `.env`, API keys, or customer payment data.
- Invent an undocumented payment provider.ネストしたファイル
編集中のファイルにいちばん近いAGENTS.mdが勝ちます。ネストは意図的に稀です。ほとんどのサブディレクトリはルートに従います。カバレッジのために別コピーをネストしないでください。
そのサブツリーがルートのルールを実際に破るときだけ、ネストファイルを足します。ネストファイルは差分です。pnpmもgitもnever-commit-secretsも繰り返しません。
infra/AGENTS.md — 差分であり、ルートの二冊目ではない
# AGENTS.md — infra/
Root git, pnpm, and Never-secrets still apply. This file is only the delta.
## Ask first
- `terraform plan` or `terraform apply` against staging.
## Never do
- Run `terraform apply` against the production workspace.
- Edit Terraform state by hand.入れないもの
リンタが強制できるスタイル。リンタに置きます。
人向けのCONTRIBUTING.md。ただしエージェントが実行するgitの行は除きます。それが運用ルールなら、AGENTS.mdにも書きます。
ツールがまだCLAUDE.mdを読むなら、そのファイルをAGENTS.mdへのポインタにしてください。運用ルールをコピーしないでください。
耐久するプロダクト知識 — 人、サービス、決定 — は知識の地図に属し、運用ファイルには属しません。AIエージェントのための知識の整理を参照してください。
長い手順はリンクしたドキュメントかスキルへ。AGENTS.mdは一行で足ります。XならYを読む。スキルをファイルの主軸にしないでください。
生きたファイルにする
エージェントが同じ間違いを繰り返したら、境界の一行を足します。古くなった行は消します。200行の予算は、膨張に気づくためのものです。
まとめ
ルートに約200行のAGENTS.mdを書いてください。地図、gitルール、Always / Ask first / Neverを持たせます。サブディレクトリがそれらのルールを実際に破るときだけ、別ファイルをネストします。チャットは引き続きファイルを上書きします。
Dylan Engelbrechtはエージェントの実践が変わるたびにこのナレッジハブを更新します。これらの記事を生きた参照として扱ってください。今の実践であり、凍結されたスナップショットではありません。