Cursor Rules / Skills 分层设计：让 Agent 像「团队新同事」

2025年底到2026年初，这个领域最大的认知转变，就是从「让AI写一段代码」变成了「让AI完成一个任务」。但任务能不能稳定完成，跟你Prompt写得漂不漂亮关系不大，关键看你有没有给Agent一套可预期的约束体系。

话说回来，很多人把.cursorrules当成万能备忘录，一口气塞500行进去，结果Agent该生成React.FC照样生成，项目里根本不存在的API也敢往外蹦。还有人听说Skills很火，一口气装了十几个，结果Agent不知道该听谁的，反而更乱。

下面分享一套实践了大半年的Rules + Skills 分层设计：它们各自解决什么问题、怎么拆分、怎么配合MCP和Code Review形成闭环，以及一套前端项目可以直接复用的模板。希望能帮你省下一些试错的时间。

---

一、先厘清：Rules、Skills、.cursorrules 不是一回事

很多人把这三样东西混着用，结果配置越写越乱。先拿一张表把边界划清楚：

维度	Rules（.cursor/rules/*.mdc）	Skills（SKILL.md）	.cursorrules（旧方案）
本质	持久约束：什么能写、什么不能写	流程指南：怎么做一件事	单文件全局规则（已过时）
触发	按 globs 自动注入，或 alwaysApply	Agent 根据 description 判断是否启用	每次对话全量注入
粒度	短、硬、可检查	长、流程化、可含脚本	粗、难维护
适合写什么	技术栈版本、命名规范、禁止事项	多步骤工作流、领域知识、检查清单	——建议迁移到 Rules
类比	员工手册里的「红线」	新人培训里的「SOP」	把手册和 SOP 糊在一起

一句话总结：

这和MCP工作流里的分工逻辑完全一致：MCP是眼睛，Rules是操作手册，Skills是培训教材。三样东西各司其职，才能形成闭环。

---

二、Rules 分层设计：按职责拆，别写「万能 Rule」

2.1 为什么要拆文件？

单文件Rule的典型问题很明显：

• Token爆炸：无关规范也被强行注入
• 互相冲突：React规则和Vue规则同时生效，不知道听谁的
• 难以维护：改一条规范要翻500行，谁都不愿意动

我的做法是按职责 + 技术栈拆分，用数字前缀控制加载优先级：

 复制代码.cursor/rules/
├── 00-global.mdc          # 全局：语言、Git、安全红线
├── 10-react.mdc           # React 项目：组件、Hooks 规范
├── 20-api.mdc             # API 层：请求封装、错误处理
├── 30-testing.mdc         # 测试：Vitest、Testing Library
├── 40-mcp.mdc             # MCP 调用边界（可选）
└── 50-review.mdc          # Agent 生成代码的自检红线

2.2 .mdc 文件格式

每个Rule文件由YAML frontmatter + Markdown正文组成，结构非常清晰：

 复制代码---
description: React 组件与 Hooks 编写规范
globs: src/**/*.{tsx,ts}
alwaysApply: false
---# React 规范- 使用函数组件，禁止 class 组件
- 禁止 `React.FC`，Props 用 interface 定义
- 自定义 Hook 以 `use` 开头，放在 `src/hooks/`
- 复杂组件拆分为 Container + Presentational
- 样式使用 CSS Modules，禁止行内 style（动态值除外）

frontmatter 字段	说明
description	规则简介，Agent和你在Rule面板里都能看到
globs	匹配文件时才注入，省Token
alwaysApply: true	每次对话都注入，适合全局红线

2.3 三层 Rules 模型

把Rules按强制程度分为三层，这样层级感就出来了：

层级	名称	示例	违反后果
L1	红线（alwaysApply）	禁止 any、禁止提交密钥、禁止 dangerouslySetInnerHTML	直接拒绝合并
L2	规范（globs 匹配）	API 层必须用 requestClient、组件命名 PascalCase	Review 打回
L3	建议（写在 Skill 里）	优先用 useMemo 缓存 columns	酌情优化

红线放Rules，建议放Skills——这是分层设计的核心原则，也是整个体系能跑起来的关键。

2.4 前端项目 L1 红线模板（可直接复制）

下面是00-global.mdc的完整示例，可以直接拿过去用，稍作调整就行：

 复制代码---
description: 全局编码红线与安全约束
alwaysApply: true
---# 全局红线## 技术栈（不可偏离）
- React 19 + TypeScript 5.8 + Vite 7
- 包管理器：pnpm（禁止使用 npm / yarn 命令）
- 状态管理：TanStack Query（禁止引入 Redux / MobX）## 安全
- 禁止 `dangerouslySetInnerHTML`，除非有 DOMPurify 且 MR 说明原因
- 禁止硬编码 API Key、Token、内网地址
- 日志和上报不得包含 PII（手机号、身份证、token）## Git / 命令
- 禁止 `git push --force`、禁止 `rm -rf`
- 改动后必须跑 `pnpm typecheck && pnpm lint`## Agent 行为
- 大改先用 Plan 模式对齐方案，禁止跳过
- 任务描述必须写清改动范围（文件清单）
- 不得引入项目未使用的新范式（新请求库、新状态库）

---

三、Skills 分层设计：管流程，不管红线

3.1 Rules 和 Skills 怎么分工？

实际场景中，Rules和Skills的分工其实很清晰，看几个例子就能明白：

场景	放 Rules	放 Skills
「禁止用 any」	是	—
「接需求的完整流程：Ask → Plan → Agent → Review」	—	是
「API 层必须用 requestClient」	是	—
「如何根据语雀文档生成 API 类型」	—	是
「MCP 调用时不要拉整个 Figma 文件」	（简短）	（详细步骤）

经验法则：

• 能在Code Review里用 / 检查的 → Rules
• 需要多步推理、需要判断「先做A还是B」的 → Skills

3.2 Skill 文件结构

Skills的存放位置有两个层级：

• 个人级：~/.cursor/skills/ ——跨项目通用
• 项目级：.cursor/skills/ ——跟仓库走，团队共享

 复制代码.cursor/skills/
└── frontend-feature-dev/
    ├── SKILL.md              # 主入口（Agent 读这个）
    ├── prompts/              # 可复用 Prompt 模板
    │   ├── new-page.md
    │   └── fix-bug.md
    └── checklists/
        └── pre-mr.md         # 提交前自检清单

SKILL.md头部格式：

 复制代码---
name: frontend-feature-dev
description: >
  前端功能开发标准流程。用户要开发新页面、新组件、接需求、
  修 Bug 时触发。包含 Ask → Plan → Agent → 验证的完整 SOP。
---

需要注意，description是Agent判断是否启用Skill的唯一依据——把触发场景写清楚，比写长正文重要得多。

3.3 我常用的三个 Skill

Skill A：frontend-feature-dev（日常开发）

核心流程非常简洁：

 复制代码1. Ask 模式梳理上下文（@folder 限定范围）
2. Plan 模式输出方案（文件清单 + 边界情况）
3. 人审 Plan，对齐后切 Agent 执行
4. 跑 pnpm typecheck && pnpm lint
5. 对照 Code Review Checklist 自查

Skill B：api-integration（接口联调）

配合MCP语雀使用，流程很顺：

 复制代码1. 用语雀 MCP 搜索并读取最新接口文档
2. 输出字段摘要，等人确认
3. 对照 @src/api/base.ts 既有模式写类型和请求函数
4. 贴一条真实响应样例到 MR 描述

Skill C：pre-mr-review（提交前自检）

把Code Review的Checklist固化进Skill：

 复制代码1. 读 diff，按 P0/P1/P2 分级输出风险项
2. 重点检查：权限、竞态、边界态、架构一致性
3. 不修改代码，只输出审查报告

3.4 Skill 不是越多越好

Skills的使用中常见几个问题，需要我们注意：

问题	原因	对策
Agent 不触发 Skill	description 太模糊	写清「什么时候用」
多个 Skill 冲突	职责重叠	合并或明确优先级
Skill 太长	把规范都塞进去了	规范挪到 Rules
Skill 从不更新	项目演进后流程变了	每个 Sprint 复盘一次

个人觉得，个人3～5个Skill，项目1～2个Skill，基本上够用了。多了反而乱。

---

四、一套完整的前端工作流：四层协作

把Rules、Skills、MCP、人工审查串起来，一个中等需求的标准路径如下面这个实战示例：

实战 Prompt 示例

Step 1 — Ask 模式：

 复制代码【Ask 模式，不要改代码】@src/features/order
需求：订单列表新增批量导出。请先梳理目录结构、数据流、可复用实现。
如有语雀文档，用 MCP 搜索「订单导出」接口。

Step 2 — Plan 模式：

 复制代码基于刚才的调研，给出实现方案，不要写代码。要求：
- 涉及文件清单
- 权限与边界情况
- 参考 @src/features/report/hooks/useAsyncDownload.ts

Step 3 — Agent 执行：

 复制代码按已对齐的方案执行。范围：只改 src/features/order/ 和 src/api/order.ts
完成后跑 pnpm typecheck && pnpm lint

Step 4 — 自检（触发 pre-mr-review Skill）：

 复制代码【Ask 模式】对照 Code Review Checklist 审查当前分支 diff。
按 P0/P1/P2 分级，不要改代码。

---

五、从 .cursorrules 迁移到分层体系

如果还在用单文件的.cursorrules，建议按以下步骤迁移：

Step 1：审计现有内容

把.cursorrules里的条目分类，看看哪些该往哪走：

类型	迁移目标	示例
禁止事项	00-global.mdc	禁止 any、禁止硬编码密钥
技术栈声明	00-global.mdc	React 19、pnpm、Vite 7
组件规范	10-react.mdc	函数组件、Hooks 命名
API 约定	20-api.mdc	错误处理、类型生成
多步流程	Skill	Ask → Plan → Agent 流程
一次性备忘	删除	某次 Bug 的临时 workaround

Step 2：建立目录

 复制代码mkdir -p .cursor/rules .cursor/skills/frontend-feature-dev

Step 3：拆分并删除旧文件

 复制代码# 确认 Rules 生效后
rm .cursorrules   # 或重命名为 .cursorrules.bak

Step 4：验证

新开一个Agent对话，让它生成一个标准组件，检查下面几项：

• 是否用了项目里的请求封装（而非裸 fetch）
• 是否遵循命名规范
• 是否自动跑了 lint

---

六、踩坑指南

坑 1：Rules 写了但 Agent 不遵守

原因：Rule太长、太模糊、或globs没匹配到当前文件。

对策：

• 单条Rule正文控制在50行以内
• 用「禁止」「必须」等硬语气，少用「建议」「尽量」
• 红线用alwaysApply: true
• 生成后立刻跑pnpm typecheck，用工具链兜底

坑 2：Skills 和 Rules 内容重复

原因：同一条规范两处都写了，Agent不知道听谁的。

对策：规范只在Rules里写一次；Skill里用「遵循.cursor/rules/中的React规范」引用，不重复粘贴。

坑 3：Rules 过多导致 Token 爆炸

原因：5个alwaysApply: true的文件，每次对话注入上千行。

对策：

• 只有L1红线用alwaysApply: true（1～2个文件）
• 其余按globs精准匹配
• 单文件不超过50行；超过就拆

坑 4：团队 Rules 没人维护

原因：Rules随项目演进过时，Agent按旧规范生成代码。

对策：

• Rules纳入Code Review范围（「新范式是否需要更新Rules？」）
• 每次线上Bug复盘：「哪条Rule能拦住？」
• 在README或CONTRIBUTING.md里链接Rules目录

坑 5：只有 Rules 没有 Skills，复杂任务还是翻车

原因：Rules告诉Agent「不要做什么」，但没告诉它「按什么顺序做」。

对策：至少建一个开发流程Skill（Ask → Plan → Agent → 验证），复杂任务强制走流程。

---

七、团队推广：从个人配置到仓库标准

7.1 仓库里应该提交什么

文件	是否提交 Git	说明
.cursor/rules/*.mdc	是	团队共享规范
.cursor/skills/	是	团队共享流程
.cursor/mcp.json	>️ 是	可提交模板，Token 用环境变量
~/.cursor/skills/	否	个人级，不提交

7.2 MR 模板加一条

 复制代码## AI 辅助开发
- [ ] 本次改动是否涉及新范式？如是，是否已更新 `.cursor/rules/`？
- [ ] Agent 生成范围：
- [ ] 已对照 Code Review Checklist 自查

7.3 和 CI 的配合

Rules管不住所有事，CI是最后防线：

 复制代码Rules/Skills（生成时约束）→ 本地 lint/test（提交前）→ CI（合并前）→ 人审（合并时）

之前写过：格式交给CI，逻辑和安全交给人——Rules做的是CI之前的预防层，不是替代品。

---

八、行动清单：今天就可以开始

1. 审计现有.cursorrules或脑中「团队规范」，按L1/L2/L3分类
2. 创建.cursor/rules/00-global.mdc，写入前10条红线
3. 按技术栈拆1～2个globs规则（如10-react.mdc）
4. 创建一个frontend-feature-dev Skill，固化Ask → Plan → Agent流程
5. 验证：新开对话，让Agent生成一个组件，看是否遵守规范
6. 删除或归档旧的.cursorrules
7. 配合MCP：在40-mcp.mdc里写MCP调用边界

---

结语

Cursor的能力越来越强，但可预测性不会自动到来。它需要你主动去构建约束体系。

Rules是Agent的「红线」——告诉它什么绝对不能做；Skills是Agent的「SOP」——告诉它复杂任务按什么顺序做；MCP是Agent的「眼睛」——让它自己去看文档和设计稿。

三者分层协作，你才真正从「Prompt工程师」变成AI工作流架构师——这也是日常训练中「AI编排力」的核心体现。

别追求一次写完美。先写10条红线Rules，再建一个开发流程Skill，在一次次真实需求里迭代——就像带新同事一样：先立规矩，再教流程，最后放手让他干活。

---

系列延伸阅读

• 前端工程师的AI副驾驶：Cursor一整年真实体验与避坑指南
• 用MCP把Figma、语雀、GitLab串成一条前端工作流
• AI生成代码之后，前端Code Review审什么？
• 前端工程师如何转型AI Agent工程师