【Cursor 工程rules实际感悟】

Cursor 工程规则分享：.cursor/rules全览与实践感悟

适用读者：使用 Cursor / Copilot 类工具做真实业务研发、希望用「可重复的规则」约束 AI 行为的开发者。
说明：下文规则正文来自本仓库.cursor/rules/*.mdc，为便于离线阅读与转载，按文件分节并以代码块收录；若仓库内规则有更新，请以仓库为准。

写在前面

.mdc规则把流程（SDD）、交互方式、前后端约定、安全、测试、Git固化到上下文里，减少模型「自由发挥」带来的返工。下面先按加载优先级与职责做一句话导读，再给出各文件完整原文（代码块内），最后是我对这套规则体系的使用感悟。

文件一览与导读

00-global.mdc（全局开发规范）

--- description: 全局开发规范 alwaysApply: true --- # 全局开发规范 ## 核心原则 1. **Spec 先行**: 任何代码生成前必须确认有对应的 Spec 文档 2. **可验证**: 所有功能必须有对应的验收测试 3. **可追踪**: 代码必须标注对应的 Spec ID 4. **不可绕过**: 禁止生成无 Spec 依据的代码 5. **文档同步**: 结构性变更必须同步更新 `CLAUDE.md` ## 标准化四阶段流程：Specify -> Plan -> Tasks -> Implement 本项目为已投产生产系统，采用渐进式保守策略引入 SDD。存量代码保持现状，仅在新增或变更功能时必须走完四个阶段。 ### 阶段 1：Specify（规格定义） - 新功能 -> 执行 `/new-spec`，生成 `docs/specs/FR-XXX-描述.md` - 变更功能 -> 执行 `/change-spec`，生成 `docs/change/CHG-YYYY-MMDD-描述.md` - 若被变更功能尚无 Spec -> 先补简化版 Spec（状态标 `Deployed`），再写变更 Spec - 若变更涉及目录结构、入口路径或模块职责调整 -> 在 Spec / Change 中标注“影响 `CLAUDE.md`” - 退出条件：Spec 状态 Approved ### 阶段 2：Plan（方案设计） - 使用 brainstorming skill 探索方案（提出 2-3 种方案 -> 确认设计） - 使用 writing-plans skill 拆解为 bite-sized Task（每个 2-5 分钟） - 保存到 `docs/plans/YYYY-MM-DD-feature.md` - 若存在结构性变更 -> Plan 中必须显式加入“同步更新 `CLAUDE.md`” - 退出条件：Plan 文档已保存并确认 ### 阶段 3：Tasks（任务分解） - 从 Plan 提取所有 Task，创建 TodoWrite 任务清单 - 每个 Task 关联 Spec 中的 AC（验收标准） - 标注文件路径、测试文件路径、依赖关系 - 将 Tasks checklist 追加到 Plan 文档末尾的「## Tasks」章节中持久化保存 - 退出条件：所有 Task 状态为 pending，且 Plan 文档中 Tasks 章节已写入 ### 阶段 4：Implement（实施交付） - **入口前置**：运行 `git status`，若存在未提交变更，按规范提交并 `git push`，确保远程有可回退的安全快照；推送成功后向用户报告，推送失败则停止并告知原因 - 执行方式：subagent-driven-development（同会话）或 executing-plans（新会话） - 每个 Task：TDD 先写测试 -> 编码实现 -> 添加 `@spec` 注释 -> Spec 合规审查 + 代码质量审查 -> 提交 - 完成一个 Task 后，在 Plan 文档中将对应 checklist 项标记为 `[x]` - 若发生结构性变更 -> 代码改动与 `CLAUDE.md` 更新必须同一批次完成 - 结构性变更提交前 -> 运行 `powershell -ExecutionPolicy Bypass -File ".cursor/check-claude-sync.ps1"` - 提交格式：`feat(FR-XXX): 简体中文描述` - 退出条件：所有 Task 完成，Plan 文档中全部标记为 `[x]`，Spec 状态 Implemented -> Verified ## CLAUDE.md 同步治理 ### 结构性变更的判定范围 以下情况必须评估并同步 `CLAUDE.md`： - 新增、删除、重命名一级目录或关键二级目录 - 前端或后端入口路径变化 - 测试目录、接口目录、服务目录职责变化 - 分层关系变化，例如 Service / Repository / Store 职责迁移 - 会影响项目理解或 AI 上下文判断的模块重组 ### Review 固定检查项 - 是否新增、删除或移动了关键目录 - 是否改变了前后端入口路径 - 是否改变了模块职责、测试路径或开发命令 - `CLAUDE.md` 中的目录结构、入口说明、分层描述是否仍然准确 ## 存量代码策略 - **不动存量**：已上线功能不主动回溯补 Spec、注释、测试 - **触碰即纳入**：当存量功能需变更时，先补简化版 Spec（状态 `Deployed`），再按四阶段流程执行 ## 对话规范 - 交互与问题求解规则详见 `conversation-principles.mdc` 当用户请求生成代码时: 1. 首先确认是否有对应 Spec 2. 如无 Spec，引导用户调用 /new-spec 命令生成 3. 按四阶段流程推进（Specify -> Plan -> Tasks -> Implement） 4. 实施完成后输出 Spec 符合性检查清单 当用户请求修改已有功能时: 1. 确认原功能对应的 Spec ID (FR-XXX) 2. 检查是否有对应的变更 Spec 文档 3. 如无，引导用户调用 /change-spec 命令生成 4. 按四阶段流程推进 ## 提交规范 - 功能性 Commit 必须在 scope 中关联 Spec ID: `feat(FR-001): 实现用户登录` - 非功能性 Commit（chore/style/docs）可省略 scope: `chore: 更新依赖版本` - 重大变更需要 Spec 评审记录 - 详细格式参见 07-git-commit 规则 ## 禁止行为 - 禁止生成无测试的代码 - 禁止绕过类型检查 - 禁止提交无 Spec 依据的功能代码 - 禁止跳过四阶段中的任何阶段

01-sdd-spec.mdc（SDD 规格驱动开发规范）

下列原文内含示例代码块，外层使用四个反引号包裹。

--- description: SDD 规格驱动开发规范 alwaysApply: true --- # SDD 规格驱动开发规范 ## Spec 文档要求 ### 必须包含的要素 - [ ] Spec ID (格式: FR-XXX / TECH-XXX / NFR-XXX) - [ ] 版本号和创建日期 - [ ] 功能描述和用户故事 - [ ] 验收标准 (Acceptance Criteria) - [ ] 接口规范 (如适用) - [ ] 数据模型 (如适用) - [ ] 边界情况处理 - [ ] 测试用例映射 - [ ] 新功能须使用需求 Spec 模板（调用 /new-spec 命令生成） - [ ] 需求变更须使用变更 Spec 模板（调用 /change-spec 命令生成） - [ ] 若涉及结构性变更，需标注是否“影响 `CLAUDE.md`” - [ ] 变更历史表格（文档末尾，记录所有关联变更文档） ### Spec 状态管理 | 状态 | 说明 | 对应阶段 | | --- | --- | --- | | Draft | 草稿阶段，待完善 | Specify | | Review | 评审中 | Specify | | Approved | 已批准，可开发 | Specify 退出 / Plan 入口 | | Implemented | 代码已完成 | Implement 完成 | | Verified | 测试已验证 | Implement 验证通过 | | Deployed | 已上线 | 部署后 | ### Spec 文档存放 - 新功能 Spec：`docs/specs/FR-XXX-描述.md` - 技术需求 Spec：`docs/specs/TECH-XXX-描述.md` - 非功能需求 Spec：`docs/specs/NFR-XXX-描述.md` - 变更文档：`docs/change/CHG-YYYY-MMDD-描述.md` - 实施计划：`docs/plans/YYYY-MM-DD-feature.md` ## 四阶段与工具映射 | 阶段 | 工具/命令 | 产出 | | --- | --- | --- | | Specify | `/new-spec`、`/change-spec` | `docs/specs/` 或 `docs/change/` | | Plan | brainstorming -> writing-plans skill | `docs/plans/` | | Tasks | TodoWrite + Plan 文档 | Plan 文档中的 Tasks 章节（持久化 checklist） | | Implement | subagent-driven-development / executing-plans | 代码 + 测试 + Git 提交 | ## 结构性变更补充约束 以下情况属于结构性变更： - 新增、删除、重命名一级目录或关键二级目录 - 前端或后端入口路径变化 - 测试目录、接口目录、服务目录职责变化 - 分层关系变化，例如 Service / Repository / Store 职责迁移 若 Spec / Change 包含上述变化： - Specify 阶段必须在文档中标注“影响 `CLAUDE.md`” - Plan 阶段必须加入“同步更新 `CLAUDE.md`” - Implement / Review 阶段必须校验 `CLAUDE.md` 是否仍与实际结构一致 ## 代码与 Spec 关联 ### 代码注释规范 JavaScript/Vue 示例： ```javascript /** * @spec FR-001 * @implements AC-001, AC-002 * @last_verified 2026-03-18 */ ``` C# 示例： ```csharp /// <summary> /// 获取委托单列表 /// </summary> /// <remarks> /// Spec: FR-001 /// 实现: AC-001, AC-002 /// 最后验证: 2026-03-18 /// </remarks> ``` 变更代码注释： JavaScript/Vue：`@change CHG-YYYY-MMDD-xxx` C#：`Change: CHG-YYYY-MMDD-xxx` ## 测试要求 - 前端测试：Vitest，文件以 `.test.js` 结尾，放在被测文件同目录 - 后端测试：xUnit + Moq，放在 `demo.Orders.Tests` 项目 - 每个 AC 至少一个测试用例 - 新增/变更代码必须带测试，存量代码不强制补测试 ## 变更历史同步 创建或修改变更文档（`docs/change/CHG-*.md`）时，必须同步更新其 `关联 Spec` 所指向的 Spec 文档： ### 操作步骤 1. 在目标 Spec 文档末尾找到 `## 变更历史` 表格 2. 若不存在，在文档最后一个章节之后新增： ``` ## 变更历史 | 变更文档 | 日期 | 说明 | | --- | --- | --- | | CHG-YYYY-MMDD-描述 | YYYY-MM-DD | 一句话概括变更内容 | ``` 3. 若已存在，在表格末尾追加一行 ### 格式参照 以 FR-001 为例： ``` ## 变更历史 | 变更文档 | 日期 | 说明 | | --- | --- | --- | | CHG-2026-0325-客户提交邮件逻辑变更 | 2026-03-25 | VBD 必填不完整时条件发送邮件 | ``` ### 约束 - 变更文档的 `关联 Spec` 字段必须指向有效的 Spec ID - 变更历史表格必须是 Spec 文档的最后一个章节 - 一个变更文档只关联一个 Spec，但一个 Spec 可有多条变更记录 - 创建变更文档时若忘记更新 Spec 变更历史，视为未完成

02-code-style.mdc（代码风格规范）

--- description: 代码风格规范 alwaysApply: false globs: "**/*.{cs,js,vue}" --- # 代码风格规范 ## 命名规范 | 类型 | 规范 | 示例 | | --------- | ---------- | ----------------------------------- | | 变量/函数 | 驼峰命名 | `getUserInfo`, `isValid` | | 类/组件 | 大驼峰 | `UserService`, `LoginForm` | | 常量 | 大写蛇形 | `MAX_RETRY_COUNT`, `API_BASE_URL` | | 文件（非 Vue 组件） | 小写短横线 | `user-service.js`, `order-api.cs` | | Vue 组件文件 | 大驼峰 | `OrderList.vue`（遵循 06-frontend 规范） | ## 注释规范 - 所有公共方法必须有文档注释 - 复杂逻辑必须有行内注释 - 必须标注关联的 Spec ID ## 函数规范 - 单一职责原则 - 函数长度不超过 50 行 - 参数不超过 5 个 ## 错误处理 - 必须处理所有异常情况 - 使用统一的错误码格式 - 错误信息必须清晰可理解

03-testing.mdc（测试规范）

--- description: 测试规范 alwaysApply: false globs: "**/*.{test.js,Tests.cs}" --- # 测试规范 ## 测试框架 - 前端：Vitest + @vue/test-utils + happy-dom - 后端：xUnit + Moq（项目 `demo.Orders.Tests`） ## 测试文件规范 - 前端测试文件以 `.test.js` 结尾，放在被测文件同目录 - 后端测试文件以 `Tests.cs` 结尾，放在 `demo.Orders.Tests` 项目 - 新增/变更功能必须有对应的测试文件 - 存量代码不强制补测试，鼓励在修改时顺带覆盖 ## 前端测试结构（Vitest） ```javascript import { describe, it, expect } from 'vitest' describe('模块名称', () => { describe('功能点 (AC-001)', () => { it('应该 [预期行为]', () => { // 测试实现 }) }) }) ``` ## 后端测试结构（xUnit） ```csharp /// <summary> /// Spec: FR-XXX | AC-001 /// </summary> public class XxxServiceTests { [Fact] public async Task MethodName_Scenario_ExpectedResult() { // Arrange / Act / Assert } } ``` ## 测试覆盖率要求 | 测试类型 | 覆盖率要求 | 适用范围 | | --- | --- | --- | | 单元测试 | >= 80% | 新增/变更模块 | | 集成测试 | >= 70% | 新增/变更模块 | | Spec 验证测试 | 100% | 每个 AC 至少一个测试 | ## Spec 验证测试 - 每个验收标准 (AC) 必须有对应的测试用例 - 测试用例名称必须包含 AC ID - 测试失败必须明确指出违反的 Spec 条款 ## 运行命令 - 前端：`npm run test`（单次）或 `npm run test:watch`（监听模式） - 后端：`dotnet test demo.Orders.Tests/demo.Orders.Tests.csproj` ## 禁止行为 - 禁止提交无测试的新增/变更代码 - 禁止测试用例无实际断言 - 禁止测试数据硬编码敏感信息

04-security.mdc（安全规范）

--- description: 安全规范 alwaysApply: true --- # 安全规范 ## 输入验证 - 所有用户输入必须验证 - 使用白名单验证而非黑名单 - 禁止直接使用用户输入拼接 SQL/命令 ## 认证授权 - 所有 API 必须验证认证令牌 - 敏感操作必须验证权限 - 令牌必须安全存储（禁止明文） ## 数据安全 - 敏感数据必须加密存储 - 日志中禁止记录敏感信息 - 密码必须使用 bcrypt/argon2 哈希 ## 依赖安全 - 定期更新依赖包 - 禁止使用有已知漏洞的版本 - 生产环境禁止使用 dev 依赖 ## 代码审查检查点 - [ ] SQL 注入防护 - [ ] XSS 防护 - [ ] CSRF 防护 - [ ] 敏感信息泄露检查

05-api.mdc（后端 .NET 8 Web API）

--- description: 后端 .NET 8 Web API 开发规则 alwaysApply: false globs: demo-api/**/*.cs --- ## 架构约定 - 严格遵循分层架构：Controller -> Service -> Repository - Controller 只负责参数校验和调用 Service，禁止包含业务逻辑 - Service 层通过 IServices 中定义的接口注入，禁止直接 new - 使用 SqlSugar ORM 访问数据库，禁止拼接 SQL 字符串 - Oracle 参数化查询使用 `:ParamName` 语法，禁止使用 `@` - 需要符合单一职责原则 ## 命名规范 - 类名：PascalCase（如 OrderService） - 方法名：PascalCase + 异步方法以 Async 结尾（如 GetOrderListAsync） - 接口名：I + PascalCase（如 IOrderService） - 实体属性：Oracle 列名转 PascalCase（FOLDERNO -> FolderNo） - DTO/VO 放在 demo.Orders.Model 对应目录下 ## 返回值约定 - 所有 API 统一返回 ApiResult<T> 包装类 - 异步方法返回 Task<ApiResult<T>> - 异常统一由全局过滤器捕获，禁止在 Controller 中 try-catch ## 实体类约定 - 继承 BaseEntity（含 ORIGREC 主键） - 必须添加 [SugarTable("TABLE_NAME")] 注解 - 必须添加 [SugarColumn] 注解，包含 ColumnName 和 ColumnDescription - CLOB 字段必须设置 ColumnDataType = "CLOB" - 可空字段使用 C# 可空类型（int?, DateTime?）

06-frontend.mdc（前端 Vue 3）

--- description: 前端 Vue 3 开发规则 alwaysApply: false globs: demo-web/src/**/*.{vue,js,ts} --- ## 技术栈 - Vue 3 + Composition API（setup 语法糖） - Element Plus 组件库 - Pinia 状态管理 - Vue Router 路由 - Axios 请求 - GrapeCity SpreadJS 表格组件 ## 组件规范 - 单文件组件使用 <script setup> 语法 - 组件文件名使用 PascalCase（如 OrderList.vue） - Props 必须定义类型和默认值 - Emit 事件必须使用 defineEmits 声明 - 组件拆分原则：单个 vue 文件不超过 300 行 ## 状态管理 - 全局状态使用 Pinia store - 组件内状态使用 ref/reademove - 跨组件通信优先使用 props/emit，其次 Pinia，避免 EventBus ## API 调用 - 所有接口定义在 src/api/ 目录下 - 使用 Axios 实例，统一配置 baseURL、拦截器 - 接口方法命名：动词 + 名词（如 getOrderList, createOrder）

07-git.mdc（Git 提交信息规范）

--- description: Git 提交信息规范 alwaysApply: true --- ## Conventional Commits - feat: 新增功能 - fix: 修复缺陷 - refactor: 代码重构（不改变功能） - docs: 文档变更 - style: 代码格式（不影响逻辑） - perf: 性能优化 - test: 测试相关 - chore: 构建/工具变更 ## 格式 提交信息的描述和正文必须使用简体中文。 - 功能性提交必须在 scope 中关联 Spec ID: `feat(FR-001): 实现用户登录` - 非功能性提交（如 chore、style、docs）可省略 scope: `chore: 更新依赖版本` ## 示例 - `feat(FR-012): 新增委托单导出 PDF 功能` - `fix(FR-003): 修复订单列表分页异常` - `refactor(TECH-005): 重构登录认证流程` - `chore: 升级 Element Plus 至最新版本` ## 前端提交前置检查 当提交涉及 `demo-web/` 目录下的文件时，必须在 `git add` 之前依次执行以下命令（执行目录为 `demo-web/`）： 1. `npm run lint:eslint`（ESLint 检查并自动修复） 2. `npm run lint:prettier`（Prettier 格式化） ### 流程 ```bash cd demo-web && npm run lint:eslint && npm run lint:prettier && cd .. git add . git commit -m "feat(FR-XXX): 描述" ``` ### 规则 - 如果 ESLint 报错且无法自动修复，必须停止提交并告知用户错误信息 - lint 修复后的文件变更必须一并纳入暂存区（所以 lint 在 git add 之前） - 仅当变更文件包含 `demo-web/` 下的 `.js`、`.ts`、`.vue` 文件时才需要执行 - 后端（`demo-api/`）文件变更不需要执行此检查 ## Implement 阶段入口推送 进入 SDD 四阶段流程的 Implement 阶段时，Agent 必须在写入任何文件之前： 1. 运行 `git status` 2. 若有未提交变更 → 按规范 lint + commit + `git push` 3. 向用户报告："已推送现有变更作为安全快照" 4. 推送失败时停止并告知用户 此规则由 SDD 流程自动触发，无需用户干预。 ## 结构性变更附加检查 当提交涉及目录结构、入口路径或模块职责调整时，除原有检查外，还必须在提交前执行： ```powershell powershell -ExecutionPolicy Bypass -File ".cursor/check-claude-sync.ps1" ``` ### 规则 - 若脚本提示 `CLAUDE.md` 可能未同步，必须先处理文档一致性，再继续提交 - 该检查适用于新增、删除、重命名关键目录，以及会影响项目总览的结构调整

conversation-principles.mdc（交互与问题求解规范）

--- description: 第一性原理驱动的交互与问题求解规范 alwaysApply: true --- # 交互与问题求解规范 本规则用于约束回答组织方式与问题求解方式，不替代系统、安全、工具限制与项目工程流程等更高优先级规则。若发生冲突，优先遵守更高优先级规则。 ## 回答结构 - 默认将回答分为两个部分：`直接执行` 与 `深度交互` - `直接执行`：按用户当前要求直接给出结果，优先推动当前任务前进 - `深度交互`：回到原始目标做审慎分析，识别是否存在目标偏移、XY 问题、路径依赖、经验主义或过度设计 ## 目标澄清 - 默认不假设用户已经完整定义目标 - 当目标、成功标准或关键约束存在歧义，且会影响结果正确性时，先澄清再继续 - 澄清时优先追问原始问题，而不是直接围绕用户提出的具体手段展开 - 提问应尽量聚焦，避免一次抛出过多问题 ## 路径优化 - 若用户给出的路径可行，但存在显著更短、更稳或更低成本的替代方案，应主动指出 - 不因“行业常见做法”或“通常都是这样”而直接沿用方案，应回到问题本身判断必要性 - 优先选择满足目标的最小充分解，避免为了形式完整而引入无关复杂度 - 若当前路径虽然不是最优，但改道成本更高，应说明权衡后再建议是否调整 ## 审慎挑战 - 当怀疑用户正在解决表象而非根问题时，应优先检查是否属于 XY 问题 - 应主动说明当前路径的主要代价，例如实现成本、沟通成本、维护成本、回滚成本与错误风险 - 对高风险、大范围影响或存在不可逆后果的任务，应提高审查强度，避免机械执行 - 审慎挑战的目标是提升结果质量，不是替代用户做目标决策 ## 交互力度控制 - 小任务、低风险任务、纯确认类问题：保持轻量，只指出明显更优路径，不展开冗长讨论 - 大任务、高风险任务、需求模糊任务：应进行更严格的目标审视、方案比较与边界确认 - 单个澄清问题、简短状态更新等场景，可以保持极简表达，但仍应遵循本规则的基本方向 - 深度交互不应反客为主，不应为了挑战而挑战，不应显著增加不必要的沟通负担

总结：我在跟进这套规则时的感悟

1. 分层清晰：alwaysApply的全局规则管流程与安全、Git、对话方式；globs规则在进到具体目录时才加重约束，既减少噪音，又能在改前端/后端时自动「对齐团队口径」。
2. SDD 不是 paperwork：00-global与01-sdd-spec把「验收标准、变更历史、代码注释」绑成一条链，AI 也不容易写出「无处挂账」的功能代码。
3. 交互规则容易被低估：conversation-principles解决的是对话漂移与 XY 问题；和纯代码规范相比，它同样影响交付质量。
4. 可复制到其它仓库：把本仓库的.mdc当作模板，替换项目名、路径与栈即可；核心是优先级（安全 / 流程 > 风格）和可验证（测试与 AC）。
5. 维护成本：规则要与真实流程一致，否则模型会「照错误条文办事」；结构或脚本变了，记得同步CLAUDE.md与相关检查（见07-git）。

若你准备在 CSDN 发布，可自行补充：团队规模、是否全员 Cursor、以及落地中最卡的一步（例如 Spec 评审或前端 lint 前置），读者会更愿意留言交流。