AGENTS.md高效编写指南：避开说明书误区

Agent 指令手术刀：别再把 AGENTS.md 写成说明书

从“写满”到“写对”

上手 AI 编程助手时，多数人卡在同一个问题：到底该写多少指引？写少了怕它抓不住重点，写多了又担心它束手束脚。结果就是，一股脑把工作习惯、代码规范、调试步骤、工具文档、项目背景全塞进 Agent 指令——甚至还要加上“请认真对待”这种空话。

写的时候挺踏实，觉得越详细 AI 就越懂你。但后来才发现，真相往往相反。

Agent 指令塞得太满，执行效率反而下降，逻辑变得混乱，维护成本直线上升。它不应该是说明书仓库，更不是教程堆叠区。常驻指令一旦“发胖”，那些真正关键的规则就被淹没了。

所以，这套方法论的核心非常明确：让 Agent 指令从“堆砌内容”转向“精准表达”。

Agent 指令不是越多越好

可以把 AGENTS.md、CLAUDE.md、GEMINI.md 这类文件想象成一张便签。

便签上写 8 条核心规则，AI 大概率会牢牢记住。但便签上写 30 页使用手册，AI 不是看不见，只是重点已被稀释到几乎失效。

所以，关键不在于“要不要写得更完整”，而在于：

这条规则，是否每次协作都必须遵守？

如果答案是否定的，它就不该出现在常驻 Agent 文件里。

这把手术刀怎么切

一个实操性很强的判断逻辑：

这张表解决了一个实际痛点：不是所有信息都要堆在同一个地方。答案不是“全写进去”，而是先判断它应该归属哪里。

哪些内容应该留在 AGENTS.md

适合留在常驻 Agent 文件里的，通常是那些长期稳定、几乎每次协作都会产生影响的规则。

比如：

• 默认使用中文回答；
• 简单问题直接回答，不要随意读取 memory、skill、项目文件或联网；
• 修改全局配置前，先提供草案，不要直接动刀；
• 当用户判断失误时，客观指出潜在风险；
• 写代码时小步修改、减少文件操作、验证通过后再报告完成；
• 不要让用户把真实 API key、token、密码直接发到聊天里。

这些规则不是针对某个特定任务，而是每次协作都可能影响最终结果的核心条款。

哪些内容不该留在 AGENTS.md

以下内容并非毫无价值，但它们不适合长期驻留在常驻文件里：

• 某个 skill 的完整说明；
• 一整套调试流程；
• 一篇文章的完整总结；
• 某个临时项目背景；
• 平台路径大全；
• 很少用到的工具说明；
• “请保持专业”“注意安全”这类没有具体触发条件的空泛建议。

它们的问题不在于“错误”，而在于“位置不对”。就像你不会每天出门都背着一本维修手册，你只需要知道：出故障时该去哪里查手册。

Skill 和 AGENTS.md 的关系

一个更清晰的理解方式：skill 是工具箱，AGENTS.md 是导航员。

比如：

• 写文章时调用写作 skill；
• 调 bug 时使用诊断 skill；
• 做 PDF 时启用 PDF skill；
• 做前端验证时借助浏览器或 Playwright skill；
• 审计 Agent 指令时使用 agent-guide。

AGENTS.md 是常驻便签。
SKILL.md 是需要时才打开的详细说明书。

所以，不要把 skill 内容完整复制进 AGENTS.md。那等于让 AI 每次上班前先背诵一堆暂时用不上的信息。更好的写法是只保留路由：

Agent 指令审计、瘦身、对比、重建：使用 agent-guide。

具体怎么审计、怎么提问、怎么对比，全部交给 agent-guide 自己处理。

agent-guide 具体怎么工作

它主要提供两种模式。

Quick Audit：快速审计

适用于你已有一个 Agent 文件，想看看它哪里臃肿。

它会先识别旧版原本希望解决什么问题，然后输出：

• Keep：应该保留的规则；
• Move：应该迁移到 skill、memory、hook、MCP、references 的内容；
• Delete：应该删除的废话或重复内容；
• Rewrite：方向正确，但需要写得更具体明确的规则；
• Risks：改完后可能丢失的能力或安全边界。

它不会为了追求简洁而盲目删减，而是先做回归检查：旧版本保护的能力，新版本是否仍然保留。

Guided Rebuild：引导式重建

适用于你想重新设计自己的 Agent 文件。

它不会直接套用通用模板，而是先提出关键问题：

• 你主要用 Agent 处理什么任务？
• 哪些 skill 你希望手动调用？
• 哪些 skill 你希望 Agent 自动路由？
• 哪些个人习惯应该存入 memory？
• 哪些操作必须事先征求你的同意？
• 你希望最终报告采用什么风格？

然后它再生成分块化的草案。

重点是：每个人的 Agent 都不一样。优质的 Agent 文件不是从万能模板复制来的，而是从这个人真实的工作流里提炼出来的。

翻车经验：三个常见坑

实操中最容易踩的坑，往往就那么几个。

第一坑：把“修改全局 Agent”误当成“修改当前项目”。当用户说想改设置里的 Agent，结果却在临时项目里新建了 AGENTS.md。这警示我们，当用户提到“全局 Agent”“Codex 的 Agent”“设置里的 Agent”时，必须先确认目标配置的来源。

第二坑：能写全局文件，不代表应该直接写。全局 Agent 指令属于个人设置，会影响后续所有对话。更稳妥的流程应该是：先读取文件，再给出草案，然后确认，最后才执行写入。

第三坑：全局 Agent 里混杂了太多 skill 细节。这会让每次启动都变得沉重。真正应该保留的是“什么时候触发哪个 skill”，具体操作细节交给 skill 自己处理。

这些坑最终都成了 agent-guide 的安全底线。

小白可以怎么开始

如果你也容易纠结、担心遗漏、最后写出一大坨，可以先从一个精简版本开始：

# Agent Instructions## 默认协作方式- 默认使用中文回答。
- 简单问题直接回答，不要随意读取 memory、skill、项目文件或联网。
- 如果我说错了，客观指出风险，不必为了迎合而忽略问题。## 文件修改原则- 先确认目标文件。
- 小步修改，不碰无关文件。
- 修改全局配置前，先提供草案。## 任务路由- 简单问题：直接回答。
- 写代码：遵守小改动、可验证原则。
- 重复流程：优先拆分成 skill。
- 当前事实：需要时查询官方来源。## 最终汇报- 改了哪些内容。
- 验证了哪些内容。
- 还有哪些未确认。

这个版本不花哨，但能先压制住最容易失控的环节。等反复遇到某类任务后，再把那类任务沉淀为 skill。不要一开始就把所有未来可能用到的东西都塞进常驻指令。

来源声明

这篇文章和 agent-guide 是阅读公开文章后，结合实践经验进行的二次整理和方法论重构。

这里不复制原文正文，不替代原文阅读，也不冒充原创首发。原文的版权、标题、作者署名和原始观点归对应原作者所有。

参考文章如下：

如果原作者认为引用、归纳或表达方式有不妥之处，可联系维护者进行修改、补充说明或删除。

结尾

Agent 指令不是越完整越好。真正重要的是：哪些规则应该常驻，哪些流程应该按需调用，哪些偏好应该存入 memory，哪些安全边界应该交给工具强制执行。能理清这些，Agent 就已经变得足够轻量，也足够可靠。

来源：互联网