如何写好 agents.md：从 2500+ 仓库提炼的可执行规范

很多团队已经在给 AI 编码助手写规则文件，但效果差异很大：

1. 有的仓库里，Agent 真正变成了“稳定的专项工程师”。
2. 有的仓库里，Agent 还是“听话但不靠谱”的通用聊天机器人。

GitHub 对 2500+ 公开仓库的 agents.md 做了分析，结论很直接：决定上限的不是你写了多少“人格化描述”，而是你是否把运行环境、命令、边界和验收标准写成可执行约束。

常见失败模式是“语义正确但工程不可执行”。例如：

1. 只写“你是一个有帮助的助手”，没有任务边界。
2. 只写“负责测试”，却不给测试命令和目录范围。
3. 只写“遵守项目风格”，但没有任何示例代码。

这类文件在阅读体验上没问题，但在 Agent 运行时会出现两个后果：

1. 决策空间过大，导致行为漂移。
2. 一旦失败，缺乏可定位的修复入口。

所以 agents.md 的目标不是“描述 AI”，而是“约束自动化执行”。

结合原文中的高表现样本，可以把有效配置归纳成六个最小模块。

命令应尽量前置，并且可直接执行，不要只写工具名。

npm test
npm run build
pytest -v

工程意义很明确：Agent 需要在“可调用工具”上收敛，不是靠猜。

写清楚测试入口、失败处理策略和不可接受行为。例如：

1. 测试失败时先定位原因，再决定是否改测试。
2. 未经授权不得删除失败用例。

明确读写边界比“你很专业”有用得多：

1. src/ 只读还是可写。
2. docs/ 是否允许新增文件。
3. tests/ 是否是唯一可修改目录。

给一段真实样例，通常胜过多段抽象描述。建议至少包含：

1. 命名规则。
2. 错误处理方式。
3. 典型函数组织风格。

把“提交前必须做什么”写成显式步骤，例如：

1. 先跑 lint/test。
2. 再生成最小 diff。
3. 最后按约定格式提交。

原文里最有价值的一点是“三层边界”：

1. Always do：始终执行。
2. Ask first：高风险操作先询问。
3. Never do：明确禁区（如密钥、生产配置、供应商目录）。

这个结构能显著降低误操作概率，也便于后续审计。

不要从“万能助手”开始，先选一个可验证的小任务。原文建议的起点非常实用：

1. 文档 Agent（写 API 文档）。
2. 测试 Agent（补单测与边界测试）。
3. Lint Agent（修格式和静态检查）。

每个 Agent 至少定义三件事：

1. 名称：如 test-agent、docs-agent。
2. 描述：一句话说明输出目标。
3. 角色：它应该像谁、只负责什么。

这样做的好处是，你可以快速验证“边界是否清晰”“命令是否可跑”“输出是否可验收”。

原文一个很关键的实践观点是：好用的 agents.md 不是一次写出来的，而是通过失败样例不断补全。

推荐采用下面的迭代节奏：

1. 先上线最小版本，只覆盖一个任务。
2. 每次误行为都回填为新规则或新示例。
3. 定期检查规则是否过时，删除冗余约束。

这比一开始写一份超长“全能规范”更稳，也更符合真实工程演进。

在你把 agents.md 提交进仓库前，可以快速过一遍：

1. 是否提供了可执行命令，而不是泛化描述？
2. 是否定义了明确读写目录和禁区？
3. 是否给出了真实代码风格示例？
4. 是否包含 Always / Ask first / Never 三层边界？
5. 是否声明了项目技术栈与关键版本？
6. 是否限定了 Agent 的单一职责？

如果这六项里有两项以上缺失，通常意味着它还不是“工程配置”，只是“提示草稿”。

agents.md 的本质不是写“更会说话的 AI 人设”，而是写“可执行、可约束、可回归”的协作协议。

对团队来说，真正有复利的做法是：

1. 先用单职能 Agent 建立成功样本。
2. 再通过命令、边界和示例不断压缩行为不确定性。
3. 最后把规则沉淀为仓库级工程资产，而不是个人经验。

当 agents.md 具备这些特征时，Agent 才会从“偶尔帮忙”走向“稳定可托付”。