别再买 AGENTS.md 模板了：真正该抄的不是提示词，是你的工程规矩

昨天刚写完“别再花钱买 Codex 资料包了”，今天早上继续用 Agent Reach 看了一圈，我觉得可以再往下拆一层。

现在被包装得最凶的，不只是 Codex 入门资料，而是 AGENTS.md。

B站上已经能搜到一堆“AGENTS.md 基础教程”“12 条规则”“三层约束实测”“附教程文档安装包”；X 上也有不少“复制 Karpathy 的 65 行配置，两分钟领先大多数 Codex 用户”的传播。更有意思的是，OpenAI Developers 在 7 月 21 日刚发了一个更新：Codex Code Review 现在可以使用 AGENTS.md 里的自定义仓库规则。

也就是说，这个文件确实重要。

但越重要，越容易被包装成玄学。

今天这篇不做“万能模板”。我更想讲清楚：AGENTS.md 到底是什么，哪些内容值得写，哪些内容只是把一堆提示词堆成付费资料包。

一、AGENTS.md 不是咒语，它是给 Agent 的入职手册

很多人第一次接触 AGENTS.md，会把它理解成“让 Codex 变聪明的提示词”。

这个理解不算错，但太浅。

更准确地说，AGENTS.md 是给 Agent 的项目入职手册。

人类新同事进一个项目，要知道目录结构、技术栈、常用命令、哪些文件不能乱动、PR 要怎么写、测试怎么跑、线上风险在哪里。Agent 也一样。你不写，它就只能每次从仓库里临时猜。

OpenAI 的 Codex best practices 里也把 AGENTS.md 放在“上下文”这一层：让 Codex 知道项目规范、检查命令、测试方式和团队约定。新出的 Codex Code Review 自定义规则，也正是沿着这个方向走：把团队反复强调的 review 规则写进仓库，让 Codex 在代码评审里按项目规矩看问题。

所以 AGENTS.md 的价值，不是“让模型听话”。

它真正的价值是减少反复沟通，把项目里那些“每次都要提醒”的规矩固化下来。

二、能卖钱的模板，通常只有前 20% 有用

我不反对参考别人公开的 AGENTS.md。

相反，好的公开配置很值得看。比如 Andrej Karpathy 的公开仓库、OpenAI 自己的 codex-rs 项目规则、agents.md 这个开放格式站点，都能帮你快速知道这个文件应该长什么样。

但模板最容易失效的地方也在这里：它不是你的项目。

别人写“用 cargo test”，你的项目可能是 pnpm。
别人写“先开 issue”，你的团队可能只看 TAPD。
别人写“每次都创建 PR”，你可能只是本地小程序临时修复。
别人写“禁止修改全局样式”，你的任务可能正好是重做设计系统。

AGENTS.md 里最值钱的部分，往往不是那些漂亮句子，而是你项目独有的约束。

比如：

这些内容很土，但它们比“请像资深工程师一样思考”值钱得多。

三、AGENTS.md 最该写的，是 Agent 容易犯错的地方

一个实用的 AGENTS.md，不应该从“我希望 Agent 多厉害”开始，而应该从“它最容易在哪里犯错”开始。

我自己的排序是这样的：

第一，工作边界。

告诉它当前项目是什么，不是什么。比如“这是前端管理后台，优先小改，不做大重构”；或者“这是公众号自动化，只创建草稿，不做最终发布”。

第二，目录和所有权。

页面在哪里，API 在哪里，状态管理在哪里，公共组件在哪里。Agent 很擅长搜索，但如果你先告诉它地图，它会少走很多弯路。

第三，命令和验证。

明确写出 lint、build、test 命令。更重要的是：不能伪造执行结果，没跑就是没跑，失败就报告失败。

第四，危险动作。

什么不能删，什么不能重置，什么需要审批，什么只能只读。Codex 的 permissions 和 approvals 设计，本质上就是把这类风险放到执行层去管。AGENTS.md 也应该告诉 Agent 哪些动作在这个项目里格外敏感。

第五，输出格式。

如果你总是要求“修改文件、改动内容、风险点、验证结果”，那就写进去。不要每次结尾再手动提醒。

一个好文件不是越长越好。它应该像一份高密度的入职备忘录：少讲愿景，多讲边界；少讲口号，多讲验收。

四、别把 AGENTS.md 写成“AI 管理学作文”

现在很多所谓模板，最大的问题不是错，而是空。

“你是顶级专家。”
“你要深度思考。”
“你要保证代码优雅。”
“你要站在用户角度。”
“你要输出生产级方案。”

这些句子看起来很专业，但对 Agent 执行任务帮助有限。

原因很简单：它们没有可操作边界。

什么叫优雅？
什么叫生产级？
什么叫深度思考？
什么叫用户角度？

如果你把它改成下面这种，价值就高很多：

前者是在鼓励模型“表现得像专家”。
后者是在告诉工具“这个项目怎么交付才算合格”。

五、AGENTS.md 不能替代权限系统

这里要泼一盆冷水。

AGENTS.md 很重要，但它管不住 API。

你可以在文件里写一百遍“不要删除数据库”，但如果 Agent 拿着生产写权限，工具层又自动批准所有命令，那你依然是在赌模型每次都记得住。

OpenAI Codex 的 permissions 文档和 approvals 机制，解决的是另一层问题：哪些文件能读写，哪些命令要审批，网络权限怎么放，什么时候需要用户确认。AGENTS.md 负责说清楚项目规则，permissions 负责让危险动作真的被挡住。

这两个东西不要混用。

AGENTS.md 写：

“不要修改生产配置；涉及部署、数据库写入、密钥、外部系统动作必须先确认。”

权限系统做：

默认只允许工作区写入；读取 home 目录、联网、执行危险命令、调用外部系统时要审批。

前者是说明书，后者是刹车。

只有说明书，没有刹车，不叫安全。

六、我建议你先写一个 80 行以内的版本

如果你现在还没有 AGENTS.md，我建议别买模板，也别一上来写 1000 行。

先写 80 行以内。

结构可以很朴素：

一段项目说明。

说清楚这是个什么项目，目标是什么，优先级是什么。

一段技术栈和目录约定。

告诉 Agent 页面、组件、API、store、utils、测试分别在哪里。

一段修改原则。

小改优先，复用现有模式，不新增依赖，不改公共接口，不碰无关文件。

一段验证命令。

列出必须跑的 lint、build、test。如果某个项目没有测试，就写“有测试再执行”，不要编一个命令。

一段安全边界。

不要删除无关代码，不要重置 git，不要改环境变量，不要处理真实发布动作，遇到凭证和生产系统要停下来。

一段结果格式。

让它最后报告改了哪些文件、做了什么、有什么风险、验证结果如何。

这已经能解决大多数问题。

后续怎么扩？不是继续找模板，而是在真实任务失败后补规则。比如 Agent 又一次忘了运行某个专项测试，那就把这个测试写进去；它又一次乱改公共组件，那就把公共组件边界写进去；它又一次把草稿当发布，那就把安全门写得更硬。

AGENTS.md 应该从事故和经验里长出来，而不是从资料包里复制出来。

七、团队版 AGENTS.md 的关键，是分层

如果是团队使用，我会分三层。

第一层，全局习惯。

写在个人全局说明或公司级说明里。比如沟通风格、默认验证态度、不要伪造结果、不要覆盖用户改动、需要审批的危险操作。

第二层，项目规则。

写在仓库根目录的 AGENTS.md。比如技术栈、目录、命令、PR 标准、测试策略、业务边界。

第三层，子目录规则。

写在某些复杂模块里。比如 src/dictionaries 的枚举规范、packages/api 的接口兼容规则、scripts/publish 的发布安全门。

这样做的好处是，规则不会全部堆在一个文件里。

Agent 进入某个目录，就能读到更贴近当前工作的约束。人类维护起来也更容易：公共原则放上层，模块细节放下层。

这比买一个“万能 AGENTS.md”更接近真实工程。

八、一份真正有用的 AGENTS.md，应该能被验证

判断一份 AGENTS.md 有没有用，不要看它写得多像专家。

看它能不能减少返工。

你可以用四个问题检查：

第一，它有没有让 Agent 少问重复问题？

如果每次任务都还要问“怎么构建、怎么测试、目录在哪”，那文件没写到点上。

第二，它有没有挡住常见错误？

比如不再乱用 any，不再硬编码枚举，不再跳过 build，不再碰无关文件。

第三，它有没有让 review 更容易？

最终汇报能不能直接看到修改范围、设计考虑、风险点和验证结果。

第四，它有没有随任务迭代？

如果 AGENTS.md 写完三个月没人改，那大概率不是成熟，而是没人真的用它。

好规则是会变的，但不会乱变。每次补充都应该来自真实失败、真实约定或真实检查项。

结尾：别买模板，买回来的也是别人的项目经验

AGENTS.md 这波热起来，我觉得是好事。

它说明大家终于意识到，AI 编程不只是模型能力问题，也是工程上下文问题。你给 Agent 的项目说明越清楚，它就越像一个能上手干活的同事，而不是一个每次都要重新培训的聊天框。

但也正因为它重要，才不该被神化成付费模板。

你当然可以参考公开配置。
你当然可以看别人怎么写。
你当然可以从一个短模板开始。

但最后那份真正值钱的 AGENTS.md，一定来自你的仓库、你的命令、你的团队习惯、你的事故、你的验收标准。

别把钱花在“复制即用”的模板包上。

先打开你自己的项目，回答几个朴素问题：

这个项目是什么？
哪些文件最容易改坏？
哪些命令必须跑？
哪些动作不能自动做？
哪些规则你已经重复提醒过 Agent 三次？

把这些写下来。

这就是第一版 AGENTS.md。

它可能不漂亮，但它有用。

而有用，才是工程里最不该被包装费覆盖掉的东西。

参考资料：