告别 README：为什么你的代码库必须立刻增加一个 AGENTS.md？

很多同学应该都有这样的感觉：

以前我们接手一个项目，第一件事是看 README.md。

现在让 AI Agent 接手一个项目，它也会先问几个问题：

• 这个项目怎么安装依赖？
• 修改完要跑什么测试？
• 哪些目录不能随便动？
• 代码风格到底听谁的？
• 线上配置、权限、支付、埋点这些地方有没有禁区？

如果这些内容只散落在 README、Confluence、飞书文档、口头约定、CI 报错里，那人类同学还能靠经验猜一猜，AI Agent 就很容易一脚踩进去。

这也是我最近特别建议大家给代码库加一个 AGENTS.md 的原因。

它看起来只是一个 Markdown 文件，但它解决的是一个很现实的问题：给 AI Agent 一份进入代码库前必须先读的工作说明书。

好了，开始我们的正文学习吧。

为什么写这篇文章

最近有一个挺有意思的信号：SQLite 仓库里也出现了 AGENTS.md。

SQLite 是一个很老牌、很克制、很工程化的项目。它不是那种为了赶 AI 热点每天换架构的项目，所以它加 AGENTS.md 这件事本身就很有意思。

我去看了一下 SQLite 当前仓库里的 AGENTS.md，第一句话是：

Guidance for AI coding agents working in this repository.

翻译过来很直白：这是给在这个仓库里工作的 AI 编码 Agent 的指导。

注意，这句话没有说“这是 README 的升级版”，也没有说“以后人类不用看文档了”。它说的是：AI coding agents working in this repository。

也就是说，README.md 更多是给人看的，告诉你项目是什么、怎么开始、怎么贡献；AGENTS.md 更像给 AI Agent 的“入场规则”，告诉它在这个仓库里怎么工作、怎么验证、哪些事不能乱来。

这件事看起来不大，但真正用起来很关键。

因为 AI Agent 最大的问题，往往不是不会写代码，而是不知道这个项目里的“规矩”。

本文你能学到什么

看完本文后，你应该能弄清楚这几件事：

• AGENTS.md 到底是什么，它和 README.md 有什么区别
• 为什么现在给代码库加 AGENTS.md 已经很有必要
• 一个能立刻用起来的 AGENTS.md 应该写哪些内容
• Codex、Cursor、Claude Code、Gemini CLI、GitHub Copilot、Aider、Amp、OpenCode、Cline 等工具到底默认读什么文件
• 最后给你一个可以直接复制到项目里的模板

文章不准备只讲概念，重点还是落到“你今天回去怎么加”。

AGENTS.md 是什么

一句话解释：

AGENTS.md 是写给 AI 编码 Agent 的项目说明文档。

更准确一点，它是一份仓库级别的上下文文件，用来告诉 Agent：

• 项目是什么技术栈
• 本地怎么启动
• 修改代码后怎么验证
• 代码风格和目录边界是什么
• 哪些命令不能乱跑
• 哪些业务逻辑要特别小心
• 提交前需要满足什么条件

官方的 AGENTS.md open format 给它的定位也很简单：Think of AGENTS.md as a README for agents.

OpenAI Codex 的官方文档也明确写到，Codex 会在工作前读取 AGENTS.md，并且支持全局、仓库、子目录多层叠加。也就是说，你可以在 ~/.codex/AGENTS.md 写自己的通用偏好，也可以在项目根目录写项目规则，还可以在某个服务目录下写更细的约束。

这和我们以前写文档的思路不太一样。

以前的文档大多是“给人介绍项目”：

# README.md

这是一个订单系统。

## Quick Start

npm install
npm run dev

现在的 AGENTS.md 更像“给 Agent 分配工作边界”：

# AGENTS.md

## Project Overview

This is a Node.js order service. It uses Nest.js, TypeORM, and Redis.

## Commands

- Install: pnpm install
- Dev: pnpm dev
- Test: pnpm test
- Lint: pnpm lint

## Working Rules

- Do not modify database migrations unless the task explicitly asks.
- After changing service logic, run pnpm test.
- Keep DTO validation decorators in sync with API docs.

你会发现，它不需要写得很漂亮，但一定要写得很清楚。

README 不是没用了，而是分工变了

标题里说“告别 README”，这里先打个补丁：不是说 README.md 没用了。

README.md 依然很重要，它解决的是人类协作问题：

• 这个项目是什么
• 为什么存在
• 怎么安装
• 怎么贡献
• 谁在维护
• 有哪些相关链接

但 AI Agent 进项目以后，它更需要的是另外一类信息：

• 修改代码前要看哪些目录
• 不能碰哪些文件
• 怎么跑最小测试集
• 失败时先看哪些日志
• 生成代码要遵守什么模式
• 什么时候必须停下来问人

这些内容放在 README 里不是不行，但会让 README 越来越臃肿。

更合理的方式是分工：

所以不是 README 被淘汰了，而是 AI Agent 需要一份更适合它的说明书。

为什么现在必须加

1. Agent 不怕没能力，怕没上下文

很多 AI 编码工具现在已经能做不少事：改 bug、补测试、迁移组件、解释代码、生成 PR。

但你会发现，只要项目稍微复杂一点，它最容易翻车的地方不是语法，而是上下文：

• 明明项目用 pnpm，它偏要用 npm install
• 明明测试要跑某个 workspace，它跑了根目录命令
• 明明这个目录是自动生成代码，它直接手改
• 明明公司有内部组件规范，它重新造了一个
• 明明某个接口不能改返回结构，它顺手“优化”了

这些问题靠模型“聪明”并不稳定，最靠谱的方式还是写清楚。

2. 规则写在对的地方，Agent 才容易稳定执行

我们以前也会把规则写在聊天里，比如：

你改完以后记得跑测试。

问题是这句话只对当前对话有效。

换一个 Agent、换一个会话、换一个同事，规则又没了。

AGENTS.md 的价值就在这里：它把团队规则变成代码库的一部分。只要 Agent 支持读取这个文件，它进入仓库时就能自动拿到这些上下文。

这就像以前我们把构建流程从“口头约定”搬到 package.json scripts，把格式化规则从“大家自觉”搬到 .prettierrc。

现在轮到 AI Agent 的工作规则了。

3. 多 Agent 时代，需要一个共同入口

以前一个项目可能只接一个 IDE 插件，现在不一样了。

一个团队里可能同时有人用：

• Codex
• Cursor
• Claude Code
• Gemini CLI
• GitHub Copilot
• Aider
• Amp
• OpenCode
• Cline

如果每个工具都维护一份自己的规则文件，很快就会出现一个问题：规则不同步。

今天 CLAUDE.md 说用 pnpm，明天 .cursorrules 说用 npm，后天 .github/copilot-instructions.md 忘了更新测试命令。

最后不是 Agent 傻，是我们自己给了它好几份互相打架的说明书。

所以我更建议把 AGENTS.md 当成“跨 Agent 的主入口”，再按工具需要做薄薄的适配。

一个好用的 AGENTS.md 应该写什么

这部分是本文重点。

我建议先别追求大而全，先写四个板块，今天就能用起来。

第一块：项目概况

Agent 需要先知道自己在哪。

这里不用写公司战略，也不用复制 README，写清楚技术栈和核心目录就够了。

## Project Overview

This repository is a monorepo for the train growth system.

- `apps/web`: React frontend
- `services/bff`: Nest.js BFF service
- `packages/ui`: shared UI components
- `packages/utils`: shared utilities

Main stack:

- TypeScript
- React
- Nest.js
- pnpm workspace

这块的目标不是让 Agent 读懂整个公司业务，而是让它别一上来就找错目录。

第二块：开发和验证命令

这块非常重要。

很多 Agent 不是不会改，而是不知道改完怎么证明自己没改坏。

你需要明确告诉它：

## Commands

Use `pnpm`, not `npm`.

- Install dependencies: `pnpm install`
- Start frontend: `pnpm --filter web dev`
- Start BFF: `pnpm --filter bff dev`
- Run unit tests: `pnpm test`
- Run lint: `pnpm lint`
- Type check: `pnpm typecheck`

如果项目很大，最好再补一句：

For small changes, prefer the most specific test command for the touched package.
Do not run full e2e tests unless the task explicitly asks for it.

这样 Agent 就不会每次都跑一个半小时的全量测试，也不会完全不跑测试。

第三块：代码规范和项目边界

这块用来告诉 Agent：什么是“符合本项目风格”的代码。

例如：

## Code Style

- Keep code in TypeScript.
- Reuse existing utilities before adding new helpers.
- Follow the current module structure.
- Do not introduce new state management libraries.
- Do not add production dependencies without asking.
- Keep public API response shapes backward compatible unless requested.

这里有一个小技巧：不要只写“保持代码质量”，这种话太虚了。

要写具体规则：

• 不要新增生产依赖
• 优先复用已有组件
• DTO 和接口文档要同步
• 不要改自动生成文件
• 不要绕过已有权限校验

Agent 需要的是可执行规则，不是口号。

第四块：Agent 工作约束

这是 AGENTS.md 和普通 README 最大的区别。

你可以直接告诉 Agent 工作方式：

## Agent Workflow

- Before editing, inspect existing patterns in nearby files.
- Keep changes focused on the requested task.
- Do not refactor unrelated code.
- If a change touches payment, auth, or permissions, explain the risk before editing.
- After editing, summarize changed files and verification results.

如果是生产项目，我还建议加一段安全边界：

## Safety Rules

- Never print secrets, tokens, cookies, or private keys.
- Do not modify `.env`, deployment configs, or CI secrets unless explicitly requested.
- Do not run destructive database commands.
- Ask before changing migrations or data backfill scripts.

这些规则平时看着啰嗦，但真出事时很值钱。

一个可以直接复制的模板

下面这份模板可以直接放到项目根目录。

如果你的项目比较简单，先用这版就够了。

# AGENTS.md

Guidance for AI coding agents working in this repository.

## Project Overview

Describe this repository in 3-5 lines:

- Main product or service:
- Main language/framework:
- Package manager:
- Important directories:

## Commands

- Install dependencies:
- Start development server:
- Run unit tests:
- Run lint:
- Run type check:
- Build:

Notes:

- Use the package manager already used by this repo.
- Prefer targeted tests for the package or files you changed.

## Code Style

- Follow existing patterns in nearby files.
- Reuse existing utilities/components before adding new ones.
- Keep changes focused on the requested task.
- Do not introduce new production dependencies without asking.
- Do not modify generated files unless the task explicitly requires it.

## Safety Rules

- Never print or commit secrets.
- Do not modify `.env` files, deployment settings, or CI secrets unless explicitly requested.
- Ask before changing database migrations, permission logic, payment logic, or data backfills.

## Verification

Before finishing a coding task:

- Run the smallest relevant test or check.
- Report what command was run and whether it passed.
- If verification was not run, explain why.

## Pull Request Notes

When summarizing changes:

- List the files changed.
- Explain behavior changes.
- Mention tests or checks run.
- Call out any remaining risk.

写到这里，你的项目已经比很多项目更适合 Agent 工作了。

主流 AI 工具到底读什么文件

这里单独整理一下，因为很多同学会搞混。

先说结论：AGENTS.md 正在变成越来越多 coding agent 的共同语言，但还没有统一到所有工具。

截至我写这篇文章时，我按官方文档和公开资料整理如下：

这里不要死记名字，记住一个原则就行：

AGENTS.md 做主入口，工具专属文件做适配。

比如你的项目可以这样放：

.
├── AGENTS.md
├── README.md
├── CLAUDE.md
├── GEMINI.md
└── .github/
    └── copilot-instructions.md

其中 CLAUDE.md、GEMINI.md、copilot-instructions.md 不需要再复制一大堆内容，可以写得很薄：

# CLAUDE.md

Please follow the repository guidance in `AGENTS.md`.

或者：

# GEMINI.md

Use `AGENTS.md` as the source of truth for repository conventions, commands, and safety rules.

这样做的好处是，团队只维护一份主规则，不同工具都能尽量对齐。

AGENTS.md 怎么写才不容易变成废纸

文档最怕两件事：

一是没人写。

二是写了没人维护。

AGENTS.md 也一样。

我建议注意这几个点。

1. 先短后长

不要一开始就写 300 行。

先把最容易让 Agent 犯错的 10 条规则写进去：

• 包管理器
• 启动命令
• 测试命令
• 不能碰的目录
• 不能加的依赖
• 改完要验证什么

能用起来，比完整更重要。

2. 规则要可验证

不要写：

- Write high quality code.

这种话基本没用。

改成：

- Run `pnpm lint` after changing TypeScript files.
- Add or update tests when changing business logic.
- Do not change public API response fields unless requested.

规则越具体，Agent 越容易执行。

3. 把踩坑写进去

如果某个坑你已经踩过，就不要让 Agent 再踩一次。

例如：

## Known Pitfalls

- `packages/api-client` is generated from OpenAPI schema. Do not edit it manually.
- `legacy/order.ts` is still used by offline jobs. Do not remove exports without checking usages.
- Payment callbacks must remain idempotent.

这部分对老项目特别有用。

很多项目的知识不是写在 README 里，而是写在老同事脑子里。

现在可以先搬一部分到 AGENTS.md。

4. 让 PR 更新它

如果你新增了测试命令、迁移了包管理器、调整了目录结构，就顺手更新 AGENTS.md。

可以把它当成一种轻量级工程资产。

就像改了 API 要更新接口文档，改了 Agent 工作规则也要更新 AGENTS.md。

常见问题

AGENTS.md 要用中文还是英文？

都可以。

如果团队主要中文协作，可以中文写；如果你的 Agent、开源贡献者、外包团队混合使用，英文会更通用。

我个人更建议：标题和命令用英文，业务解释可以中文。

比如：

## Safety Rules

- 不要修改支付回调逻辑，除非任务明确要求。
- Do not commit secrets.

Agent 能理解，人也能看懂。

需要每个目录都放一个 AGENTS.md 吗？

不需要。

先在仓库根目录放一个就够了。

只有当某些目录规则明显不同，比如 services/payment、packages/ui、infra，再考虑加局部文件。

Codex 这类工具支持从全局、项目根目录一路叠加到当前目录，越靠近当前目录的规则越具体。

这对 monorepo 很有用。

能不能直接把 README 改名成 AGENTS.md？

不建议。

README 面向人，AGENTS 面向 Agent，读者不同，内容重点不同。

更好的做法是：

• README 继续讲项目介绍和入门
• AGENTS 写 Agent 工作规则
• 两者必要时互相链接

AGENTS.md 会不会泄露内部信息？

会，所以不要写敏感信息。

不要把 token、账号、内网地址、生产库连接串、客户隐私、真实密钥写进去。

可以写规则，不要写秘密。

例如可以写：

- Never print or commit secrets.
- Ask before changing deployment configs.

不要写：

- Production database password is xxx.

这个不用解释，谁写谁背锅。

总结

如果你现在已经开始在项目里用 AI 编码工具，我建议你今天就加一个 AGENTS.md。

不要等到它很完美。

先写清楚这几件事：

• 项目是什么
• 用什么包管理器
• 怎么启动
• 怎么测试
• 哪些目录不能动
• 哪些业务逻辑要小心
• 改完怎么验证

以前我们给新人准备 README，是为了让人更快进入项目。

现在我们给 AI Agent 准备 AGENTS.md，是为了让它别靠猜来改代码。

这件事不复杂，但很值得做。

如果你的代码库已经开始有第二个 Agent 进入，那 AGENTS.md 就不是“加分项”了，而是新的项目基础设施。

参考资料

• AGENTS.md open format
• SQLite AGENTS.md
• OpenAI Codex: Custom instructions with AGENTS.md
• Cursor Rules
• Windsurf / Cascade AGENTS.md
• Claude Code Memory
• Gemini CLI configuration
• GitHub Copilot repository custom instructions
• Aider conventions
• Amp AGENT.md update
• OpenCode Rules
• Cline Rules