AGENTS.md 是给 AI 编码智能体用的操作文档。它告诉智能体如何在这棵目录树里工作：地图在哪、跑哪些命令、这个仓库怎么做 git，以及必须始终做、先问、或永远不要做的事。
它不是第二份 README。README 是把项目介绍给人看的。它也不是风格指南。编码标准已经由 linter 和代码库负责。
格式就是普通 Markdown。没有强制 schema、YAML frontmatter 或 JSON 配置。开放约定在 agents.md：文件名是 AGENTS.md，离正在编辑的文件最近的那份生效，列出的命令会被执行，聊天里的消息始终覆盖文件。
2025 年 12 月，该格式捐赠给 Agentic AI Foundation (AAIF)，这是 Linux Foundation 下的 directed fund，与 Anthropic 的 Model Context Protocol 并列。一份文件，多种智能体。
根目录目标约 200 行。够写完地图、git 规则和边界。又短到每次会话都能加载。
文件里有什么
五个区块。保持这个顺序。
概览 —— 这棵树是什么，几句话。
地图和到哪里读更多 —— 要紧的目录，以及指向持久知识索引的指针。指过去。不要把 wiki 贴进来。
命令 —— 确切的安装、测试和 lint 命令。你写了，智能体就会去跑。
Git 工作流 —— 这个仓库怎么交付。分支名、是开 pull request 还是推到 main、commit 语气。Git 是仓库特有的，编码标准不是。
边界 —— Always do。Ask first。Never do。
示例：根目录 AGENTS.md
一个虚构的计费 monorepo。名字只是示意。保住这些区块。
仓库根目录 —— 虚构计费 monorepo
# 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.什么不要写进去
linter 能强制的风格。放进 linter。
给人看的 CONTRIBUTING.md，除非那些 git 行是智能体会执行的。若它们是操作规则，也写进 AGENTS.md。
若工具仍会读 CLAUDE.md，让那份文件指向 AGENTS.md。不要把操作规则再抄一份。
持久的产品知识——人、服务、决策——属于知识地图，不属于操作文件。见 为 AI 代理组织知识。
长流程放进链接的文档或 skill。AGENTS.md 里一行就够：做 X，读 Y。不要让 skill 成为文件的脊柱。
保持它活着
智能体重复同一个错误时，加一条边界。一行过时了，就删掉。200 行的预算，就是用来发现膨胀的。
小结
写一份约 200 行的根目录 AGENTS.md。给它地图、git 规则，以及 Always / Ask first / Never。只有当子目录真正打破这些规则时，才再嵌一份。聊天仍然覆盖文件。
Dylan Engelbrecht 会随智能体实践更新这个知识中心。把这些文章当作活的参考——当前做法，不是冻结快照。