教程
Cursor Rules 编写指南：让 AI 在仓库里「听话」的实操方法
详解 Cursor Rules 的用途、与 Skills 的分工、推荐写法与常见踩坑，帮助团队把项目规范固化到 IDE 层。
为什么需要 Cursor Rules？
Cursor 的 Agent 很强，但默认并不知道你的团队约定：包管理器用 pnpm 还是 npm、组件放哪、能不能改生成文件、提交信息怎么写。Rules 就是把这些全局/项目级约束写进仓库，让每次会话都自带「公司文化」。
它和 Agent Skill 互补：Rules 管底线与风格，Skills 管专项任务流程。
Rules 适合写什么？
适合放进 Rules
- 技术栈与版本基线（Next.js App Router、React 19、Tailwind 等）
- 目录约定与命名（
src/components、禁止在pages/新建） - 安全红线（禁止提交密钥、禁止改生产配置）
- 代码风格偏好（少用某类模式、优先服务端组件）
- 测试与提交要求（改 API 必须补测试）
不适合塞进 Rules
- 某个一次性功能的实现步骤（应写成 Skill）
- 超长产品文档全文（会挤占上下文）
- 频繁变动的临时实验开关说明
推荐结构
一份好用的 Rules 通常按块组织：
1. 项目身份：这是什么产品、主要语言与框架
2. 必须遵守：硬性规则，用「禁止 / 必须」表述
3. 优先做法：鼓励但非绝对的模式
4. 文件边界：哪些目录可改、哪些只读
5. 验证命令：npm run lint、npm run build 等
语气要像规范文档，不要像散文。AI 对祈使句和清单的执行率明显高于「希望你尽量……」。
与 Skills 如何分工
| 内容类型 | 放 Rules | 放 Skill |
|----------|----------|----------|
| 全局编码风格 | 是 | 否 |
| 「创建 API Route」多步流程 | 可引用 | 是 |
| 安全与合规底线 | 是 | 可补充 |
| 某业务领域 SOP | 否 | 是 |
实践建议：Rules 保持 1～3 页可读长度；把可复用任务拆到 SKILL.md，再在 RuleHub 或团队目录中索引。可在 RuleHub 搜索 找同类实践。
落地步骤
1. 从痛点反推
回顾最近两周 AI 生成代码里反复返工的点：错误的包管理器、错误的路由写法、缺少错误处理。每条痛点对应一条 Rule。
2. 写最小集并试跑一周
先写 8～12 条硬规则，让同事用真实任务验证。过长的 Rules 会被模型「选择性忽视」。
3. 用 PR 管理变更
Rules 与代码一样需要评审。增删规则时在 PR 描述说明动机，避免个人偏好悄悄变成团队法律。
4. 定期清理
每季度删掉过时条目（例如已废弃的 Pages Router 约定），保持信噪比。
常见误区
- Rules 越全越好：上下文有成本，重复与冲突会降低遵从度。
- 只写偏好不写禁止：缺少负面约束时，模型仍会走捷径。
- Rules 替代 Code Review：Rules 降低出错率，不能取消人工审查。
- 复制开源 Rules 不改：别人的栈 ≠ 你的栈，必须本地化。
自检清单
- 新人读完能否回答「这个仓库怎么改代码」？
- 是否明确包管理器、测试命令、禁止目录？
- 是否与现有 Lint / CI 规则一致（避免口头说一套、CI 另一套）？
- 是否链接了关键 Skills 或内部文档路径？
小结
Cursor Rules 是把团队工程文化注入 AI 会话的最低成本方式。写短、写硬、写可验证，并与 Skills 分工，你才能在 VibeCoding 速度下仍然保持仓库可控。
下一步：打开当前项目，列出上周 AI 改错的三件事，立刻写成三条 Rules；需要任务型流程时，参考 SKILL.md 格式指南。