谈谈我用 CLAUDE.md 给 AI 写项目约束这件事

用了大半年 Claude Code 和 Cursor，我慢慢摸索出一套用文档约束 AI 行为的方法。

不算什么高深的理论，就是怎么让 AI 在你的项目里"听话"，少犯错，别瞎改东西。

问题从哪来的

一开始用 AI 写代码，最大的感受是：它确实能写，但经常写不对。

不是说代码有 bug，而是它不遵守你项目的约定。你用 pnpm，它给你 npm install；你的路由是后端动态配置的，它直接在路由文件里加了一堆硬编码路由；你某个组件库锁了版本，它随手就给你升级了。

每次都得反复纠正，特别累。

后来发现，这些问题的根源其实很简单：AI 不知道你的项目规则。它只能从代码里猜，猜出来经常是错的。

我的解法：三级文档体系

我现在的做法是搞了一个三层结构，核心思路就八个字：索引在顶，细节按需。

第一层：全局用户规则

~/.claude/CLAUDE.md，这个文件对所有项目生效。

放的都是个人偏好和通用规则：

用 pnpm，别用 npm
不要自动启动开发服务
考虑国内网络环境，别用被墙的 CDN
Markdown 图表优先用 mermaid

很简单，十来行，但是每次对话都会加载。所以只放真正跨项目通用的东西。

第二层：项目根目录的 CLAUDE.md

这是项目的入口文件，也是最关键的一层。

我给自己定了个规矩：这个文件只能当索引用，不放细节。

它只干三件事：

项目概述——一两段话说清楚这是什么项目、用的什么技术栈
关键约束——比如"路由由后端管理，前端不要硬编码"这种踩坑型规则
文档索引——用表格列出所有详细的规则文件和设计文档在哪

这样整个文件控制在 150 行左右，AI 每次读到的上下文很少，但它知道去哪里找更详细的信息。

第三层：按子系统拆分的规则文件

我把项目的不同子系统拆成独立的规则文件，放在 .cursor/rules/ 目录下。

按编号排序：

00-project.mdc — 项目约定、目录结构、表格布局规范
01-topology-and-canvas.mdc — 画布架构、插件系统、节点嵌入
03-validation-and-forms.mdc — 表单验证、全量校验、字段联动
04-style-and-icons.mdc — 样式系统、图标加载、颜色规范
05-monaco-and-iac-dialog.mdc — Monaco Editor 集成

每个文件只管自己那块子系统，2KB 到 10KB 不等。

这样做的好处是：AI 不需要一次性加载所有规则，用到哪块读哪块。

还有一层：功能设计文档

除了规则文件，我还有一套 docs/design/ 目录，放的是功能设计文档。

规则文件告诉 AI "应该怎么做"，设计文档告诉 AI "这个功能的完整设计是什么"。两者互补。

比如"统一多层默认值系统"这个功能，设计文档里有完整的设计说明、数据流、优先级逻辑。AI 在做相关功能时，可以读这个文档来理解业务背景。

渐进式披露是关键

整个体系最核心的设计理念，就是渐进式披露。

AI 的上下文窗口是有限的，你塞太多东西进去，它反而记不住重点。所以我的策略是：

第一层给方向，第二层给索引，第三层给细节，第四层给设计。

AI 拿到第一层就知道项目大概是什么，碰到具体问题再去翻后面的文件。就像你去图书馆，先看大厅的索引，再去找具体书架上的书。

这比把所有规则都堆到一个文件里效果好得多。

还有一些小细节

文档规范要写死

我在 CLAUDE.md 里明确定义了文档规则：

docs/design/ 只放功能设计和架构说明
不放 bug 修复记录
不放临时问题解决记录
文件命名要清晰，不要带版本号

这个规范很重要，不然时间一长，docs 目录会变成垃圾场。

约束要具体，不要抽象

我见过有些人写规则是这样的：

"请遵循项目现有的代码风格和设计模式。"

这种规则等于没写。AI 根本不知道你的"现有风格"是什么。

我的写法是：

"不要在前端路由文件中硬编码业务路由。路由由后端 RuoYi 系统配置。添加新页面时，只需实现页面组件。"

具体到文件、具体到行为、具体到应该怎么做。

同步更新机制

在 CLAUDE.md 末尾我写了文档同步规则：

进行更改时：

更新相关的规则文件以反映架构变更

更新或创建设计文档以反映功能设计变更

如果添加/删除文档文件，更新索引

这样 AI 在改代码的时候，也会同步更新对应的文档，不会出现代码和文档脱节的情况。

做得不好的地方

说了这么多好的，也聊聊问题。

规则文件有内容重复

写着写着，不同文件之间会出现重复内容。比如样式规则那块，核心原则在文件开头写了一遍，后面又写了一遍。时间一长自己都搞不清哪个是最新的。

教训：每个规则只在一个地方定义，其他地方引用。

编号跳跃

我的规则文件编号从 01 直接跳到了 03，中间的 02 不知道什么时候删了。这种小问题不影响功能，但强迫症看着难受。

docs 目录有历史遗留

虽然定义了文档规范，但主 docs 目录下还是散落着一些不属于 design 子目录的文件。什么 技术背景 copy.md、code-review-fixes.md 之类的。有些是早期没规范时留下的，有些是临时文件。

说白了就是规范定得容易，执行难。

缺少"反面模式"清单

我的规则主要是"应该怎么做"，但没有集中的"不要这样做"清单。现在这些禁忌分散在各处，比如"不要用 build 命令测试"、"不要手动封装 document.cookie"。如果能集中到一个区域，AI 可能更不容易犯这些错。

CLAUDE.md 的架构摘要还是偏厚

虽然我一直在控制 CLAUDE.md 的篇幅，但"关键架构模式"那块还是写了快 40 行。这些细节在规则文件里都有更完整的描述，在索引文件里再写一遍其实是浪费上下文。

理想状态应该是每块一两句话 + 一个指向规则文件的链接。

双工具维护成本

同时维护 Cursor 的 .cursor/rules/ 和 Claude Code 的 CLAUDE.md，内容有很多重叠。目前是手动保持同步，虽然大部分内容一致，但偶尔改了一边忘了改另一边。

一个意外的收获

搞了这套体系之后，我发现一个意料之外的好处：它帮我理清了项目架构。

要把规则写清楚，你得先自己想清楚。很多时候写着写着就发现："诶，我这块的设计好像不太合理？" 于是顺手就重构了。

所以这套东西不仅是给 AI 看的，也是给自己看的。某种程度上，它逼着你把隐性知识显性化。

最后说几句

用 AI 写代码这件事，工具再好，也得有人告诉它"在这个项目里应该怎么做"。

纯靠 AI 自己看代码猜，效果一般。纯靠每次对话里口述规则，累。写好约束文档，让 AI 自己去读，是目前我觉得最靠谱的方式。

我的这套做法肯定不是最优解，但它确实解决了我的痛点。如果你也在用 Claude Code 或者 Cursor，不妨试试在自己的项目里搞一套类似的约束体系。

不用一步到位，从写好一个 CLAUDE.md 开始就行。