CLAUDE.md / .cursorrules 怎么写？别写项目说明书，只写这三类

给 AI 编程助手写 CLAUDE.md / .cursorrules，很多人第一反应是把项目从头介绍一遍：技术栈、目录分层、命名风格、提交规范，一口气写十页。

然后 AI 该乱来还是乱来。

问题不在 AI 笨，而在于那十页里很多内容它自己就能从代码读出来：技术栈看依赖清单，目录分层看文件结构，命名规范扫几行代码就能归纳。

CLAUDE.md 该写的不是“AI 能读到什么”，而是“AI 会不会照做”。

一、CLAUDE.md 该写什么：三类内容

判断标准：不是能不能读到，是会不会照做。

二、第一类：AI 读得到却会违背的硬规矩

举一个真实例子：项目用 CodeFirst，数据库结构由实体类定义，框架启动时自动同步，不手写迁移脚本。

但 AI 看到“加字段”时，容易给出：

ALTER TABLE xxx ADD xxx ...

这不是因为它没读到项目做法，而是因为训练数据里“改数据库”的主流做法就是迁移脚本。AI 会把主流做法默认平移到你的项目上。

这种规矩要写成门禁：

## 数据库变更门禁

- 唯一真相源：实体类定义。
- 禁止：ALTER TABLE、CREATE TABLE、手写迁移脚本、直接 DDL。
- 正确做法：通过实体类变更，让框架自动同步。
- 命中风险时：先停手，说明冲突，再给符合项目约定的方案。

写法原则：

• 默认禁止 + 白名单：不要写“尽量不要”，要写“默认禁止”。
• 正反都写：既写正确做法，也写禁止形式。
• 统一术语：逼 AI 用项目里的词思考，不用主流词滑回主流写法。

三、第二类：否决过的方案和取舍

AI 读代码能知道“现在用了什么”，但它很难知道“为什么不用另一个方案”。

所以你不写，它就会反复翻案。比如项目早就决定不引入某个消息中介库、不拆某个复杂分层、不走某种“业界标准”架构，AI 换个需求又会把它加回来。

每条重要取舍建议写五项：

还要补一道规则：方案撞上已定决策时，AI 必须停手指出冲突，请用户定夺，禁止以“用户明确要求”为由绕过。

四、第三类：文档骨架和同步契约

文档多不等于体系成型。

背景、领域、流程、决策都写了，如果没有入口，新人和 AI 还是不知道从哪看起；改了业务代码，如果没有同步契约，文档很快就会开始说谎。

骨架只需要三样：

1. 全局导航：一份 README / index，把人和 AI 引到正确起点。
2. 能改 / 不能改清单：事实源不许动，可再生产物授权内改。
3. 同步契约：改了哪类代码，必须同步哪些文档。

多套规则并存时，不要每份都写全。更稳的是：

单一真相源 + 分层链接 + 明确仲裁顺序

两份都写全，早晚漂移。

五、CLAUDE.md 不该写什么

AI 读代码就能正确照做的，别写。

比如技术栈、目录结构、普通命名规范，多数情况下它自己能归纳，也会跟随。你再写一遍，只会占上下文预算，稀释真正重要的规则。

但数据库变更这种硬规矩不一样：AI 读得到，却容易违背，所以必须写，而且要写成门禁。

六、总结

CLAUDE.md / .cursorrules 写得好不好，不看字数，看新会话能不能一轮就上手。

三类写全：它会违背的硬规矩、它读不到的取舍、它串不起来的骨架。
这三类不写，十页规则也拦不住 AI 乱来。

你项目里最该补进 CLAUDE.md 的，是硬规矩、技术取舍，还是文档骨架？