CLAUDE.md怎么写，给失忆的新员工一本入职手册

想象你开了家小店，每周都来一个帮忙的新店员。麻烦在于，这些店员全都失忆，每个人上班第一天，都不知道收银机怎么开、哪个抽屉的钱不能动。

你有两个选择。每来一个就口头交代一遍，累，而且总会漏讲，新人总在同一个地方出错。或者写一份入职手册贴在门后，新人来了先看手册，立刻知道怎么干、哪里是雷区。

CLAUDE.md 就是那份贴在门后的入职手册，只不过这个失忆的新员工叫 Claude Code。

它有个新手最容易忽略的特点，每开一个新会话都是一张白纸，完全不记得上次聊过什么。这不是它笨，是设计如此。所以「让 AI 更听话」的关键，从来不是每次费劲重新解释项目，而是把那些话写进一份它每次开工都会先读的手册里。

这份手册治的病非常具体，叫重复解释。不写的日子是这样的，你让 AI 加个登录功能，它不知道你们用什么框架、测试怎么跑，瞎猜一个写法；你纠正它，我们用 pnpm 不用 npm，组件放在 components 里；第二天新会话，它又忘了，你又得解释一遍。写一次手册，终身免当复读机。

该写和不该写，一对照就清楚

新手最容易翻车的地方不是不会写，是写错了东西，把篇幅花在没用的内容上，真正要紧的边界反而漏了。

该写的都是 AI 干活真用得上的事实。真实可复制的命令，比如跑测试用什么、启动开发环境用什么。具体的禁区，比如不要动环境变量文件、不要直接往主分支推。项目特有的约定，比如用 pnpm 不用 npm、提交信息写中文。验收标准，比如改完必须测试全过才算完成。

不该写的也有一类，模糊指令（「记得测试」「跑一下看看」）、空泛态度（「注意安全」「保持高质量」）、通用常识（「这是个 TypeScript 项目」，它本来就知道）、以及缩进引号这类格式问题，那些归代码检查工具管，写进手册纯属浪费篇幅。

光看分类不够直观，看几组真实改写。注意代码质量，改成「改完必须跑测试，全过才提交」。不要乱改东西，改成「不要修改 dist 目录和环境变量文件，改了会出事」。保持风格统一，改成「新组件优先复用 components 里已有的，不要重造」。好好写测试，改成「新功能必须配单元测试，放在同名测试文件里」。发布要小心，改成「发布前必须先确认，不要自动执行部署命令」。

发现规律了吗？好写法全都能用「做没做到」来判断，坏写法只是态度。

老雷写手册时有一条铁律，每写一条规则，先问自己「这条能不能检查」。「保持整洁」检查不了，「不要在 src 目录外新建文件」一眼就能查。检查不了的，要么删掉，要么改写成能检查的动作。一份全是态度没有动作的手册，AI 读了等于没读。

判断要不要写的土标准

很多人纠结，我的项目这么小，值得专门写这个文件吗。

判断标准不看项目大小，看任务会不会重复。哪怕是个练手小项目，只要打算反复让 AI 改它、读同一套目录、守同一批命令，就值得花十分钟写一份。真正不需要写的，只有问完这一次就再也不碰的临时问答。

重复，才是这份文件回本的前提。

内容上还有几条边界要划清。老雷的土话版本是，手册里每个字都要么是一句命令、要么是一条红线，别让它变成抒情散文。别人的通用大道理不要抄进来，AI 本来就懂。整棵目录树不要原样贴进来，占篇幅没重点，写「什么东西在哪」的一句话指引就够。代码格式规则不用写，缩进引号分号归检查工具管。以及最容易踩的坑，个人偏好别混进项目手册，你不喜欢太长的回答，那是你的偏好，写进项目手册会绑架所有用它的人。

还有一个更隐蔽的翻车点，手册写得太长。这类文件有大小上限，超出部分会被静默截断，也就是说你精心写的后半本，AI 根本没读到。所以手册要克制，只写项目特有的、容易踩的铁律，通用大道理 AI 本来就懂，写进去只会挤掉真正关键的规则。每写完一版问自己一句，删掉一半还成立吗。

两份模板，最小版和进阶版

最小版五行起步，二十行封顶。三块内容，项目是什么（一两句话）、怎么运行和测试（真实可复制的命令）、哪里绝对不能碰（具体路径和文件）。

给个最小版的样子，照着改就能用。开头一句写清项目是什么，比如「这是一个博客系统，用某框架搭建，部署在某个平台」。接着是命令区，启动用什么、测试用什么、部署前要跑什么检查，一条一行真实可复制。最后是禁区，不要动环境变量文件，不要直接往主分支推代码。五行到十行，就够 AI 少走九成弯路。

进阶版在最小版之上加四块。技术栈和关键依赖，防止 AI 自作主张换方案。目录指引，说清 API 处理、页面组件、工具函数各在哪个文件夹。验收标准，改动完成的硬性条件，比如测试全过加文档更新。禁区清单，明确不能动的文件、目录和操作，以及发布类动作必须先确认。

一个检验手册质量的好办法，找个没接触过项目的同事，只给他手册，让他复述「这个项目怎么跑、哪里不能碰」。复述得出来，手册合格；复述不出来，说明写的都是废话。

这个测试反过来用在 AI 身上更准。把手册喂给 AI，让它复述项目的运行方式和禁区——复述不出来的部分，就是手册写得不够清楚的部分。AI 是这份手册最严格的审稿人。

进阶版再补四块。技术栈和关键依赖，防止 AI 自作主张换方案。目录指引，说清 API 处理、页面组件、工具函数各在哪个文件夹。验收标准，改动完成的硬性条件，比如测试全过加文档更新。禁区清单，明确不能动的文件和操作，以及发布类动作必须先确认。

写完之后还有两件事要做。第一，让手册跟着项目长，每次发现自己在对话里重复解释同一件事，就顺手补进手册。第二，多项目的人建一层全局手册，管自己的通用偏好，项目手册管具体项目的规矩，两层各管各的，项目层的具体规则优先于全局层的通用习惯。

写完之后的两件事

手册不是立碑，是活文件。第一件事，让它跟着项目长。每次你发现自己在对话里重复解释同一件事，就顺手把这句话补进手册。跑了两个月，这份文件会从二十行长到六七十行，全是真枪实弹。

第二件事，多项目的人建一层全局手册。项目手册管具体项目的规矩，全局手册管你个人的通用偏好，比如回答风格、注释习惯。两层各管各的，项目层的具体规则优先于全局层的通用习惯。

CLAUDE.md 治的不是 AI 的笨，是你的重复。把每次都要说的话写一次，以后每次开工它自己先读。

想起连锁餐饮的打法。为什么连锁店能开遍全国，因为总栈把「每家店每天要做的所有事」写成了标准操作手册，任何一家新店开业，照着手册跑就能出品一致。没有手册的夫妻店，味道全看老板当天心情。

你的 AI 项目，值得一本手册。