CLAUDE.md 怎么写？让 Claude Code 少乱改的 6 条规则

20260521-claude-md-rules-cover

有一次我只让 Claude Code 改一个很小的登录判断。

需求不复杂：账号被禁用时，不要继续走后面的登录流程，直接返回错误。

它确实把判断补上了。

但我打开 diff 一看，心态马上变了。

它顺手格式化了 controller，改了几个无关命名，还动了一个公共工具类。

这次改动从“看一眼业务判断”，变成了“我要重新审一遍它到底动了什么”。

那次我最后没敢直接合。

我把登录判断留下，把格式化撤掉，公共工具类也回滚了。

真正浪费时间的不是改代码，而是重新判断哪些改动是必要的，哪些只是它顺手带出来的。

小改动变成大 diff

那次之后我才意识到，问题不一定出在 Claude Code 不听话。

很多时候，是我写给它的项目规则，本来就没法执行。

这件事之后，我才开始认真改 CLAUDE.md（Claude Code 会加载的项目级指令文件）。

不是补更多“请认真一点”，而是把规则写成能限制 diff 的边界。

这个时候打开 CLAUDE.md，里面配置的内容大概是这样：

• • 不要乱改。
• • 注意代码质量。
• • 先理解再修改。
• • 像高级工程师一样工作。

问题是，这几句话没有告诉 Claude Code：

• • 这次只能改登录校验。
• • controller 不能整文件格式化。
• • 公共工具类要不要动，必须先说明理由。
• • 只跑启动命令，不能算验证完成。

Claude Code 看到的是一句提醒，不是一份具体任务单。

口号式规则变成可执行任务单

对 AI Agent（能连续读文件、改代码、跑命令的 AI 助手）来说，你不把这些事写清楚，它只能猜：这次能改哪些文件，改之前要看哪些调用方，改完要跑哪些测试，哪些没验证必须明说。

这些没写清楚，CLAUDE.md 写再长，也只是好看的口号。

从那以后，我就不太把 CLAUDE.md 当愿望清单了。

它更像一份行为合同。它管不了所有问题，但能让 Agent 少乱动、少瞎猜，改完能验收。

后来我看到 Mnilax 分享的一组 CLAUDE.md 规则，方向是对的。

但我不太想直接照抄。

规则这种东西，放进项目以后，真正要看的不是“像不像最佳实践”，而是下一次 Agent 乱改时，你能不能拿它拦住。

所以这篇不讲神奇模板，重点放在一个具体问题上：怎么把好听的规则，改成 Agent 真能执行、人也能验收的规则。

口号为什么拦不住大 diff

后来我回头看那份 CLAUDE.md，问题其实挺明显。

它不是没写规则。

相反，它写了不少。

但这些规则都有一个共同问题：每一句都要靠人类常识补全。

比如：

不要乱改。

这句话的问题不是态度不对。

问题是 Agent 没有你的项目背景。

你没写清楚时，它拿不到这些边界：这个任务只允许改登录校验，公共工具类不能碰，格式化整个文件也算越界。

再比如：

注意代码质量。

对人来说，代码质量是一个经验词。对 Agent 来说，得拆成可检查的东西：

• • 后来的人能不能读懂。
• • 出问题能不能定位。
• • 需求变化后能不能继续改。

我不建议把规则区写成资料库。

项目背景、API 文档、架构图，可以放在附录或引用文件里。规则区只留会触发动作的句子。

把一句提醒拆成 4 行

我后来不是一上来就想做模板。

我只是想把“不要乱改”这句话写得能拦住下一次事故。

拆到最后，我发现它至少要回答 4 个问题。

这 4 行不是格式要求。

它其实是一条规则的验收顺序。

它在防什么错：
什么时候触发：
Agent 要做什么：
怎么验收：

比如原来写：

不要乱改代码。

可以改成：

它在防什么错：Agent 为了完成当前任务，顺手改了无关文件、命名和格式。
什么时候触发：需要修改代码、配置、文档或目录结构时。
Agent 要做什么：先说明本次修改范围；只改完成目标必需的内容。
怎么验收：收尾时列出改动文件、验证动作和没有触碰的边界。

再比如原来写：

测试一下。

可以改成：

它在防什么错：只跑了命令，却没有证明业务规则是对的。
什么时候触发：新增或修改代码、脚本、配置后。
Agent 要做什么：优先运行现有测试；没有测试时给出可重复的最小验收命令。
怎么验收：说明测试覆盖了什么、没有覆盖什么、失败时停在哪里。

再补一个更常见的技术规则。

原来写：

处理好异常。

可以改成：

它在防什么错：失败时只吞异常、只打印一句日志，后面没人知道哪里坏了。
什么时候触发：新增接口、脚本、外部调用、文件读写或批处理逻辑时。
Agent 要做什么：说明失败分支怎么处理；保留必要错误信息；不要把异常包装成成功。
怎么验收：列出失败场景、日志或返回信息，以及没有覆盖的异常边界。

写到这里，规则才开始有用。Agent 知道该做什么，你也知道该怎么检查它。

已有项目先补 6 条边界

如果项目里已经有 CLAUDE.md，先别急着整份重写。

下面这 6 条不是另一套口号。

它们是 4 行模板的压缩版。先直接贴进去用，真遇到反复踩坑，再把某一条展开成 4 行。

## AI Agent 工作规则

- 开工前先说明目标、范围、输入资料、输出物和成功标准。
- 修改已有内容前，先读目标文件、直接调用方和相关公共工具。
- 只改当前任务必须改的内容，不顺手格式化、重构和改名。
- 沿用当前项目已有风格；发现两套冲突写法时，说明选择理由。
- 测试要验证真实行为，不能只证明有返回值或命令能跑。
- 未跑测试、跳过边界、部分失败或结果不确定时，必须明说。

6 条边界规则示意图

它们分别挡的是这几类问题：

• • 目标没说清，Agent 自己补剧情。
• • 文件没读完，就开始改。
• • 小改动变成大范围重排。
• • 项目已有风格被它另起一套。
• • 只跑命令，没有验证业务行为。
• • 没做完，却说“已完成”。

这 6 条我不会说它们高级。

恰恰相反，它们都很土。

但我现在越来越觉得，项目里的 Agent 规则先别追求完整，先挡住最常见的坑。

它们基本覆盖了 Agent 最容易出问题的几个位置：

• • 开工前，别让它猜。
• • 修改中，别让它乱扩范围。
• • 收尾时，别让它把“跑过命令”说成“验证完成”。

先把这一步做到位，后面少很多“它为什么又乱改”的返工。

新项目先别写成百科

如果是新项目，我不会一开始就写很长。

我会先放一版很短的入口规则，只覆盖 5 个区域：

• • 目标和边界。
• • 修改前检查。
• • 改动范围。
• • 测试和验收。
• • 安全边界。

完整模板我放到文末附录。

真正重要的是：不要一次写满，而是先挡住最常见的越界、漏测和假完成。

已有规则文件的项目，也不要整段覆盖。把缺的部分合进去就行。

以后只有 Agent 反复犯同一类错时，才追加规则，而且仍然按 4 行模板写。

多个 Agent 别维护两份规则

如果你团队里也在用 Claude Code、Codex 或 Cursor，这件事最好早点统一。

我一开始也想过，Claude Code 一份规则，Codex 再写一份规则。

后来觉得这事迟早会乱。

同一条“不要顺手格式化”，在两个文件里各写一遍，过几周大概率会出现两个版本。

所以我现在的做法是：通用规则只维护一份。

截至我写这篇时，OpenAI Codex 文档里也把 AGENTS.md 当成项目规则入口：Codex 开工前会先读它。

通用规则放在 AGENTS.md。

CLAUDE.md 只放 Claude Code 专属说明，以及怎么引入通用规则。

复杂排障、检查清单、固定工作流，不要都塞进入口文件。可以做成 Skill，或者单独放成可复用的流程文档。

本次对话里的临时要求，就只留在本次对话里，不要污染长期规则。

多 Agent 规则分层示意图

如果项目已经有 AGENTS.md，可以按 Claude Code 官方文档里的 @路径 写法，在 CLAUDE.md 里引入它。

@AGENTS.md

## Claude Code

- Claude Code 专属规则写在这里。

通用规则只维护一份，工具差异单独补充。

复制很快，维护起来很烦。

CLAUDE.md 不是刹车

CLAUDE.md 会被 Claude Code 加载进当前会话上下文，也就是模型当下能看到的一组规则和资料，用来影响它理解项目、执行任务和收尾汇报。

但这里不要把它和 auto memory 混成一个概念。

auto memory / MEMORY.md 是另一套长期记忆机制，用来记录和索引项目里的可复用信息。

CLAUDE.md 更像项目入口规则，告诉 Claude Code 这个项目怎么工作；auto memory / MEMORY.md 更偏向持续记录和复用项目记忆。

它不是权限系统，也不是硬开关。写得模糊、冲突或太长，Claude 还是可能自己选一种解释。

规则与安全控制关系示意图

所以写 CLAUDE.md 时，重点不是把所有资料都塞进去，而是放那些会反复影响执行行为的规则。

写完以后，用 3 个问题验收

写完规则后，我现在只先问 3 个问题：

• • 这条规则在防什么错？
• • Agent 具体要做什么？
• • 我能不能拿它验收结果？

规则验收 3 问示意图

至于触发条件、是否高频、有没有和旧规则冲突、有没有暴露密钥和私有信息，这些当然也要检查。

但如果前面 3 个问题都答不上来，这条规则基本不用急着放进入口文件。

等它真的反复触发，再进入 CLAUDE.md 或 AGENTS.md。

先拿一句口号试运行

我现在不太相信那种一次写完、永远正确的 CLAUDE.md。

项目会变，工具会变，Agent 犯错的方式也会变。

所以规则文件最好也别写成圣经。

先找一句最像口号的话，把它改成 4 行。

比如：

注意代码质量。

然后把它改成 4 行：

它在防什么错：
什么时候触发：
Agent 要做什么：
怎么验收：

下一次让 Agent 做一个小任务，只看它有没有说清楚 3 件事：

• • 改了什么。
• • 验了什么。
• • 哪些没验。

如果说不清，这条规则还是废话。

别纠结 CLAUDE.md 要不要更长。

你就问自己一句：这条规则，我能拿着它去验收吗？

附：第一版 CLAUDE.md 模板

如果你确实是从零开始，可以先用这一版。

别把它当最终答案。它只是一个起点。

# 项目工作规则

## 目标和边界

- 开工前先说明目标、范围、输入资料、输出物和成功标准。
- 信息不足时先问，不把猜测包装成结论。

## 修改前检查

- 修改已有内容前，先读目标文件、直接调用方和相关公共工具。
- 没看懂组织方式时，先说明疑点，不直接重写。

## 改动范围

- 只改当前任务必须改的内容。
- 不顺手格式化、重构、改名或优化无关区域。
- 发现两套冲突写法时，选更近、更稳定或测试更多的一套，并说明理由。

## 测试和验收

- 测试要验证真实行为，不能只证明有返回值或命令能跑。
- 没有自动化测试时，给出可重复的最小验收命令或人工检查步骤。
- 未跑测试、跳过边界、部分失败或结果不确定时，必须明说。

## 安全边界

- 删除、覆盖、批量移动、提交、推送前，先说明目标、影响范围和替代方案。
- 不读取、不输出密钥、账号、客户信息、内部地址和私有路径。

参考资料

• • Mnilax 的 X 原帖：https://x.com/Mnilax/status/2053116311132155938
• • Claude Code 官方文档：https://code.claude.com/docs/en/memory
• • Claude Code Skills 官方文档：https://code.claude.com/docs/en/skills
• • OpenAI Codex AGENTS.md 官方文档：https://developers.openai.com/codex/guides/agents-md