第六章 给 Cursor 配置规则与记忆

一、为什么你需要"规则"

你有没有过这种体验？

• 每次 AI 写代码都喜欢加中文注释，你不喜欢，每次都要说"不要加注释"。
• 你的项目用 TypeScript 严格模式，AI 写出来的总有 any，每次都要纠正。
• 你希望 AI 永远先列方案再动手，每次都要在开头加"先列方案"。
• 你希望 AI 用你公司的代码规范（比如某种命名习惯），每次都要复制粘贴一段说明。

这些"每次都要重复说的偏好"，就是"规则"该解决的问题。

把它们一次性写成规则文件，从此Cursor 在每次对话都自动遵守，你只关心"这次任务的特殊要求"。

这就是 Cursor 的 Rules 系统。

二、Rules 系统的全貌

Cursor 的"AI 记忆"分 4 个层级，按优先级从高到低：

注意：旧版 Cursor 用过 .cursorrules 单文件，已经废弃。新版统一用 .cursor/rules/*.mdc 目录结构。

下面我们一个一个讲清楚。

三、Project Rules：你这个项目的"宪法"

3.1 怎么创建

方式 1（推荐 - 在 Cursor 内创建）：

1. 在 Cursor 里按 Cmd+Shift+P。
2. 输入 New Cursor Rule，回车。
3. 给规则起名（比如 typescript-strict），回车。
4. Cursor 会自动在 .cursor/rules/ 目录下创建一个 .mdc 文件，并打开。

方式 2（手动创建）：

直接在项目根目录新建文件夹 .cursor/rules/，里面放 .mdc 文件。

3.2 .mdc 文件的结构

.mdc = "Markdown Cursor"。它是一个普通 markdown 文件，但开头有一段"frontmatter"（YAML 元信息）：

---
description: TypeScript 严格模式规范
globs:
  - "**/*.ts"
  - "**/*.tsx"
alwaysApply: false
---

# TypeScript 严格模式

- 所有类型必须显式声明，不允许 `any`。
- 函数参数和返回值必须有类型。
- 使用 interface 定义对象，不用 type 别名（除非是联合类型）。
- 命名约定：组件 PascalCase、函数 camelCase、常量 SCREAMING_SNAKE_CASE。

frontmatter 三个字段：

正文：用 markdown 写。AI 把这部分当作"系统提示词"的一部分。

3.3 三种触发方式

方式 1：自动按文件类型触发

globs:
  - "**/*.ts"
alwaysApply: false

当用户讨论的文件命中 glob 时，Cursor 自动把这条规则塞进上下文。

方式 2：每次都强制带

alwaysApply: true

每次对话都带，不管讨论什么文件。 慎用——会消耗每次对话的 token。只用于"整个项目通用的最高约定"。

方式 3：手动 @ 引用

description: 部署到 Vercel 的检查清单
alwaysApply: false

没有 globs，alwaysApply 也是 false。这种规则只在你主动 @ 它时才生效。

@Cursor Rules vercel-deploy 帮我检查一下能不能上线

适合"偶尔需要"的规则。

四、6 个开箱即用的 Project Rules 模板

下面 6 个模板，复制到你项目的 .cursor/rules/ 目录，立刻可用。

模板 1：中文表达

.cursor/rules/chinese-output.mdc

---
description: 中文输出与中英文排版规范
alwaysApply: true
---

# 中文输出规范

- 所有解释、注释、提交信息默认用简体中文。
- 代码标识符（变量、函数、类名）保持英文。
- 中英文之间留一个空格："使用 React 框架"。
- 中文与数字之间留一个空格："共 3 个文件"。
- 标点用中文标点（，。；："），但代码块内保留英文标点。
- 不使用 emoji（除非用户明确要求）。
- 不要用"亲"、"小可爱"等过度热情的称呼。

模板 2：禁止新依赖

.cursor/rules/no-new-deps.mdc

---
description: 不要新增依赖
alwaysApply: true
---

# 依赖管理规范

- 默认情况下，禁止新增任何 npm / pip / cargo / gem 依赖。
- 如果某个功能必须引入新依赖，必须先告诉我并说明：
  1. 为什么必须用这个依赖
  2. 有没有不引入依赖的替代方案
  3. 这个依赖的最近一次更新时间和 GitHub Star 数
- 我同意后再装。
- 安装后必须把版本固定在 package.json 里（去掉 ^）。

模板 3：先 Plan 后 Act

.cursor/rules/plan-first.mdc

---
description: 复杂任务先列方案再动手
alwaysApply: true
---

# 工作流规范

对于改动多个文件、安装新依赖、修改配置文件的任务，
请遵循 Plan → Act 流程：

1. **Plan 阶段**
   - 列出 3-5 步的执行方案
   - 列出会改动 / 创建的文件清单
   - 列出会跑的命令清单
   - 等用户回复"开始"

2. **Act 阶段**
   - 严格按方案执行
   - 一步完成后告诉用户"第 X 步完成，开始第 X+1 步"
   - 出错立即停下，向用户汇报

简单任务（改一个文件、修一个 bug）可以直接 Act，不必走 Plan。

模板 4：测试先行

.cursor/rules/test-first.mdc

---
description: 写新功能时同步写测试
globs:
  - "src/**/*.ts"
  - "src/**/*.tsx"
alwaysApply: false
---

# 测试规范

任何新写的核心函数（不含 UI 组件），必须同步写一个 vitest 测试，要求：

- 测试文件放在 `tests/` 下，结构镜像 `src/`。
- 命名：`xxx.test.ts`。
- 至少覆盖：1 个正常路径 + 1 个边界条件 + 1 个错误路径。
- 写完测试后跑 `npm test`，确保通过。

UI 组件（.tsx）暂不强制写测试。

模板 5：提交信息风格

.cursor/rules/commit-style.mdc

---
description: Git 提交信息规范
alwaysApply: true
---

# Git 提交信息规范

提交信息使用 Conventional Commits 风格：

<type>(<scope>): <description>

<可选正文>

type 枚举：
- feat: 新功能
- fix: 修 bug
- docs: 文档
- style: 格式（不影响功能）
- refactor: 重构
- test: 测试
- chore: 构建 / 工具

示例：
- `feat(auth): 加 Google 登录`
- `fix(timer): 修复计时漂移`
- `chore: 升级 vite 到 6.0`

description 用中文，不超过 60 字。

模板 6：禁止动核心配置

.cursor/rules/protect-config.mdc

---
description: 保护核心配置文件不被随意修改
alwaysApply: true
---

# 受保护文件清单

以下文件 / 目录在没有用户明确同意时，**禁止修改**：

- `package.json` 中的 `dependencies` / `devDependencies`
- `tsconfig.json`
- `vite.config.ts`
- `next.config.js`
- `.env`、`.env.local`、`.env.production`
- `prisma/schema.prisma`
- `migrations/` 目录下任何文件
- 任何 `.github/` 下的 workflow 文件

如需改动，请先告诉用户原因和影响，得到明确同意再改。

把这 6 个文件放进 .cursor/rules/，下次让 AI 做事，它的"标准动作"就和你的偏好对齐了。

五、规则的常见误区

误区 1：写得太长

规则 > 1000 字时，AI 自己都"看花眼"。 对策：每条规则只解决一件事。多事拆多个文件。

误区 2：alwaysApply 全开

每条都 alwaysApply: true，结果每次对话都塞 5000 字规则。 对策：只 1-3 条最关键的开 always。其他用 globs 触发。

误区 3：规则之间冲突

A 规则说"用 styled-components"，B 规则说"用 TailwindCSS"。 AI 看到冲突会"瞎猜"。 对策：定期梳理规则，去掉过时的。

误区 4：规则写得"模糊"

"代码要清晰"——什么叫清晰？ 对策：写"必须 / 禁止 / 必须用 / 禁止用 / 命名按 X / 风格按 Y"，绝对量化。

误区 5：规则不更新

项目从 React 18 升到 19，规则里还写 React 18 的 API。 对策：每次重大依赖升级后，过一遍规则。

六、AGENTS.md：写给 AI 看的"项目说明书"

6.1 这是什么

AGENTS.md 是放在项目根目录（或任意子目录）的一个 markdown 文件，专门写给 AI 看。它和 .cursor/rules/ 互补：

• .cursor/rules/ 写"约定 / 规范 / 必须做的事"。
• AGENTS.md 写"项目背景 / 文件结构 / 关键决策"。

6.2 一个标准 AGENTS.md 模板

# 项目说明（写给 AI 同事看）

## 这个项目是干什么的

这是一个个人订阅管理工具。用户可以记录所有的订阅服务（Netflix、Spotify 等），
追踪续费日期，避免漏续 / 续了不用。

## 技术栈

- 前端：React 19 + Vite 6 + TypeScript
- 样式：TailwindCSS 4
- 状态：Zustand
- 数据持久化：localStorage（无后端）
- 部署：Vercel

## 关键目录

- `src/components/` — UI 组件
- `src/store/` — Zustand store
- `src/lib/` — 工具函数
- `src/types/` — TypeScript 类型定义

## 重要决策

- 不引入后端，全部本地存储。
- 不引入图表库，柱状图自己用 SVG 画。
- 单语言：简体中文 only。
- 无登录系统，单用户使用。

## 我希望 AI 怎么协作

- 改 UI 时优先复用已有组件，不要随便造新的。
- 修 bug 时先复现、再分析、最后改。
- 加新功能前先在本文件追加一段"决策"。
- 所有提交信息用中文 + Conventional Commits。

## 不要做的事

- 不要重构整个项目结构。
- 不要给"轻度优化"建议（小改动靠 PR review）。
- 不要碰 vercel.json 和 .env。

把这个文件放在项目根目录，Cursor 在 Agent 工作时会自动读。

6.3 AGENTS.md 和 README.md 的区别

• README.md 写给人看：怎么安装、怎么跑、为什么做。
• AGENTS.md 写给 AI 看：怎么协作、不要做什么、关键决策。

两个文件可以并存。

6.4 多个 AGENTS.md

你可以在子目录也放 AGENTS.md，规则会"继承 + 覆盖"：

项目根/
├── AGENTS.md             ← 项目级
├── src/
│   └── auth/
│       └── AGENTS.md     ← auth 模块级
└── tests/
    └── AGENTS.md         ← 测试模块级

AI 改 src/auth/login.ts 时会同时看到根目录和 src/auth/ 两份 AGENTS.md。

七、User Rules：跨所有项目的"个人偏好"

7.1 这是什么

跟 Project Rules 不同，User Rules 是绑在你"账号 + 这台电脑"的，所有项目都生效。

适合写：

• 你的语气偏好（"用大白话回答"）。
• 你的语言偏好（"始终用简体中文"）。
• 你常用的工具（"git commit 用 Conventional Commits"）。

7.2 怎么设置

1. 按 Cmd+, 打开 Cursor 设置。
2. 找到「Rules」一节。
3. 在「User Rules」里填你的全局规则。

7.3 一份"普通人通用"的 User Rules 模板

# 我的全局偏好

## 输出语言
- 默认用简体中文回答。
- 代码注释默认用中文（除非项目规范要求英文）。
- 中英文之间留一个空格。

## 沟通风格
- 用大白话，少术语。
- 不要长篇大论，先给结论再给理由。
- 不要堆 emoji。
- 称呼用"你 / 我"，不用"亲 / 小可爱"。

## 工作方式
- 改超过 3 个文件的任务，必须先列方案，等我说"开始"。
- 装新依赖前必须告诉我。
- 删文件前必须告诉我。
- 改 .env 前必须告诉我。

## 代码偏好
- 命名：函数 camelCase / 组件 PascalCase / 常量 SCREAMING_SNAKE_CASE。
- 缩进：2 空格。
- 行长：100。
- 不写"自我解释"的注释（如 `// 加 1` 上面写 `i = i + 1`）。
- 注释只解释 "为什么"，不解释 "做什么"。

把这段贴进 User Rules，所有项目自动生效。

八、Notepads：你的"长期素材库"

8.1 这是什么

Notepads 是 Cursor 自带的"小笔记本"——一些长期会用的提示词模板、设计规范、参考链接，存在 .cursor/notepads/ 下，需要时 @ 引用进对话。

8.2 怎么创建

1. Cmd+Shift+P → New Notepad。
2. 输入名字，比如 ui-checklist。
3. 在打开的文件里写内容。

8.3 一个例子：UI 检查清单

.cursor/notepads/ui-checklist.md

# UI 上线前 10 项检查

1. 视觉
   - [ ] 字体大小合理（最小 14px）
   - [ ] 行高 1.5-1.7
   - [ ] 颜色对比度符合 AA（4.5:1）
   - [ ] 主色和品牌一致

2. 交互
   - [ ] 所有按钮 hover 有反馈
   - [ ] 表单字段有 focus 状态
   - [ ] loading / 空 / 错误状态都设计了
   - [ ] 表单验证清晰

3. 响应式
   - [ ] 320px 宽不破版
   - [ ] 平板（768px）布局合理

4. 无障碍
   - [ ] 所有 input 有 label
   - [ ] 所有图片有 alt
   - [ ] 色彩之外有形状 / 文字辅助
   - [ ] 键盘可全程操作

5. 性能
   - [ ] 首屏 < 2 秒
   - [ ] 没有明显的布局抖动

8.4 怎么使用

在 Composer 输入：

@Notepad ui-checklist 帮我用这个清单检查 @File LoginPage.tsx

AI 会读这个 notepad，用清单逐项检查你的登录页。

8.5 哪些素材适合放 Notepad

• 上线前检查清单。
• 写 README 的标准模板。
• 命名规范、品牌色卡、字体规范。
• "我经常想说的一段话"提示词。
• 项目的术语表（让 AI 用对术语）。

九、规则 / AGENTS.md / Notepads 的优先级

当一个对话同时触发多种"记忆"时，Cursor 怎么处理？

优先级（由高到低）
─────────────────
1. 当前对话最新一条 user 消息（你刚说的话）
2. @ 引用的文件 / Notepad / Past Chats
3. Project Rules（alwaysApply: true 的规则）
4. AGENTS.md（项目根 + 当前目录的）
5. Project Rules（globs 命中的）
6. User Rules
7. 项目索引检索到的相关代码

意思是：

• 你"当下说的话"权重最高。
• 主动 @ 的内容次之。
• "全局规则"是基线。

如果"上下文很冲突"——比如规则说"全英文"，你这次说"用中文"——AI 会听你这次的。这就是"对话优先"原则。

十、规则配置的 5 个最佳实践

实践 1：先放最关键的"3 条"

不要一上来写 20 条。先写 3 条最核心的（比如"中文输出 / 不装新依赖 / 先 plan 后 act"），跑一周，再加。

实践 2：用 git 管理 .cursor/rules

把 .cursor/rules/ 提交到 git，团队共享。这样新同事 clone 项目，AI 就自动按团队规范工作。

实践 3：建立"个人模板仓库"

把你最爱的几套规则文件存到 GitHub 一个公开仓库，每个新项目 git clone 一下复制 .cursor/rules/。 我自己有这样一个 cursor-rules-starter 仓库，每个新项目省 5 分钟。

实践 4：定期"清规则"

每月底翻一次 .cursor/rules/，去掉过时的、合并重复的。规则越精简越有效。

实践 5："失败案例"也写进规则

AI 第 N 次犯同一个错（比如"它老是装 axios，但你坚持用 fetch"），就写进规则。规则是 AI 错误的疫苗。

十一、综合演练：给番茄钟项目配规则

回到 第四章 做的番茄钟项目。我们给它配一套规则：

步骤 1：创建目录

在 pomodoro-timer/ 目录下：

mkdir -p .cursor/rules

步骤 2：写 3 条核心规则

.cursor/rules/general.mdc：

---
description: 番茄钟项目通用规则
alwaysApply: true
---

# 番茄钟项目通用规则

## 技术约束
- 纯前端（HTML + CSS + JS 三个文件），不引入框架 / npm 依赖。
- 数据用 localStorage，不引入数据库。
- 中文界面。
- 风格参考 Linear 的极简感。

## 我希望 AI 这样工作
- 改之前先告诉我打算改什么。
- 不要碰 index.html 之外的"已稳定"文件，除非我明确允许。
- 用中文回复，代码注释也用中文。
- 不要写多余的解释，专注代码。

.cursor/rules/style.mdc：

---
description: 视觉风格规范
globs:
  - "**/*.css"
  - "**/*.html"
alwaysApply: false
---

# 视觉风格

- 主色：番茄红 #e74c3c（工作）/ 薄荷绿 #2ecc71（休息）。
- 文字色：浅色模式 #1a1a1a / 深色模式 #f0f0f0。
- 背景色：浅色 #ffffff / 深色 #0f0f0f。
- 圆角：12px。
- 间距单位：8px、16px、24px。
- 字体：系统默认（不引入 Google Fonts）。
- 动效：200ms ease 转场，不要超过 400ms。

.cursor/rules/no-deps.mdc：

---
description: 禁止新依赖
alwaysApply: true
---

# 不要装依赖

这是一个**纯静态**项目。任何情况下都不要：

- 创建 package.json
- 跑 npm init
- 跑 npm install
- 引入 CDN 库

如果某个功能必须依赖第三方，先停下来告诉我。

步骤 3：写一个 AGENTS.md

AGENTS.md：

# 番茄钟项目说明

## 概览
浏览器番茄钟工具。开始 / 暂停 / 重置 + 自动切换工作 / 休息 + 历史统计 + 深色模式 + PWA。

## 文件结构
- index.html — 页面骨架 + 内联 SVG 图标
- style.css — 全部样式（含深浅色变量）
- app.js — 全部逻辑（计时器 / 存储 / 通知 / 图表）

## 关键决策
- 计时算法：不用 setInterval，用 Date.now() 计算实际经过，每 200ms 重绘。
- 数据格式：localStorage["pomodoro:v1"] = JSON 对象。
- 通知：Notification API + audio 双重提醒。

## 已知限制
- 不支持云同步（设计如此，单设备使用）。
- iOS Safari 后台计时可能不准（PWA 也救不了）。

## 不要做
- 不要把 app.js 拆成模块（保持单文件，方便分享）。
- 不要引入 jQuery 或任何库。

步骤 4：试一试

在 Cursor 里按 Cmd+I，输入：

帮我加一个"白噪音"功能：在工作模式下播放雨声。

观察 Cursor 的回应。它应该会：

• 自动遵守规则：不引入新依赖（用 Web Audio API 合成雨声 or 内联短音频 base64）。
• 用中文回应。
• 风格保持一致。
• 修改 app.js 之前可能会先问"我打算这样改"。

如果它依然装了新依赖或者用英文回答，说明规则没生效——检查 .mdc 文件的 frontmatter 是不是写错了。

本章一图回顾

Cursor 的 4 层"记忆"
═══════════════════════════════════════════════
  Project Rules    →  .cursor/rules/*.mdc      项目内
  AGENTS.md        →  根目录 + 子目录          项目内
  User Rules       →  Cursor 设置              所有项目
  Notepads         →  .cursor/notepads/*.md    手动 @

.mdc frontmatter
─────────────
  description       一句话说清做什么
  globs             命中文件类型
  alwaysApply       是否每次都带

6 个开箱即用规则
─────────────
  ① 中文表达
  ② 禁止新依赖
  ③ 先 plan 后 act
  ④ 测试先行
  ⑤ 提交信息风格
  ⑥ 保护核心配置

5 条最佳实践
─────────────
  先 3 条 → git 管理 → 模板仓库
  定期清理 → 错误也写进规则

下章预告

到这里，你已经掌握了 Cursor 的"基础设施"。从下一章开始，我们进入实战。第七章 生活场景实战 会用 7 个完整案例让你亲手把 Cursor 用到生活的方方面面：整理文件、个人记账、简历网站、爸妈一键工具、旅行规划、健身打卡。