团队里每个人都在用 AI 写代码，可它输出的风格、目录、命名各写各的，评审时一半时间花在纠正它。这篇从 .cursorrules 这个项目规则文件讲起：它到底管什么、和普通提示词差在哪、团队规范该怎么拆成几条能落地的规则，最后给一份可以照着填的模板思路。属于接入与开发分区的配置类速查，不涉及具体模型效果对比。
团队里每个人都在用 AI 写代码，结果风格、目录、命名各写各的，代码评审一半时间花在纠正它而不是业务逻辑上。这篇讲 .cursorrules 这个项目规则文件：它到底管什么、和普通提示词差在哪、团队规范该怎么拆成几条能落地的规则，最后给一份能照着填的模板骨架。属于接入与开发分区的配置类速查，不涉及模型效果对比。
先说清边界：它管的是模型在你这个项目里怎么干活，不管模型本身行不行。幻觉、算错数、凭空编接口这些属于另一类问题，站内已有专门文章处理，别指望靠规则文件解决。你要动手改配置前，建议先到 /guide 看当时的接入与指南目录，确认自己该看哪一篇。
.cursorrules 到底管什么，和随手写的提示词差在哪
它是一份放在代码仓库里、随项目走的纯文本规则文件，编辑器生成代码时把它当上下文一起读，所以约束每次都生效，不用你每开一个对话就重新交代一遍。提示词是「这一次我想要什么」，规则文件是「这个项目一直不许做什么」，一个管输出内容，一个管风格、结构和边界。
- 作用范围
- 约束模型在你项目里的写法与边界，不改变模型本身能力
- 生效方式
- 随仓库提交、随项目走，队友拉到代码就一起生效
- 不该放的内容
- 账号、内部地址、业务数据这些会随文件被提交和分享的东西
- 不适用场景
- 一次性脚本、临时验证想法、只读不改别人的仓库
判断你要不要加它，看一个信号：同一类问题在代码评审里被反复提。如果评审里从没出现过「命名又乱了」「这文件不该动」这类重复评论，加规则文件收益很低，先把流程理顺更划算。
规范怎么拆条：从「评审时你会挑的刺」倒推
拆条原则是「一条规则对应一类可被检查的毛病」。写不出检查方法的规则就是废话，比如「代码要优雅」应该改成能对照的具体写法，否则模型只能猜，你也只能凭感觉验收。
| 分组 | 写什么 | 判断写好的标准 |
|---|---|---|
| 技术栈与版本约束 | 语言、框架、允许的依赖范围 | 新人照它选库不会选错 |
| 目录与命名 | 新文件放哪、类名函数名怎么起 | 给一个真实文件路径当参照 |
| 风格与注释 | 函数长度、注释写在哪 | 能在评审里一眼对照检查 |
| 禁止事项 | 不许改的文件、不许引的依赖、不许打印敏感信息 | 违反了能直接指出是哪一条 |
- 每条尽量带正例或反例，写「不要用长函数」不如写「单个函数超过几十行就该拆，参考某个具体文件的分层」
- 规则条目不是越多越专业，超过你能记住并维护的数量就开始互相打架
- 团队里通常按模块拆成一份主文件加几份局部补充，别硬塞进一个文件
- 禁止事项优先写，因为它收益最快，命名与目录次之，风格细节最后雕琢
动手写：一份规则文件的四步成型法
- 先别写，先摘评论翻最近几次代码评审的评论，把重复出现的问题摘出来。这些就是最该先写进去的规则，验证方式是看它们是否对应真实发生过的返工。
- 按分组归档并压缩把摘出来的问题按技术栈、目录命名、风格注释、禁止事项四类归档，每条压到一两句话，形容词能删全删。
- 放进仓库根目录跑真实任务让队友各自用真实需求验证，看模型是否真的按规则改代码。判断依据是产出代码是否符合规则，而不是它有没有夸这份文件写得清楚。
- 定期清理过期条目规则一旦被写进代码检查工具或提交钩子，就从文件里删掉让自动化去管。文件只留机器不好判的部分，验证方式是检查文件长度是否还在可控范围。
顺序上建议先写禁止事项，因为违反一次代价最大，收益最快；再写命名与目录，最后才雕琢风格细节。想先了解不同接入方式下规则文件的加载差异，可以到 /tools/speed-test 看当时的接入测试说明再动手。
放进团队流程：谁改、多久看一次、怎么防止失修
规则文件最大的死法是失修：某人本地改了没提交，或者依赖升级了条目没删，别人拉到仓库却不知道它已经过期。所以它必须进流程，不能当私人配置。
- 指定一个维护人，规则改动走和代码一样的评审流程
- 给关键规则加一句「什么时候该删」，比如依赖升级后相关约束同步清理
- 新人上手时把规则文件当读物之一，比口头交代「我们这边习惯这么写」省事
- 涉及业务数据、内部地址、账号信息的规则留在环境变量或密钥管理里，不进文件
- 每隔一段时间集中看一次，把已经自动化覆盖的条目删掉，避免文件越堆越长
谁适合维护？不是最懂 AI 的人，而是最常做代码评审的人，因为规则来源就是评审里的重复问题。一个五人小团队通常一个人维护主文件、各模块负责人维护局部补充即可。
模板骨架：照这个结构填就行
骨架分四块，照着填，条目内容必须来自你自己项目的真实评审记录。直接抄别人的规则文件大概率水土不服，因为技术栈和目录结构对不上。
| 部分 | 写什么 | 例子形式 |
|---|---|---|
| 开头 | 项目定位和技术栈 | 这是什么服务、用什么语言和框架 |
| 主体一 | 禁止事项 | 不许改某个目录、不许引某类依赖 |
| 主体二 | 目录与命名 | 新文件放哪、命名怎么起，给一个文件路径 |
| 主体三 | 风格与注释 | 函数长度、注释写在哪 |
| 结尾 | 不确定时的处理方式 | 先问再改、改动前说明影响范围 |
结尾那条「不确定时怎么做」最容易被忽略，但能挡掉不少自作主张的改动。规则文件本身不承诺产出质量，它只是把团队共识固化成每次生效的上下文；具体效果和不同接入方式的差别，到 /rankings 和 /sites 核对当时的数据再判断。
常见问题
写了 .cursorrules 是不是模型就不会写错代码了？
不是。它只约束风格和边界，让输出更符合你项目习惯，减少返工，但改不了模型本身的知识盲区和推理错误。把它当「减少沟通成本的约定」而不是「质量保证」，真正兜底还得靠测试和评审。另外文件太长、条目互相冲突时，模型反而会顾此失彼。
一个人开发的小项目有必要写吗？
看你是否反复交代同样的事。如果每次都要告诉它目录结构、不要动某个文件，那写一份短的值得；如果只是临时写几个脚本，不写更省事。判断标准很简单：最近几次你重复说过的要求超过三条，就值得落成文件。
规则文件里可以写内部业务逻辑和接口细节吗？
谨慎。这份文件通常会提交到仓库、分享给协作者，也可能被同事复制到别处，写进去等于扩散。建议只写结构性约定，比如模块职责和命名规则；具体的接口地址、数据字段、账号信息放环境变量或专门的密钥管理里，需要时在对话中单独说明。
