适用场景与目标

背景速览： 过去 24 小时，AI 编程 Agent（Claude Code、Cursor、Codex、Copilot Coding Agent、Jules、Gemini CLI、Aider、Cline、RooCode 等）已经成为团队日常写代码的标配。但绝大多数团队踩了一个共同的坑：

• Agent 第一次进你的仓库，不知道你的构建命令、测试命令、目录约定、命名规范
• 它会瞎跑命令（npm test 在你的项目里其实是 pnpm test）、瞎改文件（不知道 monorepo 子包结构）、瞎装包（不知道有内部私有 registry）
• 你花 20 分钟跟它解释一次，下一个 Agent 进项目又得重新解释

AGENTS.md 正在成为行业共识的解法：一份为 Agent 写的 README，独立于人类看的 README.md，固定在仓库根目录（或子目录），被 25+ Agent 原生支持，被 60k+ 开源项目采用。本周 HN 上 Sebastian Raschka 的实测 进一步验证：写一份靠谱的 AGENTS.md，能让 Agent 在中型项目里的”一次成功率”从 50% 拉到 75%+，人类返工时间砍掉一半。

适用场景：

• 团队正在使用或计划推广 Claude Code / Cursor / Codex / Aider 等 AI 编程工具
• 仓库结构有 1 个以上”新人（人）需要 1-2 天才能摸清”的特点（monorepo、私有 package、私有 CI、私有部署）
• Agent 在你的项目里经常”猜错命令”、“漏掉 lint”、“改完不跑测试”、“提 PR 不带 description”
• 你不想把 README.md 写成 200 行的混合体（人看着累，Agent 看不全）

核心目标：

用 半天时间 在仓库里落地一份结构良好、内容聚焦的 AGENTS.md，拿到四件东西：

1. Agent 进项目就知道怎么装、怎么跑测试、怎么 lint、怎么提 PR
2. 项目特有约定（命名、子包、目录、私有 registry）一次性写清楚，不用每次重复解释
3. 人类 README 保持干净，不被 Agent 上下文污染
4. CI / Hook / 子目录级 AGENTS.md 三层结构跑通，覆盖”不同子 Agent 看不同上下文”的场景

---

最小可行方案（MVP）步骤

阶段 0：先看一眼你的工具链都支持什么（10 分钟）

# 1) 确认你用的 Agent 是不是支持 AGENTS.md
#    官方支持列表: https://agents.md/
#    主流全支持：Claude Code / Cursor / Codex / Copilot Coding Agent / Jules / Gemini CLI / Aider / Cline / RooCode / opencode / Zed / Windsurf / Devin

# 2) 看一眼哪些 60k+ 项目里有一份写得好的 AGENTS.md 当参考
#    官方精选案例: https://agents.md/#examples
#    推荐先看: openai/codex, vercel/next.js, supabase/supabase, prisma/prisma
gh repo view openai/codex --web  # 拉到底找 AGENTS.md

支持的 Agent 数量比你想象的多。如果你用的工具不在列表里，大部分支持「项目根目录的 CLAUDE.md / .cursorrules / AGENT.md / .github/copilot-instructions.md」——都可以用 AGENTS.md 作为单一事实源，再让各 Agent 工具去引用它。

阶段 1：写第一份 AGENTS.md（1-2 小时）

核心原则：AGENTS.md 是给 Agent 看的，不是给人看的。 写法和 README 完全不同：

<!-- AGENTS.md -->
# AGENTS.md

## Project overview
- This is a monorepo managed by pnpm workspaces.
- Two top-level apps: `apps/web` (Next.js 15, App Router) and `apps/api` (Hono on Node 22).
- One shared package: `packages/ui` (React 19 component library).
- Internal registry: `https://npm.internal.company.com` (NOT public npm).

## Setup commands
- Install deps: `pnpm install --registry=https://npm.internal.company.com`
- Start dev server (all): `pnpm dev`
- Start dev server (single app): `pnpm --filter @company/web dev`
- IMPORTANT: do NOT run `npm install` or `yarn install` — will mess up the workspace.

## Testing instructions
- Unit tests: `pnpm test`
- Single package tests: `pnpm --filter @company/web test`
- Single test file: `pnpm --filter @company/web vitest run src/foo/bar.test.ts`
- E2E tests: `pnpm e2e` (requires `pnpm playwright install` first)
- CI config is in `.github/workflows/ci.yml` — match the matrix there.

## Code style
- TypeScript strict mode ON. No `any` (use `unknown` + narrow).
- Imports sorted by `@company/eslint-config` (auto-fixed by `pnpm lint:fix`).
- React: function components only, no class components.
- Tailwind utility classes; do not write new CSS files.

## Build & deploy
- Build all: `pnpm build`
- Build single app: `pnpm --filter @company/api build`
- Output of `apps/web` → `.next/`, served via Vercel.
- Output of `apps/api` → `dist/`, deployed as a Node 22 container.

## PR conventions
- Branch name: `<ticket-id>-<short-desc>` (e.g. `ENG-1234-fix-login-redirect`).
- Commit format: Conventional Commits (`feat:`, `fix:`, `chore:`, `refactor:`).
- PR title format: `[<project_name>] <Title>` (e.g. `[web] Fix login redirect loop`).
- PR description must include: what changed, why, how to test, screenshots if UI.
- Always run `pnpm lint && pnpm test` before pushing.

## Things to avoid
- Do NOT modify `packages/ui/src/tokens/*` without checking with the design system team.
- Do NOT bump `react` or `next` versions in a feature PR — open a separate dependency-upgrade PR.
- Do NOT add new top-level packages to the monorepo without first creating an RFC in `docs/rfcs/`.
- Do NOT commit `.env*` files. Use `.env.example` with placeholder values.

## Agent-specific notes
- When using Claude Code: prefer `pnpm` over `npm`. Do not run `pnpm dlx` for global tools — install them in `package.json` `devDependencies` instead.
- When using Cursor: the `.cursor/rules/*.mdc` files are auto-generated from this file; do not edit them directly.

为什么这么写（不是 README 写法）：

• 标题用祈使句（“Install deps”、“Run unit tests”），不是描述句
• 把”不要做什么”（Things to avoid）放在最显眼的位置，避免 Agent 走老路
• 命令给完整可复制版本（包括 --registry、包括 --filter），不让 Agent 自己猜参数
• 不用 emoji、装饰、引言、screenshot——Agent 看不到图，emoji 增加 token 无意义
• 每条都”能执行验证”——不要写”确保代码质量高”，要写”run pnpm lint && pnpm test”

阶段 2：和 README 拆开（10 分钟）

AGENTS.md 绝不替代 README.md。两者各管各的：

关注点	README.md（人）	AGENTS.md（Agent）
受众	人类贡献者、用户、招人	AI 编程 Agent
内容	项目介绍、quick start、contribution guide、screenshot	构建命令、测试命令、目录约定、命名规范、避坑清单
长度	200-500 行（含图、表格、故事）	50-200 行（纯文本，可机器解析）
更新频率	季度	每次引入新工具/约定
语气	友好、欢迎	命令式、精确

如果你的 README 已经有 Agent 需要的命令，不要复制到 AGENTS.md——直接写：

<!-- AGENTS.md -->
## Reference
- For the human-facing overview, see [README.md](./README.md).
- For the architecture deep-dive, see [docs/architecture.md](./docs/architecture.md).

Agent 会自己跟过去读。

阶段 3：子目录嵌套 AGENTS.md（30 分钟）

关键能力：Agent 在某个子目录工作时，会优先看最近的 AGENTS.md。 利用这个机制给子包、子模块分别写：

.
├── AGENTS.md                 # 顶层：monorepo 全局约定
├── apps/
│   ├── web/
│   │   └── AGENTS.md         # Next.js 特定：路由约定、ISR、Server Components
│   └── api/
│       └── AGENTS.md         # Hono 特定：路由结构、中间件、错误处理
├── packages/
│   └── ui/
│       └── AGENTS.md         # 组件库特定：storybook、视觉回归、导出顺序
└── infra/
    └── AGENTS.md             # Terraform 特定：plan 命令、workspace 切换

子 AGENTS.md 只写这个子目录特有、而父 AGENTS.md 没有的内容。例如 apps/api/AGENTS.md：

<!-- apps/api/AGENTS.md -->
# AGENTS.md (apps/api)

## Local dev
- Start the API in isolation: `pnpm --filter @company/api dev`
- It listens on `http://localhost:8787`. The web app's dev server proxies to it.
- Postgres: `docker compose up -d postgres` (uses the docker-compose.yml in repo root).

## Adding a new route
- Routes live in `src/routes/<resource>/<action>.ts`. Use Hono's `hono/router` syntax.
- Every route MUST call `requireAuth()` middleware unless it's in `publicRoutes` array.
- All request bodies are validated with Zod schemas in `src/schemas/`.

## Testing
- Run only API tests: `pnpm --filter @company/api test`
- For integration tests, the test DB is reset between tests via `globalSetup`.

## Things to avoid
- Do NOT add new top-level dependencies to `apps/api/package.json` without checking with the platform team — most cross-cutting deps belong in `packages/`.
- Do NOT use `console.log` in route handlers; use the `logger` from `src/lib/logger.ts`.

阶段 4：CI 校验 AGENTS.md 自身（30 分钟）

AGENTS.md 会被 Agent 当事实源，写错一句会污染几百次任务。 加 CI 校验：

# .github/workflows/validate-agents-md.yml
name: Validate AGENTS.md
on:
  pull_request:
    paths: ['**/AGENTS.md', '.github/workflows/validate-agents-md.yml']

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install
        run: npm install -g @agents-md/lint

      - name: Lint
        run: agents-md-lint ./**/*.AGENTS.md
        # 规则示例：
        #   - 每条命令必须在仓库里能跑通（dry-run check）
        #   - 不能超过 500 行（太长 = 没人维护）
        #   - 不能用第一人称（"we"、"our project"）
        #   - 必须有 "Setup commands" 段落

      - name: Verify commands actually exist
        run: |
          # 抽出 AGENTS.md 里所有 ```bash 代码块，跑 dry-run
          npx agents-md-verify --extract=commands
        # 输出哪些命令"在 AGENTS.md 里写了但实际跑不通"

这样 AGENTS.md 永远不会腐化到”写了但 Agent 跑不通”的程度。

---

关键实现细节

1. 上下文大小：AGENTS.md 真的会被全文塞进 prompt

这是一个真实成本问题。 Agent 每次开工都会把当前目录（向上递归）的 AGENTS.md 全部塞进 system prompt。如果你的 AGENTS.md 写 500 行，每次任务多花 5k-10k token。

经验法则：

层级	行数上限	超出后果
顶层 AGENTS.md	150 行	token 成本飙升
子目录 AGENTS.md	100 行	Agent 开始”只看顶层”
整棵树 AGENTS.md 总和	300 行	需要拆分到 docs/

实操建议：

<!-- AGENTS.md -->
## Reference docs
For deeper content, see these files (Agent: read with `read_file` on demand, do NOT preload all of them):
- `docs/testing-strategy.md` — full testing pyramid, fixtures, mocks
- `docs/deploy-runbook.md` — staging/prod deploy steps, rollback
- `docs/dependency-policy.md` — when to add deps, RFC process

## Commands quick reference
| Task | Command |
|------|---------|
| Install | `pnpm install --registry=https://npm.internal.company.com` |
| Test | `pnpm test` |
| Lint | `pnpm lint` |
| Build | `pnpm build` |
| E2E | `pnpm e2e` |
| Single package | `pnpm --filter @company/<pkg> <cmd>` |

这样 Agent 知道”看顶层快速开始”，需要细节时再去 read_file 单独读，不会一次性全塞进 prompt。

2. 显式禁令和白名单同等重要

Agent 不知道”什么不该做”是最大坑。把所有”曾经踩过、Agent 又会再踩”的禁令写进 “Things to avoid” 段落：

## Things to avoid (learned from real incidents)

- Do NOT run `npm install` — it will install into the wrong node_modules and break the monorepo. Use `pnpm install`.
- Do NOT edit `package-lock.json` directly. If you need to add a dep, run `pnpm add <pkg>`.
- Do NOT commit secrets. If you see a `.env` file in your diff, STOP and ask the user.
- Do NOT bump Node version in a feature PR. Open a separate PR with title `chore: bump node to <ver>`.
- Do NOT use `any` in TypeScript. If you can't type something, use `unknown` and narrow it.
- Do NOT add a new top-level dependency to `apps/*` packages without first checking if it exists in `packages/*`.
- Do NOT run migrations in dev mode. Use `pnpm db:migrate` explicitly.
- Do NOT touch files under `packages/ui/src/tokens/*` — they're auto-generated from Figma.

每一条都来自一次真实事故。没有事故的禁令不要写——会污染注意力。

3. 跨 Agent 兼容：用单一事实源 + 工具自己的 wrapper

不同 Agent 工具有自己的 instruction 文件：

• Claude Code: CLAUDE.md（也会读 AGENTS.md）
• Cursor: .cursorrules 或 .cursor/rules/*.mdc
• Codex: AGENTS.md（原生支持）
• Copilot Coding Agent: AGENTS.md 或 .github/copilot-instructions.md
• Aider: AGENTS.md + CONVENTIONS.md

不要为每个 Agent 维护一份不同的文件。 用 AGENTS.md 作为单一事实源，让工具自己的配置文件去引用它：

<!-- .cursorrules (Cursor 专用，会被读进 system prompt) -->
# Inherit from AGENTS.md
@AGENTS.md

# Cursor-specific additions
- When generating code, prefer early returns over nested if/else.
- For React components, use the `<Memo>` wrapper only when props include functions/objects.

<!-- CLAUDE.md (Claude Code 专用) -->
@AGENTS.md

# Claude Code specific
- Use `pnpm` for all package operations.
- When you need to run a long command, prefer `pnpm` scripts over raw node calls.

好处： AGENTS.md 改一次，所有 Agent 都跟上。工具特定的微调放在工具自己的文件里，不污染主文件。

4. 用 Markdown table 表达命令清单，Agent 解析最稳

Agent 对 Markdown table 的解析准确率远高于”段落 + 列表”。所有”命令 → 用途”的映射都用 table：

## Commands

| Intent | Command | Notes |
|--------|---------|-------|
| Install | `pnpm install` | Uses internal registry by default |
| Run all tests | `pnpm test` | Vitest, parallel, ~30s |
| Run one test file | `pnpm test src/foo/bar.test.ts` | |
| Run one test name | `pnpm test -t "should redirect"` | Vitest `-t` pattern |
| Lint | `pnpm lint` | ESLint + Prettier check |
| Lint + auto-fix | `pnpm lint:fix` | |
| Type check | `pnpm typecheck` | tsc --noEmit |
| Build | `pnpm build` | Both apps + package |
| Build single app | `pnpm --filter @company/web build` | |
| DB migrate | `pnpm db:migrate` | Asks for confirmation |
| Reset dev DB | `pnpm db:reset` | Drops + re-migrates + seeds |
| E2E | `pnpm e2e` | Playwright, headless |
| E2E (headed) | `pnpm e2e:headed` | Local only |

为什么 table 比 list 好： Agent 经常需要根据”用户说的”匹配”该跑哪个命令”。table 的第一列”Intent”直接对应用户语义，匹配率 90%+；list 要从动词短语里猜，匹配率掉到 60%。

5. 包含一个”Agent 完成 PR 的 checklist”

Agent 提完 PR 经常忘东西。让 AGENTS.md 显式告诉它”提 PR 前必须做”：

## Before opening a PR

Always run this checklist (in order):

1. `pnpm install` — pick up any new deps
2. `pnpm lint:fix` — auto-fix what's possible
3. `pnpm typecheck` — must be clean
4. `pnpm test` — all green
5. `pnpm build` — both apps build
6. Update CHANGELOG.md if your change is user-visible
7. Fill in PR description:
   - **What**: one-sentence summary
   - **Why**: link to ticket / user story
   - **How to test**: exact steps for a reviewer
   - **Screenshots**: if UI changed
8. If you touched `packages/db/schema.prisma`, run `pnpm db:generate` and commit the regenerated client

Agent 会照着做。没写 checklist 的话，Agent 提的 PR 经常”没跑测试”或”忘了 changelog”。

---

常见坑与规避清单

坑 1：把 AGENTS.md 写成人类 README 的复制粘贴

症状： 200 行、emoji、screenshot、欢迎语、长段落。Agent 读完 80 行 context 还没看到第一条命令。

规避：

• 命令式语气，全用祈使句
• 表格 > 段落，table 占 60%+ 内容
• 禁令段落显眼：单独的 “Things to avoid” 区块，不用 bullet 藏在某段里
• 不长于 150 行（顶层）

坑 2：写了命令但命令在仓库里跑不通

症状： AGENTS.md 写 npm test，但 package.json 里 test 是 vitest run 而且需要先 pnpm install，Agent 一跑就报错。

规避：

• 从 package.json 里抄命令，不要凭记忆写
• 加 CI step（阶段 4）做 agents-md-verify，把代码块里的命令 dry-run 跑一遍
• 命令格式统一：永远 <pkg-manager> <script>，不要混用 npx / pnpm dlx / global

坑 3：禁令太多，Agent 变成”啥也不敢做”

症状： 写了 30 条 “Do NOT …”，Agent 在每个决策点都犹豫不决，任务成功率从 80% 掉到 40%。

规避：

• 禁令只写”曾经踩过、且 Agent 会主动再踩”的——不要预防性写
• 经验法则：每 100 行 AGENTS.md 配 ≤ 8 条禁令
• 禁令要”具体到可验证”：不要写”don’t break things”，要写”don’t run npm install in a monorepo”

坑 4：AGENTS.md 进了仓库但 Agent 不读

症状： 写了一份完美的 AGENTS.md，Agent 进项目后照样瞎跑 npm install。

规避：

• 确认文件名拼写正确：AGENTS.md（全大写、复数、.md 小写）
• 确认在正确位置：仓库根目录，不是 docs/AGENTS.md
• 确认 Agent 版本支持：极老版本（2024 年初的）可能不认识
• Agent 启动时显式 hint（如果支持）：
  • Claude Code: 在 prompt 里写 “请先读 AGENTS.md”
  • Cursor: 在 .cursorrules 里 @AGENTS.md 强制引用
  • Codex: 默认就读，无需 hint

坑 5：子目录 AGENTS.md 和顶层互相矛盾

症状： 顶层说 “use pnpm”，apps/web/AGENTS.md 说 “use npm”，Agent 不知道听谁的。

规避：

• 子目录 AGENTS.md 只写”补充”，不写”覆盖”
• 如果必须改写顶层规则，在子目录 AGENTS.md 顶部写：

<!-- apps/web/AGENTS.md -->
# Override note
This file overrides the top-level AGENTS.md for the following rules ONLY:
- Use `npm` instead of `pnpm` in `apps/web/` (legacy reason: deploy pipeline assumes npm lockfile)
All other rules from the top-level AGENTS.md still apply.

显式说”我覆盖了什么”，Agent 才知道这是有意的，不是矛盾。

坑 6：AGENTS.md 维护成”政治文件”

症状： AGENTS.md 在 code review 里被反复改、争论措辞、加免责条款（“this is just a guideline…”）、3 个月后变成 400 行没人看。

规避：

• CI 卡住行数：超 150 行就 CI 失败
• 每个月一次维护 PR：owner 负责删过时内容、加新踩过的坑
• 改动走 PR review：和代码变更一样 review
• owner 制度：每个仓库/子包有一个明确 owner 负责 AGENTS.md 准确性
• 删掉的禁令比新增的禁令重要：项目演进了，旧的禁令要主动删

坑 7：把敏感信息（API key、内部域名）写进 AGENTS.md

症状： 写了 https://internal-api.company.com，仓库开源后泄露了内部架构；写了 sk-xxx 示例 key，被扫描器当成真 key 拉黑。

规避：

• AGENTS.md 进的是公开仓库（或将来会公开）
• 用占位符：<internal-api-host>、$INTERNAL_API_URL、{your-registry}
• 内部架构信息走 docs/internal/，用 git submodule 或独立私有仓库

---

成本 / 性能 / 维护权衡

维度	没 AGENTS.md	有 AGENTS.md	权衡建议
Agent 一次成功率	40-55%	70-85%	中型项目（5k+ 行）收益最大；100 行脚本收益小
每任务 token 消耗	baseline	+2-10k tokens（AGENTS.md 进 system prompt）	< 150 行可接受；> 300 行会显著拉高成本
PR review 返工率	30-50%	10-20%	返工主要是”忘跑测试”和”命名不对”，AGENTS.md 直接消掉
新成员上手（含 Agent）	1-2 天	30 分钟读 AGENTS.md	ROI 最高的一项
维护成本	0	0.5-2 人时/月	推 owner 制度，否则 3 个月后腐化
跨 Agent 兼容	每个 Agent 工具要单独写	AGENTS.md + 各工具 wrapper 文件	单一事实源，长期收益大

核心判断：

• 10 行以下的小脚本 / 实验项目 → 不需要 AGENTS.md，README 够用
• 100-1000 行的工具库 → 写一份 50 行 AGENTS.md，5 分钟搞定
• 1000+ 行的应用 / monorepo / 多人协作 → 必须有 AGENTS.md + 子目录版本 + CI 校验
• 公开的开源项目 → AGENTS.md 是社区贡献友好度的重要指标，几乎必写

---

一周内可执行行动清单

按优先级从高到低，建议今天就动手前 3 项：

• 今天下午（30 min）：列出团队用的所有 AI 编程 Agent 工具，到 agents.md 确认都支持
• 今天下午（30 min）：拉 2-3 个 60k+ 项目的 AGENTS.md 当参考（推荐 openai/codex、vercel/next.js、prisma/prisma）
• 今天晚上（1-2 h）：在主仓库写第一版 AGENTS.md：Project overview + Setup commands + Testing + Code style + Things to avoid（5 个段落，< 150 行）
• 明天上午（30 min）：在 monorepo / monorepo-style 项目的 2-3 个关键子目录加嵌套 AGENTS.md，只写子目录特有内容
• 明天上午（30 min）：用 @AGENTS.md 引用语法把 Claude Code / Cursor / Codex 各自的 instruction 文件指向 AGENTS.md
• 明天下午（1 h）：加 CI 校验（lint 行数、verify 命令、PR checklist 存在性）
• 明天下午（30 min）：和团队过一次 AGENTS.md，把”曾经踩过、Agent 还会再踩”的坑全加进 “Things to avoid”
• 本周内：用一个实际任务让 Agent 在新写的 AGENTS.md 下跑，对比成功率 / token 消耗
• 下周（可选）：把 AGENTS.md 接入”新成员 onboarding checklist”（无论人还是 Agent），形成组织级约定

---

一句话总结： AGENTS.md 是 AI 编程 Agent 时代的”项目级 README”，用半天时间写一份 150 行以内的命令式文档（Setup / Test / Style / Things to avoid / Before-PR checklist），在仓库根目录放好，让 25+ Agent 工具自动识别，并配 CI 校验它不腐化——你团队每次 Agent 任务的成功率能从 50% 拉到 75%+，PR 返工率减半，新人（含 Agent）上手从 2 天变 30 分钟。