Cursor 规则文件（.cursorrules）怎么写才不踩坑：5 个能直接抄的实战模板

很多团队上手 Cursor 之后，第一反应是装一堆插件、记一堆快捷键，却忽略了一个更省事的东西：规则文件。简单来说，它是一份给 AI 编辑器看的「团队约定书」，告诉模型这个项目用什么框架、命名怎么定、测试怎么跑、哪些坑别踩。把它写好，AI 生成的第一版代码就更接近团队规范，人工返工明显变少。本文不堆概念，直接给你 5 个能抄的实战模板，覆盖新项目初始化、Python 后端、前端组件、SQL 与测试几个常见场景，并讲清楚每条约定为什么这么写、写在哪、踩过哪些坑。这类文件的价值不在长，而在于把那些「只说一遍就会忘」的约定固化下来，让每次对话都从同一套基线开始——这恰恰是 AI 编程 协作里最被低估的一步。

一、规则文件到底解决什么问题

规则文件通常指项目根目录下的 .cursorrules（新版 Cursor 也支持 .cursor/rules/ 目录下的多文件规则）。它的作用是在每次对话开始时，把一段固定提示词自动注入上下文，相当于给 AI 预设了角色和约束。和聊天里临时叮嘱一句不同的是，它是持久化的，换人、换会话都不会丢。

理解这一点很重要：它解决的是「重复沟通成本」和「风格漂移」。你不需要每次都说「用 Python 3.11、用 type hints、别用 print 调试」，写进文件后模型默认就照做。它本质是团队约定的载体，把零散规范变成可执行的默认约束，比口头要求可靠得多。也正因为如此，文件写得好不好，直接决定了 AI 在你项目里是「帮忙」还是「添乱」。

二、五个可直接抄的模板

下面五个模板覆盖最常见场景，你按项目类型挑用，不必全上。

模板一：通用项目骨架

新建仓库时，先用一份通用骨架把基础约定锁死，避免后面每个人各写各的。

# 项目约定
- 语言：优先使用类型标注（type hints），变量名用小写蛇形。
- 禁止在业务代码里用 print 调试，统一用 logging。
- 提交前必须跑 lint 与单元测试，零警告才允许合入。
- 注释只解释「为什么」，不解释「是什么」。
- 遇到不确定就提问，不要臆造 API 或参数。

这套约定的核心是「不确定就提问」。很多 AI 生成代码翻车，是因为它凭印象编了一个不存在的函数签名，明确禁止臆造能挡掉一大类低级错误。这也是把代码规范固化成文件的最佳切入点。

模板二：Python 后端服务

Python 项目最忌讳风格不统一和依赖混乱，文件里要把这两点写死。

# Python 后端约定
- 运行环境：Python 3.11+，依赖全部写进 requirements.txt 并锁版本。
- 目录：按分层组织（api / service / model / schema），禁止循环导入。
- 数据库操作必须经过 ORM，禁止在代码里拼接原生 SQL 字符串。
- 接口返回统一用 JSON，错误码走 schema 校验。
- 单元测试覆盖率不低于 70%，用 pytest 跑。

这里特意强调「禁止拼接原生 SQL」，因为模型很容易为了省事直接写字符串 SQL，埋下注入隐患。如果你要补 SQL 基础，可以参考 Python3 教程 里的数据库章节。约定越具体，模型越不容易跑偏。

模板三：前端组件规范

前端项目常因组件职责不清导致维护灾难，文件要约束组件边界和样式方案。

# 前端组件约定
- 框架：React + TypeScript，组件用函数式写法。
- 样式：优先 CSS Modules，禁止全局 class 污染。
- 状态：跨组件状态用 Context 或状态库，组件内用 useState。
- 每个组件只做一件事，props 必须有类型定义。
- 列表渲染必须写稳定的 key，禁止用 index 当 key。

「禁止用 index 当 key」是高频坑，模型默认爱用 index，写进文件能从源头避免重渲染错乱。想补 JavaScript 基础可以看 JavaScript 教程，把原型链和闭包搞清，写组件才稳。

模板四：SQL 与数据库

涉及数据库的改动风险最高，文件要明确迁移和查询规范。

# 数据库约定
- 所有表变更走迁移脚本，禁止手工改库。
- 查询必须走索引，禁止 SELECT *。
- 联表查询先 EXPLAIN，确认命中索引再上线。
- 批量写入用事务，失败要能整体回滚。

这一节和测试、回滚强相关。数据库改动一旦出错，影响面是全局的，所以把「先 EXPLAIN 再上线」写死，等于给 AI 加了一道前置检查。多人协作时这些约定也要进版本管理，Git 教程 讲的分支与提交规范值得照着用。

除了提交规范，规则文件本身也该纳入「会演进」的意识里：它和代码一样会随着项目成长而过时。当团队引入新框架、换了包管理工具，或者刚踩到一个新坑，第一时间把经验补进对应模板，比事后单独写文档省力得多。很多团队的规则文件越用越旧，根源就是没人负责维护，建议指定一位同事定期回看，把它当成一份活的约定，而不是一次性的静态配置。文件一旦开始过期，AI 照着旧规范生成的代码反而会成为新的返工源，所以维护节奏比写得多更重要。

模板五：测试与提交

最后一段管住「交付质量」，让 AI 生成的代码默认是可验证的。

# 测试与提交约定
- 新增功能必须带单元测试，覆盖正常路径与边界路径。
- 提交信息用约定式格式：type(scope): 简述。
- 不提交 secrets、不提交大文件。
- CI 失败先本地复现再改，禁止靠重试蒙过去。

把测试要求写进文件，AI 在写实现的同时就会顺手补用例，而不是写完功能就结束。质量意识这块，软件测试教程 里黑盒白盒的划分能帮你判断用例够不够。

三、常见坑与排查

文件也不是写完就高枕无忧，有几个坑要留意。第一，文件过长会被截断，Cursor 对注入长度有上限，建议控制在 60 行以内，把最关键的几条放最前面。第二，约定冲突，比如既要求「简洁」又要求「详细注释」，模型会无所适从，每条最好能自洽。第三，文件过期，技术栈升级后老约定可能失效，定期回看很有必要。

如果生成的代码还是经常跑偏，先别怪模型，打开文件看看是不是约束太虚。能用一句话明确的事，就别写成「尽量」「酌情」这种模糊词。环境层面，本地运行问题多半和权限、进程有关，对照 Linux 基础把常见命令理清，排查会快很多。

还有一点容易被忽略：规则文件不是越长越好。有人恨不得把每条 lint 规则、每个命名细节都写进去，结果文件长到没人愿意看，模型加载时也更容易被截断。好的做法是只写「人会忘、AI 会乱来」的那几条硬约束，其余交给工具链和编辑器配置。判断标准很简单：这条约定如果不写进文件，AI 是不是大概率会犯同一个错？是才写，不是就删。保持文件精简，模型遵守率高、加载也快，实际效果反而比堆字数更好。规则文件的核心竞争力从来不是篇幅，而是把最关键的那几根线牵住。

小结

这类文件的价值不在「多」，而在「准」——它把团队代码规范变成可执行的默认约束。五个模板覆盖了从骨架到提交的主要场景，你直接抄改即可，不必全用。真正省力的是把那些「说一遍就忘」的约定固化下来，让 AI 默认走在正确轨道上。把它当成项目的第一份文档来维护，长期来看比反复口头叮嘱划算得多。

延伸学习

• 想系统提升 AI 协作开发能力，可以看 AI驱动的Python编程实战 这门课程。
• 2026 年 AI 编程助手怎么选？Qoder、OpenClaw 与 DeepSeek 横向对比测评 帮你横向了解主流工具的差异。
• 想深入 AI 编程实战，可以参考 AI 人工智能教程。

常见问题

Q：规则文件应该提交到仓库吗

应该。它本质是团队约定，放仓库里所有人共享，新人拉下来就能用同一套基线，也方便 Code Review 时统一标准。

Q：.cursorrules 和 .cursor/rules 哪个更好

小项目用单个 .cursorrules 足够；项目大了建议拆成 .cursor/rules/ 下的多个文件，按模块加载，避免一份巨长文件难以维护。

Q：AI 还是不听规则怎么办

先确认规则确实被加载（对话开头能看到注入内容），再看是不是规则本身矛盾或太虚。把模糊表述改成可执行的具体约束，通常就能解决。