AGENTS.md 能给编码代理什么——而 README 文件给不了的

---

前言：一个让我头疼的问题

先说一个我反复遇到的失败场景。

团队给一个编码代理（coding agent）一个仓库、一个任务，可能还附带了一个 README。代理能找文件、能写代码，但它仍然得猜很多隐藏规则：它猜包管理器是什么、它猜哪些检查是重要的、它猜生成的文件能不能改、它猜“做完”到底是什么意思。

你可能会说：“那 README 里写清楚不就行了？” 但问题是，README 通常是写给人看的：告诉人这个项目是干嘛的、怎么跑起来、重要文档在哪。编码代理需要的上下文完全不同——它需要的是操作规则，而不是项目介绍。

这个缺口，就是 AGENTS.md 要填的。

README 和 AGENTS.md 的分工

官方的 AGENTS.md 指南把它描述成一个可预测的存放编码代理指令的地方：安装命令、测试命令、代码风格、安全注意事项，还有对大型 monorepo 的嵌套指令。

我觉得这个区分在更实际的层面上也很有用：

• README 回答的是：“这个项目是什么？”
• AGENTS.md 回答的是：“代理在碰这个项目之前，应该知道什么？”

第二个问题才是让工作变得脆弱的地方。因为代理一旦猜错，就可能删掉不该删的文件、用错包管理器、或者提交了不该提交的代码。

用 Goose 来让这个区别更具体

Goose 是一个开源的本地 AI 代理，它不只是个聊天框——它有桌面应用、CLI、API、MCP 扩展和技能（Skills）系统。在没有 AGENTS.md 的时候，我发现自己得写这样的 prompt：

“更新文档，但不要碰生成的文件，用 pnpm，运行 lint 和测试命令，保持 PR 小一点，告诉我哪些是你没法验证的。”

有了 AGENTS.md 之后，prompt 可以缩短成：

“更新新配置参数的 quickstart 文档。”

Goose 可以在仓库里直接执行任务，而仓库本身就携带了那些固定的操作指令。

我是在一次小型的文档/配置更新中注意到这一点的。当时生成文件和源文件混在一起。没有仓库指令的时候，prompt 必须带上包管理器、生成文件的边界、检查命令以及“告诉我哪些是你没法验证的”这条规则。一旦这些规则写进了 AGENTS.md，prompt 就只剩下任务本身了。

不是魔法，只是减少了忘记那些无聊细节的机会。

技能（Skills）该怎么安排

一旦 AGENTS.md 开始真正干活，我建议再加一层：技能。

AGENTS.md 不应该变成每个重复工作流程的粘贴板——那样它就会变成一个“杂物抽屉”。更干净的拆分方式是这样的：

• AGENTS.md：存放固定规则（你希望代理每次进来都遵守的）
• 技能（Skills）：描述可重复的任务流程（比如数据库迁移、API 变更、发布）
• MCP 和扩展：给代理提供访问工具和数据的能力

这个分层在 Goose 里也很清晰。Goose 有一个 技能市场（Skills Marketplace），里面可以放可重用的指令集和可选的辅助文件。

举个例子，对于一个后端服务来说，AGENTS.md 可以把迁移、API 变更和发布分别路由到不同的技能上。这样 AGENTS.md 文件保持简短，而任务流程可以在别的地方写得足够详细。

判断标准很简单：

• 如果这条规则几乎每个任务都要用，放在 AGENTS.md 里。
• 如果这是一类工作的可重复流程，做成一个技能，然后在 AGENTS.md 里通过路由引用它。

一个值得尝试的小工作流

找一个你已经在使用编码代理的低风险仓库，试试这个：

1. 添加一个 AGENTS.md 文件，包含五个部分：

Setup（安装）

记录被认可的安装和运行命令。比如：

pnpm install
pnpm dev

Checks（检查）

记录最小可靠的测试、lint、类型检查命令。比如：

pnpm test
pnpm lint
pnpm typecheck

Boundaries（边界）

告诉代理哪些文件、数据或操作它不应该碰。比如：

- 不要编辑 `generated/` 目录下的任何文件
- 不要修改 `node_modules/`
- 不要删除或修改数据库中的数据
- 不要发布或部署任何东西

Done criteria（完成标准）

告诉代理在停止之前应该提供什么证据。比如：

- 运行了所有相关检查（或解释为什么没运行）
- 总结改了哪些行为
- 列出剩余风险或后续步骤
- 确保没有包含密钥、私有数据或本地路径

Skills（技能）

把可重复的任务流程路由到对应的技能。比如：

- 数据库迁移 → 使用 migration-review 技能
- API 变更 → 使用 contract-checking 技能
- 发布 → 使用 release-notes 技能

2. 然后，用同样的任务试两次：

任务：为一个新的配置参数添加示例。

• 第一次：没有 AGENTS.md，看看你需要在 prompt 里解释多少东西。
• 第二次：加上 AGENTS.md，再问一次。

有用的测试标准是：

• 代理是不是运行了正确的检查？
• 它是不是避开了生成文件？
• 你的 prompt 是不是变短了？

如果答案都是“否”，那说明 AGENTS.md 可能写得太模糊、太长，或者包含了代理无法执行的指令。

一个可用的 AGENTS.md 模板

如果你不想从零开始，可以直接用这个：

# AGENTS.md

## Project Map
- `src/` contains application code.
- `tests/` contains tests.
- `docs/` contains user-facing docs.
- `generated/` is produced by tooling; do not edit it manually.

## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`

## Working Rules
- Keep changes scoped to the user's request.
- Prefer existing helpers before adding abstractions.
- Do not deploy, publish, migrate, or delete data without explicit approval.
- Do not include secrets, private data, or local-only paths in committed files.

## Completion
- Run the relevant checks or explain why they were not run.
- Summarize changed behavior.
- List remaining risk or follow-up.

## Skills
- For database migrations, use the migration review skill.
- For API changes, use the contract-checking skill.
- Before a release, use the release-notes skill.

这个模板已经足够有用，而且短到有人愿意维护它。

哪些东西不该放进去

不要放这些：

• 架构论文——代理不需要了解项目的历史哲学
• 理想化的价值观——比如“我们应该永远写干净的代码”，代理听不懂
• 仓库里的每一个命令——只放最小可靠的命令
• 你不希望出现在 prompt 日志里的私有上下文——假设一切都会被记录

如果某条指令不会改变代理的行为，就砍掉它。

我的最终结论

AGENTS.md 不是一个神奇的安全层。它只是一个简单的地方，用来放你一直在重复的那些指令：安装、检查、边界、以及“做完”的定义。

对我来说，实际的衡量标准是：

代理能不能用更少的提示词完成一个小任务，并且仍然展示它跑了哪些检查？

如果能，说明仓库变得更明确了。如果不能，说明文件还需要改进。

就这么简单。