Cursor 规则生成

从扫描到生效（skill-flow）

  [ 扫描：根配置、子包、测试与 docs ]
              │
              ▼
       ┌──────────────┐     对齐：ESLint / Prettier / 提交规范
       │  归纳约束与    │──── 引用「以配置文件为准」，避免与工具重复矛盾
       │  反模式清单    │
       └──────────────┘
              │
              ▼
       ┌──────────────┐     拆分：按路径或子项目写规则块；写明 globs
       │  起草规则文件  │──── 与「规则分层」一致：不重复高优先级层已声明的内容
       └──────────────┘
              │
              ▼
       ┌──────────────┐     PR：说明影响范围；评审后合并
       │  评审与合并    │──── 会话中按需 @ 规则或粘贴片段验证
       └──────────────┘
              │
              ▼
         [ Agent / 人按分层取规则 ]

规则分层与完整示例

Cursor 侧常见堆叠为：编辑器用户规则 → 工作区（仓库）级规则 → .cursor/rules 下按文件/目录生效的规则（含 globs 时更窄的范围优先）。上层定「全局原则」，下层写「本目录例外与补充」；冲突时以文档化顺序为准，并在根规则中写明「子规则仅追加，不推翻安全/合规底线」。

  ┌─────────────────────────────────────┐
  │  User rules（个人、跨项目）           │  ← 习惯与可移植偏好
  └─────────────────────────────────────┘
              │ 更具体者补充，不重复啰嗦
              ▼
  ┌─────────────────────────────────────┐
  │  Project / AGENTS.md / 团队基线       │  ← 仓库级语言、流程、禁止项
  └─────────────────────────────────────┘
              │
              ▼
  ┌─────────────────────────────────────┐
  │  .cursor/rules（含 globs 时按路径收窄） │  ← 子包栈、测试策略、目录专属约定
  └─────────────────────────────────────┘
              │
              ▼
         [ 当前文件上下文 + 会话说明 ]

.cursor/rules 目录结构与三种触发类型：

# .cursor/rules/ 目录结构示例
.cursor/
  rules/
    project.mdc          # always — 项目级基线，每次会话都生效
    typescript.mdc       # auto_attached — *.ts / *.tsx 文件自动附加
    react-components.mdc # auto_attached — src/components/**
    testing.mdc          # auto_attached — **/*.test.ts, **/*.spec.ts
    security-review.mdc  # agent_requested — 手动 @security-review 时才附加

# 三种触发类型说明
# always        — 每次 Agent 会话都附加，用于全局原则和禁止项
# auto_attached — 匹配 globs 时自动附加，用于特定文件/目录的约定
# agent_requested — 仅在 Agent 需要或用户 @ 时才附加，用于专项检查

# typescript.mdc 完整示例
---
description: TypeScript 项目代码约定
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

# TypeScript 约定

## 技术栈
- TypeScript 5.x，strict 模式开启
- 包管理：pnpm，运行时：Node.js 20 LTS
- 测试：Vitest + Testing Library

## 代码风格
- 使用 `const` 优先于 `let`，禁止 `var`
- 函数返回类型必须显式声明（除非推断明显）
- 接口用 `interface`，类型别名用 `type`（组合/联合类型）
- 异步函数返回 `Promise`，禁止返回裸 `any`

## 禁止项
- 禁止 `@ts-ignore`（改用 `@ts-expect-error` 并附注释）
- 禁止 `as any`（先尝试类型收窄或泛型约束）
- 禁止直接访问 `process.env`（通过 config 模块封装）

## 测试
- 每个 service/util 文件必须有对应的 .test.ts
- mock 外部依赖，不发真实网络请求
- 测试描述使用中文，说明业务场景

• 多包仓库：根规则写「覆盖顺序与冲突处理」，子目录规则只写该树差异。
• 与 ESLint / Prettier 并存时写「机器检查以配置为准；规则里只写 AI 行为与审查重点」。

高质量规则要素与更多模板

• 输出应包含：目录模式、适用技术栈、禁止的反模式、与 Code Review 的交叉引用。
• 变更策略：重大规则调整走 PR，并在描述中说明对现有会话的影响。
• 具体：列出具体规则，避免「遵守最佳实践」之类的空泛描述。
• 可执行：规则可被 AI 直接遵守，有明确的「做 / 不做」。
• 有示例：对非显而易见的规则附上 ✅ 和 ❌ 代码片段。

React 项目与 Python 项目规则模板示例：

# react-components.mdc — React 组件约定
---
description: React 组件开发约定
globs: ["src/components/**/*.tsx", "src/pages/**/*.tsx"]
alwaysApply: false
---

# React 组件约定

## 组件结构
- 使用函数组件 + hooks，禁止 class component
- Props 接口命名：`${ComponentName}Props`
- 组件文件导出：named export（禁止 default export 组件）

## 状态管理
- 本地状态用 useState / useReducer
- 跨组件共享状态用 Zustand（禁止直接用 Context 传递频繁更新的状态）
- 服务端状态用 TanStack Query（禁止在 useEffect 里手写 fetch）

## 禁止项
- 禁止在渲染函数里定义事件处理函数（性能）
- 禁止在 JSX 里写内联样式（使用 CSS modules 或 Tailwind）

✅ 正确:
const handleClick = useCallback(() => { ... }, [deps]);

❌ 错误:
<button onClick={() => { ... }}>

# python-api.mdc — Python API 约定
---
description: Python FastAPI 项目约定
globs: ["**/*.py"]
alwaysApply: false
---

# Python 项目约定

## 技术栈
- Python 3.12+，FastAPI，SQLAlchemy 2.x，Pydantic v2
- 测试：pytest + httpx（async 测试用 pytest-asyncio）

## 代码风格
- 类型注解必须完整（参数和返回值）
- 使用 Pydantic 模型做输入校验，禁止手动 if/else 校验
- 数据库操作通过 Repository 模式封装，禁止在 router 里直接用 db.query

## 禁止项
- 禁止 `except Exception: pass`（必须记录日志或重新抛出）
- 禁止在 Pydantic 模型里用 `Optional[X]`（改用 `X | None`）

多包仓库与变更策略

多包仓库建议按子项目拆分规则文件，并在根规则中写明覆盖顺序与冲突解决方式。若团队已有 ESLint / Prettier 配置，规则里应引用「以配置文件为准」，避免与工具重复且互相矛盾。

SKILL 引导片段

---
name: cursor-rules-bootstrap
description: 根据仓库结构生成 .cursor/rules 草案
---
# 扫描步骤
1. 读取仓库根：package.json / pyproject.toml / go.mod 判断技术栈
2. 查看 tsconfig.json / .eslintrc / Makefile 归纳现有约束
3. 列出 src/ 目录结构，识别 components / services / api 等层次

# 规则文件生成原则
- project.mdc：always，包含技术栈版本、禁止项、提交规范
- {stack}.mdc：auto_attached，按文件 globs 触发
- 每个规则块：具体可执行 + 有 ✅/❌ 示例
- 机器检查以配置文件为准（ESLint/Prettier），规则只写 AI 行为

# 三种 alwaysApply 类型
- alwaysApply: true   → 每次会话（全局原则）
- alwaysApply: false + globs → 匹配文件时自动附加
- agent_requested     → 按需 @ 附加（专项检查）

# 高质量规则要素
- 具体：列出具体禁止/推荐项，不写「遵守最佳实践」
- 可执行：Agent 可直接遵守，有明确 do/don't
- 有示例：非显而易见的规则附代码片段

# 多包仓库策略
- 根 project.mdc 写全局底线（安全/合规不可推翻）
- 子包 rules/*.mdc 只写该子树差异
- 与 ESLint/Prettier 不重复，引用「以配置为准」