小白装好 AI 编程助手不会用？可能是没看完这篇胎教级 Agent 指令说明书
说明：这篇文章是我读完几篇掘金文章后的二次整理和个人实践笔记，不是原文转载，也不是说这些观点都是我原创的。原文链接和作者我放在文首，大家最好去看原文。
先把原作者写清楚
这篇小白笔记主要参考了下面几篇文章。先说明一下，免得大家觉得全是我自己想的：
| 原文 | 作者 | 链接 |
|---|---|---|
| 腾讯面试官问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… |
其实主要是我自己归纳总结、踩坑复盘，再加一点实践延伸，原文内容没有直接复制。
我一开始也写得很臃肿
我才学了一个月左右的 vibe coding，水平确实有限。很多时候不是我不想写清楚，是真的会纠结半天。
这句要不要写？那句要不要写？万一 AI 不知道怎么办？万一它乱改文件怎么办？
然后我就会忍不住把一堆东西都塞进 Agent 指令里：工作习惯啊、代码规范啊、调试流程啊、工具说明、skill 内容、项目背景……甚至有些只是我当时脑子里突然蹦出来的提醒。
写的时候觉得挺安心，好像写得越多，AI 就越懂我。
但现在回头看，大概就是典型的新手没有安全感，不太确定该怎么办，就先一股脑全塞进去再说。
后来才慢慢发现，不是这样的。
Agent 指令写太满，反而会慢、乱、难维护。它不是什么说明书仓库，更不是把所有教程都往里堆的地方。
Agent 指令到底是什么
你可以先把 AGENTS.md、CLAUDE.md、GEMINI.md 这类文件理解成：
贴在 AI 显示器旁边的一张便签。
便签上写 8 条关键规则，AI 可能真的会记住。
便签上写 30 页说明书，AI 不是完全看不见，但重要东西会被淹没。
所以重点不是“写得多专业”，而是“写得少一点、准一点、真的能改变行为”。
不同工具叫法也不太一样。
比如 Codex 常见是 AGENTS.md，Claude Code 常见是 CLAUDE.md，Gemini CLI 常见是 GEMINI.md，Cursor 常见是 .cursor/rules。
有些人会口语化叫它 codex.md、claude.md，或者“某某工具的 agent 文件”。名字不完全一样，但讨论的是同一类问题：哪些规则应该常驻，哪些流程应该拆出去。
我现在理解的核心原则
一句话：
常驻规则只放长期、稳定、每次都要知道、模型自己容易猜错的东西。
其它东西要拆出去。
| 内容 | 更适合放哪里 |
|---|---|
| 每次都要遵守的语言、语气、权限边界 | 全局 Agent 指令 |
| 某个项目的构建命令、架构边界、禁改文件 | 项目 AGENTS.md |
| 一套重复多步流程 | SKILL.md |
| 会变化的个人经验和项目教训 | memory |
| 必须强制执行的规则 | hook / settings / CI |
| 外部系统和实时信息 | MCP / plugin |
| 大量参考资料 | references |
这个表对我这种小白特别有用，因为它解决了一个很折磨的问题：
我到底要不要把这个也写进 agent 里？
答案不是“都写”，而是先问：它应该常驻吗？如果不是每次都要知道，那可能就该分流到别的地方。
什么东西该留在 AGENTS.md
适合留下来的，一般是这种：
- 我默认用中文交流；
- 小问题不要乱读记忆、skill、项目文件；
- 修改全局配置前，先给草案，不要直接改；
- 我是普通人，可能会判断错，需要客观指出风险；
- 写代码时小步改、少动文件、验证后再说完成；
- 哪些路径不能碰，哪些命令要谨慎。
这些东西不是某个任务才需要，而是每次协作都容易影响结果。
什么东西不该留在 AGENTS.md
这些就不太适合长期塞在全局指令里：
- 某个 skill 的完整说明；
- 一整套调试流程；
- 一篇文章的完整总结；
- 临时项目背景；
- 平台路径大全；
- “注意安全”“写得优雅”这种空话；
- 很少用到的工具说明。
它们不是没用，而是不该每次都加载。
这就像你不会每天出门都背一本维修手册。你只需要知道：坏了去哪里查手册。
Skill 是干嘛的
我现在会把 skill 理解成：
当 AI 做到某类事情时，才打开的一份专项说明。
比如：
- 写文章时用写作 skill；
- 调 bug 时用诊断 skill；
- 做 PDF 时用 PDF skill；
- 做前端验证时用浏览器/Playwright skill；
- 审计 Agent 指令时用 Agent Instruction Scalpel 这种 skill。
它和 AGENTS.md 的区别是：
AGENTS.md是常驻便签；SKILL.md是需要时才打开的说明书。
所以不要把 skill 内容完整复制进 AGENTS.md。那样等于你让 AI 每次上班先背一堆暂时用不上的东西。
我自己的翻车经验
这轮我自己也踩了几个坑。
第一个坑：我说想改设置里的 agent，AI 先在当前临时项目里新建了一个 AGENTS.md。
这就说明指令一定要写清楚：当用户说“设置里的 agent”“全局 agent”“Codex 的 agent”，要先确认目标配置来源，不要默认当前目录就是目标项目。
第二个坑：AI 技术上能写全局文件，但不代表应该直接写。
全局 Agent 指令属于个人设置，会影响后面所有对话。更稳的做法应该是：先读文件，再给草案，再确认，最后才写。
第三个坑：全局 Agent 里混进了太多 skill 的具体内容。
这会让每次启动都变重。真正应该保留的是“什么时候触发哪个 skill”，具体怎么做交给 skill 自己。
小白可以怎么开始
如果你也和我一样，一开始容易纠结、怕漏、最后写一大坨，我建议别急着追求完美。
先写一个很短的版本：
# Agent Instructions
## 默认协作方式
- 默认用中文回答。
- 小问题直接答，不要乱读记忆、skill、项目文件或联网。
- 如果我说错了，客观指出，不要为了顺着我而忽略风险。
## 改文件原则
- 先确认目标文件。
- 小步修改，不碰无关文件。
- 修改全局配置前，先给草案。
## 任务路由
- 简单问题：直接回答。
- 写代码：遵守小改动、可验证原则。
- 重复流程：优先拆成 skill。
- 当前事实：需要时查官方来源。
## 最终汇报
- 改了什么。
- 验证了什么。
- 还有什么没确认。
这个不高级，但很有用。
至少它能先把最容易乱的地方按住，不至于一上来就让 AI 背一整本说明书。
等你真的反复遇到某类问题，再把它沉淀成 skill。
这篇文章型 Skill 想解决什么
我想做的不是一个“自动帮你改配置”的工具。
它更像一个方法论：
当 AI 看到一份臃肿的 Agent 指令时，知道怎么分类、怎么删、怎么拆、怎么保留 attribution，最后给一个更清楚的版本。
它适合 Codex，也适合 Claude Code、Cursor、Gemini 这类工具。
平台名字会变，路径也可能变，但这个原则基本不变：
Rules 管常驻规则，Skills 管按需流程，Hooks/Settings 管强制执行，MCP/Plugin 管外部能力。
我把这个方法整理成了一个 GitHub 仓库：
里面有给 AI 看的 SKILL.md，也有这篇文章、来源笔记、名词附录和翻车记录。感兴趣的话可以直接看，或者拿去继续改。
结尾
我现在也不敢说自己完全搞懂了，反正就是先别急着把所有东西都塞进 AGENTS.md。
能分出来哪些该常驻、哪些该放 skill、哪些该交给工具，已经比一开始一股脑全写进去好很多了。
后面肯定还会改，毕竟我也才学一个月。先能用，少乱，慢慢变清楚，就这样。
