目录一、CLAUDE.md 必写第一类AI 读得到却会违背的硬规矩提示语模板给一条硬约束立门禁CLAUDE.md 代码示例门禁规则的落地写法二、CLAUDE.md 必写第二类记录否决过的架构取舍提示语模板让 AI 别再翻案已定的取舍三、CLAUDE.md 必写第三类文档骨架与同步契约提示语模板给堆成黑箱的 AI 文档补骨架四、CLAUDE.md 不该写什么AI 能自行归纳的别写五、总结三类写全一轮恢复全部上下文给 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 听话的是哪一条评论区聊聊。