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

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

说明：这篇文章是读完几篇公开文章后，结合自己维护 Agent 指令时的踩坑记录做出的二次整理和实践笔记。它不是原文转载，也不替代原文阅读。原文链接和作者放在文中。

我一开始也把 Agent 文件写得很满

刚开始用 AI 编程助手时，我有一种很强的不安全感。

这句要不要写？那句要不要写？万一 AI 不知道怎么办？万一它乱改文件怎么办？万一它忘记我的习惯怎么办？

于是我就忍不住把一堆东西都塞进 Agent 指令里：

• 工作习惯；
• 代码规范；
• 调试流程；
• 工具说明；
• skill 内容；
• 项目背景；
• 临时提醒；
• 文章笔记；
• 各种"要认真、要专业、要小心"的话。

写的时候很安心，好像写得越多，AI 就越懂我。

后来才发现，很多时候不是这样的。

Agent 指令写太满，反而会慢、乱、难维护。它不是说明书仓库，更不是把所有教程都往里堆的地方。常驻指令越胖，真正关键的规则越容易被淹没。

所以这套 agent-guide 想做的事情很简单：

像手术刀一样，把 Agent 指令切薄、切准、切到该去的位置。

Agent 指令不是越多越好

你可以先把 AGENTS.md、CLAUDE.md、GEMINI.md 这类文件理解成：

贴在 AI 显示器旁边的一张便签。

便签上写 8 条关键规则，AI 可能真的会记住。

便签上写 30 页说明书，AI 不是完全看不见，但重点会被淹没。

所以问题不是"我要不要写得更完整"，而是：

这条规则到底该不该每次都给 AI 看？

如果答案是否定的，它就不该塞进常驻 Agent 文件。

这把手术刀怎么切

agent-guide 的核心判断表是这样的：

内容	更适合放哪里
每次都要遵守的语言、语气、安全边界	全局 Agent 指令
某个项目的构建命令、架构边界、禁改路径	项目 AGENTS.md
重复出现的多步流程	SKILL.md
会变化的个人偏好和历史经验	memory
必须强制执行的规则	hook / settings / CI / permissions
外部系统和实时信息	MCP / plugin / browser / 官方文档
长解释、术语、来源、案例	README / article / examples / references
"要认真、要专业、要小心"这类空话	删除，或改成具体触发条件和动作

这个表解决的是一个很实际的问题：

我到底要不要把这个也写进 Agent 文件？

答案不是"都写"，而是先判断它应该放在哪里。

哪些内容应该留在 AGENTS.md

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

比如：

• 默认用中文回答；
• 简单问题直接答，不要乱读 memory、skill、项目文件或联网；
• 修改全局配置前，先给草案，不要直接改；
• 用户可能会判断错时，要客观指出风险；
• 写代码时小步改、少动文件、验证后再说完成；
• 不要让用户把真实 API key、token、密码发到聊天里。

这些规则不是某个任务才需要，而是每次协作都可能影响结果。

哪些内容不该留在 AGENTS.md

这些内容不一定没用，但不适合长期塞在常驻文件里：

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

它们的问题不是"错误"，而是"位置不对"。

这就像你不会每天出门都背一本维修手册。你只需要知道：坏了去哪里查手册。

Skill 和 AGENTS.md 的关系

我现在更愿意这样理解 skill：

当 AI 做到某类事情时，才打开的一份专项说明。

比如：

• 写文章时用写作 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 是阅读公开文章后，结合实践经验做出的二次整理和方法论改写。

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

参考文章如下：

原文	作者	链接
腾讯面试官问CLAUDE.md维护，我只说了两个词，他当场愣住了！！	沉默王二	juejin.cn/post/764550...
Codex 工程化实践指南：深入理解 AGENTS.md、SKILL.md 与 MCP	Lei_official	juejin.cn/post/761666...
你大概率没用对 Claude Code 的五大能力	Niubility	juejin.cn/post/763704...
我最近把 Codex 用顺手了，分享一下我是怎么把它调成适合自己工作流的	这里有个bug	juejin.cn/post/761778...
三大编程智能体的RULES和SKILLS规范！	甲维斯	juejin.cn/post/759954...

如果原作者认为引用、归纳或表达方式不合适，可以联系维护者进行更改、补充说明或删除。

结尾

Agent 指令不是越完整越好。

真正重要的是：哪些规则应该常驻，哪些流程应该按需打开，哪些偏好应该进 memory，哪些安全边界应该交给工具强制。

能分清这些，Agent 就已经轻很多，也稳很多。