TRAE-AI编程
装了 Cursor 之后发现，AI 助手总是自作主张：你项目用 Vue 它给你写 React，你定了缩进规范它偏用四个空格，改来改去风格全乱。解决办法不是每次对话里反复提醒，而是写一份 Cursor 规则文件，让助手在每次对话前就记住项目约定。这份规则文件该写什么？核心是三段：项目背景与技术栈声明、编码规范与目录约定、边界禁令与验证命令。本文给出可直接抄的最小模板，并解释每一段为什么必须写、写漏了会发生什么。
一、先看结论：规则文件该写什么
规则文件的本质是"给 AI 的项目说明书"。一份 Cursor 规则文件写得越具体，助手越少跑偏。三段内容的取舍见下表：
| 段落 | 写什么 | 不写会怎样 |
|---|---|---|
| 项目背景与技术栈 | 框架、语言版本、包管理器 | AI 按通用习惯写，风格与项目冲突 |
| 编码规范与目录约定 | 命名、缩进、文件放哪 | 每次生成位置随机，目录越来越乱 |
| 边界禁令与验证命令 | 不许动哪些文件、怎么验证 | AI 改坏配置或跑错命令 |
优先级上，第一段解决"用什么写"，第二段解决"怎么写"，第三段解决"不许做什么"。新手最常见的误区是把 Cursor 规则文件写成散文（"请帮我好好写代码"），这种表述 AI 无法执行；正确写法是短句加列表，每条只说一件事。写完先检查三条：技术栈版本对不对、路径与实际目录一致、禁令覆盖了最怕被改的文件。官方对各项配置的说明可在 Cursordocs 教程 里对照查阅。
二、准备阶段：找到规则文件的位置
Cursor 支持项目级规则：在项目根目录建 .cursor/rules/ 目录，每条规则一个 .mdc 文件；旧版本则是单个 .cursorrules 文件，两者目前兼容，新项目建议用 rules 目录，方便按主题拆分。先确认你的版本支持哪种：
# 在项目根目录查看是否已有规则文件（Windows 用 dir，macOS/Linux 用 ls）
ls -la .cursor/rules/ 2>/dev/null || ls -la .cursorrules 2>/dev/null
# 没有就创建规则目录
mkdir -p .cursor/rules预期结果是空的规则目录已建好（未在本机执行，按 Cursor 官方文档推断）。位置确认后有个关键细节：规则文件只在项目内生效，换一个项目要重新放一份；如果你的规范是团队级的，把模板放进仓库，让规则文件跟着代码走，新人克隆下来就自动生效。准备阶段的验收标准是：你能说出规则文件放在哪、什么命名、对哪些人生效。接下来逐段填内容。
三、第一段：项目背景与技术栈声明
第一段告诉 AI"这是个什么项目"，它是 Cursor 规则文件里收益最高的一段。至少包含四行：框架与版本、语言版本、包管理器、运行入口。模板可直接抄：
# 项目背景（.cursor/rules/stack.mdc）
- 框架：Vue 3 + Vite，组合式 API（setup 语法糖）
- 语言：TypeScript 5，严格模式开启
- 包管理器：pnpm，不要用 npm 或 yarn 的命令
- 入口：src/main.ts，页面在 src/views，组件在 src/components
这段为什么必须写？因为大模型默认按训练数据里的"最常见的写法"生成代码：你说写个列表页，它很可能默认 React 函数组件加 Tailwind，因为这类样本最多。声明了技术栈，生成的代码才会落在你的框架上。写的时候有两个检查点：版本号必须真实——去 package.json 抄，不要凭印象写；目录路径必须存在——写错路径 AI 会"贴心地"帮你建错目录。项目技术栈变了记得同步更新这一段，否则 Cursor 规则文件反而成了误导源。
四、第二段：编码规范与目录约定
第二段解决"怎么写才像这个项目的人写的"。挑团队真正在乎的五到八条写，不要把整个风格指南抄进来——规则越长，AI 越容易忽略细节：
# 编码规范（.cursor/rules/style.mdc）
- 组件用 <script setup> 写法，不写 export default
- 命名：组件 PascalCase，工具函数 camelCase，常量 UPPER_SNAKE
- 样式统一用 scss，缩进两个空格，禁止内联 style
- 新页面放 src/views/<模块名>/，公共组件放 src/components/
- 请求统一走 src/api/，组件里不许直接写 fetch 或 axios这一段的写法要点是"可判定的短句"。"代码要优雅"这种话 AI 没法执行，"禁止内联 style"它就能严格照做。目录约定尤其值得写：不写的话，AI 每次建文件的位置像抽盲盒，两周后项目结构就不可维护了。写完做一个自查：让 AI 新建一个示例组件，看它放的路径、用的命名是否符合每一条；不符合的那条，说明表述不够明确，改写成更机械的短句再试。规范的验证和配置排错思路，与 TRAE 问题排查 里"改配置后必须实际触发一次"的原则一致。
五、第三段：边界禁令与验证命令
第三段是安全带，也是新手最容易漏的一段。它告诉 AI 两件事：不许碰什么、改完怎么验证：
# 边界与验证（.cursor/rules/boundary.mdc）
- 禁止修改：pnpm-lock.yaml、.env、docker-compose.yml
- 禁止执行删除、数据库清空、git push 等破坏性命令
- 改完代码必须能通过 pnpm lint 与 pnpm build，再汇报结果
- 不确定的需求先提问确认，不要自行扩写功能遇到问题时，按下面的清单排查规则文件本身：
| 现象 | 常见原因 | 修复方向 |
|---|---|---|
| 规则写了但 AI 不遵守 | 规则太长或表述模糊 | 精简到短句列表，一条一件事 |
| 换台电脑规则失效 | 规则文件没进版本库 | 把 .cursor/rules 提交到仓库 |
| AI 仍然用错包管理器 | 写了规范但没写禁令 | 补"不要用 npm/yarn"类禁令句 |
| AI 改坏了锁文件或配置 | 禁令没覆盖该文件 | 把关键文件加进"禁止修改"清单 |
| 新对话又忘了规则 | 规则文件放错位置 | 确认在项目根 .cursor/rules/ 下 |
这一段里"改完必须能通过某条命令"是点睛之笔：它把验证责任交给了 AI，每次改动都有回归标准，而不是靠你肉眼 diff。禁令清单要随项目演进，每次被 AI 坑一次，就往禁令里加一条，这份文件会越来越贴合你的项目。
总结
Cursor 规则文件的三段式：项目背景与技术栈声明让 AI 知道"用什么写"，编码规范与目录约定解决"怎么写"，边界禁令与验证命令保证"不许做什么、怎么算通过"。写法上记住三个原则：短句可判定、版本与路径必须真实、文件随仓库走。写完用"让 AI 新建一个示例"来验收，不合规的条款改到更机械为止。配置一次，之后的每次对话都在规则约束下进行，助手跑偏的次数会断崖式下降，这正是规则文件的价值所在。
延伸学习
常见问题
Q：.cursorrules 和 .cursor/rules/ 目录到底用哪个？
A：新项目直接用 .cursor/rules/ 目录。它是 Cursor 现在主推的方式，每条规则一个 .mdc 文件，可以按主题拆分（技术栈、规范、禁令各一个），也方便团队合并代码时少冲突。旧的 .cursorrules 单文件方式仍然兼容，老项目不必急着迁移；但如果你已经要在多个文件里写很长的规则，拆分到目录会更可维护。两者都存在时以官方文档说明的优先级为准，避免同一约定写两份导致互相矛盾。
Q：规则文件写多少条合适？会不会太长 AI 就不看了？
A：经验上是十到十五条短句以内效果最好。规则文件的约束力来自"具体"而不是"多"：三条可判定的禁令，胜过三十条"请注意代码质量"式的散文。如果规范确实庞大，按主题拆成多个 .mdc 文件，让每条规则保持独立、简短、可判定。判断标准是抽查：随机指一段 AI 最近生成的代码，对照规则逐条核对，命中率高说明长度合适；开始出现明显忽略某条的情况，就精简或拆分。
Q：团队多人用 Cursor，规则文件怎么共享？
A：把 .cursor/rules/ 目录提交进 Git 仓库，跟代码一起走。这是最省事的共享方式：新人克隆仓库后规则自动生效，改规则走正常的代码评审，团队对"AI 该怎么写"达成的是可版本管理的共识。注意两点：一是规则里不要写密钥等敏感信息，它跟代码一样对全仓库可见；二是规则变更要有提交说明，三个月后你才知道某条禁令是为什么加的。
Q：除了 Cursor，其他 AI 编辑器能复用这份模板吗？
A：三段式结构本身通用——项目背景、编码规范、边界禁令这个框架，在各类 AI 编程助手的规则或配置机制里都适用，个别工具的文件名和格式不同，迁移时按各自官方文档调整放置位置即可。真正需要重写的是验证命令一段：不同项目的 lint、构建命令不同，迁移时替换成目标项目的真实命令。先在 Cursor 里把模板打磨成熟，再迁移到其他工具，成本最低。
