18 · CLAUDE.md 完整指南：层级、写法与最佳实践

CLAUDE.md 的发现范围、层级优先级、推荐内容、反模式和维护方法，把稳定的项目规则写成 Claude 可执行的说明书。

CLAUDE.md 是你可以写给 Claude 的「项目说明书」。它会（默认）在每次任务开始前被读进来，告诉 Claude 这个项目的规矩和雷区。这一篇把它讲透。

「发现范围」：CLAUDE.md 放哪里才有效。通常放在项目根目录，就能被自动发现；有些还支持子目录的局部规则。放对位置，规则才生效。

「层级优先级」：规则可以分层——根目录一个总规则，子目录再放局部规则，越贴近具体目录的越优先。这样大项目就能「总原则 + 分模块细则」配合。

「推荐内容」是核心：一份好的 CLAUDE.md 通常包含——项目技术栈和整体结构、怎么构建和测试、代码风格约定、哪些目录或文件别乱动、常见任务的推荐做法。核心目标就一个：让 Claude 少踩坑。

「反模式」是很多人犯的错：写成一坨又长又臭的流水账、或者写了从不更新（里面是过时信息，反而误导它）。规则要精、要准、要活着。

「维护」提醒我们这不是一次性的事。项目在变，规则就跟着变，把它当项目的一部分。

CLAUDE.md 的价值，在于把「每次都要口述一遍的规矩」沉淀成「自动生效的默认值」。写好几个项目后你会发现，一份清晰的 CLAUDE.md，能显著减少返工和闯祸。

这一篇建议重点学。无论你用哪个入口、做多复杂的任务，清晰的 CLAUDE.md 都是稳定交付的地基。

常见误区：很多新手会把这一篇讲的「基本规则」当成「教条」——什么都严格遵守。其实这些规则的核心是「降低风险、提高效率」，理解了动机，规则就自然内化了，不用死记硬背。

动手试一下：你可以花 5 分钟做一个最小验证——找一个真实的代码任务，让 Codex 跑一遍，看它的行为是不是和这一篇描述的一致。理论与实践对照，才知道「懂」和「会用」是两件事。

与其他篇的关系：这一篇是本组的基础。如果你跳过了前面几篇，建议先回去看，否则这里有些概念可能看着突兀。如果都看过了，那你可以直接进入更后面的实战环节，把这里学到的东西用上。

实用清单（速记版）：① 适用场景：{场景}。 ② 关键动作：{动作}。 ③ 风险点：{风险}。 ④ 验证方法：{验证}。把这四点记住，能让你在大部分场景下做出正确决策。