给 AI 编码助手写规则文件（CLAUDE.md、.cursorrules、AGENTS.md），大多数人第一反应是把项目从头介绍一遍：技术栈、目录分层、命名风格、提交规范，一口气写了十页。然后 AI 该乱来还是乱来。

问题不在 AI 笨，在于那十页里绝大多数内容 AI 自己就能从代码读出来。技术栈看依赖清单，分层看目录，命名规范扫一遍现有代码就归纳出来了。

太长不看版：规则文件该写的是 AI 光读代码补不上的三类——①它读得到却会违背的硬规矩；②它根本读不到的取舍和否决；③散落各处它串不起来的骨架。三类写全，新会话一轮对话就能恢复项目全部关键上下文。

先用一张表说清 CLAUDE.md / .cursorrules 该写什么、不该写什么：

类别	写不写	判据	举例
技术栈、目录结构	不写	AI 读代码就能正确照做	package.json / go.mod 已说明一切
命名规范（无违背风险）	不写	读得到、也会照做	驼峰/下划线，扫一遍代码就归纳出来
① 会违背的硬规矩	必写	读得到、却会违背	CodeFirst 项目里 AI 手写 ALTER TABLE
② 否决过的取舍	必写	AI 根本读不到	为什么不用 MediatR / 某设计模式
③ 文档骨架	必写	散落各处串不起来	导航 + 边界清单 + 同步契约

判据从来不是"能不能读到"，是会不会照做。

以下三类都来自我维护的一个真实后端项目（.NET + SqlSugar），但道理跨语言通用。每类附一条可直接复用的提示语模板。

一、CLAUDE.md 必写第一类：AI 读得到却会违背的硬规矩

核心规律：AI 会把训练数据里最主流的做法默认平移到你的项目上，哪怕你明明选了别的。 你的方案越"小众但合理"，AI 越想"好心"掰回来。

我的项目用 CodeFirst（实体类就是数据库结构唯一来源，框架启动时自动同步表），不写迁移脚本。可 AI 选择性失明——你说加字段它甩 ALTER TABLE，写数据校验它直接查库核对列，写回滚它写删列 DDL。因为它训练里"改数据库"的主流范式是 Rails/Django 那套迁移文件。

手写改动会造出和代码定义脱节的"影子结构"，两个真相源打架，排查掉一把头发。把 CodeFirst 换成你项目里任何"框架自动管、你别手动碰"的东西，道理一样。

光写"别手动改"没用，AI 过两轮就忘。三条通用原则：

• 默认禁止 + 白名单：只开几个白名单口子，命中时必须报出第几条。
• 正反都写：正面说"用 X"不够，得把禁用形式逐条列死。
• 统一措辞：逼 AI 用你项目的术语思考，用主流词想就会滑向主流做法。

提示语模板：给一条硬约束立门禁

我要给 AI 协作立一条硬约束：本项目用了"框架自动维护、不该手动绕过"的机制——
我的例子是数据库结构由代码定义、框架启动时自动同步（.NET CodeFirst），
禁止 AI 手写 ALTER TABLE / 迁移脚本去绕过它。
（换成你项目里那个"框架管、别手动改"的东西。）

请落成逃不掉的门禁：
1. 为什么：这种主流写法在本项目为何主动有害。
2. 触发点：AI 在相关需求下，生成代码前必须检查。
3. 判定：出现被禁形式即违例；给出正确做法。
4. 违反时：停下来提示正确做法，不准自作主张。
5. 落地：这条该写进哪几层规则文件。
只输出门禁成品，不解释过程。

CLAUDE.md 代码示例：门禁规则的落地写法

## 数据库变更 — 硬约束

- **唯一真相源**：`src/Wuwei.Api/Entity/` 下的实体类。框架启动时 CodeFirst 自动同步表结构。
- **禁止**：手写 ALTER TABLE、CREATE TABLE、迁移脚本、直接 DDL。
- **白名单**：仅在以下情况可绕过——
  1. 用户明确要求（必须在对话中显式说出"我需要手写 DDL"）
  2. 紧急线上修复（事后必须补文档）
- **命中时**：报出命中第几条白名单，给出 CodeFirst 正确做法。
- **统一措辞**：说"让框架自动同步"，不许说"改表结构"或"加迁移"。

二、CLAUDE.md 必写第二类：记录否决过的架构取舍

你得把"为什么"和否决过什么单独写下来，否则 AI 会反复翻案。

我项目里有编码规范（代码长什么样）、有决策记录（选了什么），但缺"为什么这么设计"。于是 AI 每接新需求就重新引入早被否决的方案——它总想塞 MediatR（消息中介库），搭更"标准"的架构分层。不是它坏，是它不知道那次否决不是疏漏，是权衡过有代价的取舍。

补法：

• 每条原则带五元组：原则 / 为什么 / 接受什么代价 / 反例 / 对应代码位置。
• 反例钉在真实事故上：零宽空格导致映射失败、空 catch {} 吞异常任务卡僵尸、全字段更新把空值写进库。跨语言通用。
• 配门禁：方案撞上已定决策时 AI 必须停手 → 指出违反哪条 → 请你定夺。禁止以"用户明确要求"为由绕过——这是 AI 越界时最常用的挡箭牌。

提示语模板：让 AI 别再翻案已定的取舍

我有一个有记录的架构否决：{我们故意不用 X，如 MediatR / 某设计模式 / 某库}。
请分两步帮我固化：

第一步，产出"为什么否决 X"的说明：讲清这不是疏漏，是权衡过的取舍——
放弃了什么、换来了什么、什么情况下才重新考虑。

第二步，基于说明设门禁：
- AI 撞到与 X 相关的选择时，先读说明再动手；
- 要引入 X = 违例，必须先征得我同意；
- 违反时硬停说明冲突、给替代方案，不准偷偷引入；
- 禁止以"用户明确要求"为由绕过。
只输出两样成品，不解释过程。

三、CLAUDE.md 必写第三类：文档骨架与同步契约

文档堆到几十份后暴露的问题：内容多 ≠ 体系成型。三十来个文件，背景领域流程决策全有，但新人和 AI 进来仍不知从哪看起，改了代码没人知道同步哪些文档。

骨架三样东西：

• 全局导航：一份索引 / README 引到正确起点。
• 能改 / 不能改清单：事实源不许动（项目定位、安全、License），可再生产物授权内放手改。
• 同步契约：“改了哪类代码 → 必须同步哪些文档”。

铁律：多套规则并存时，"单一真相源 + 分层链接 + 明确仲裁优先级"远比"每份都写全"耐维护。 我原本有一份很长的 IDE 规则，补"给人读的契约"时没复制一遍，写成摘要 + 链接 + 仲裁顺序：代码事实 > AI 工作流 > 规则文档。

提示语模板：给堆成黑箱的 AI 文档补骨架

我的项目已堆了 {N} 份 AI 协作文档（背景、领域、流程、决策、任务都有），
内容充实但新人不知道从哪看起，改完代码文档还在说谎。
请帮我补"骨架"，不是再加内容：
1. 全局导航：一个 README/index 作为入口。
2. 同步契约："改了哪类代码 → 必须同步哪些文档"。
3. 能改/不能改清单：哪些是事实源、哪些是可再生产物。
只产出骨架本身，不塞新业务内容。

四、CLAUDE.md 不该写什么：AI 能自行归纳的别写

AI 读一遍代码就能正确照做的，别写。 技术栈、目录结构、那些它一眼能归纳又不会违背的命名规范——它自己就学对了，你再写一遍白占上下文还稀释真正重要的几条。

判据从来不是"能不能读到"，是会不会照做。

五、总结：三类写全，一轮恢复全部上下文

规则文件写得好不好不看字数，看新会话能不能一轮对话就上手且不翻旧账。三类写全——它会违背的硬规矩、它读不到的取舍、它自己串不起来的骨架——一轮恢复全部上下文。写代码的事 AI 能替你干很多，但"什么不能碰、为什么这么选"它替不了你，除非你写下来。

你项目的 CLAUDE.md 或 .cursorrules 里最让 AI "听话"的是哪一条？评论区聊聊。