# Vibe Cursor Pro

**企业级 Cursor Vibe Coding 模板 v4.0**

将 Cursor AI 从"代码补全工具"升级为"受约束、可观测、自适应、安全可控"的全栈工程协作者。

适用技术栈：Vue 3 + Vite / PHP Hyperf + Swoole / TypeScript (ES2022+)

---

## 目录

- [为什么需要这个模板](#为什么需要这个模板)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [日常使用指南](#日常使用指南)
- [Rules 规则系统](#rules-规则系统)
- [Skills 技能系统](#skills-技能系统)
- [Subagents 任务委托](#subagents-任务委托)
- [MCP 服务配置](#mcp-服务配置)
- [文档知识库](#文档知识库)
- [自动化脚本](#自动化脚本)
- [项目结构](#项目结构)
- [定制化指南](#定制化指南)
- [常见问题](#常见问题)
- [版本历史](#版本历史)

---

## 为什么需要这个模板

| 维度 | 传统开发 | Vibe Cursor Pro |
|------|----------|-----------------|
| **质量** | 人工 Review | AI Guard 自动质检 + 分层 Rules 约束 |
| **准确性** | 靠记忆 / Wiki | 智能上下文自动加载 + MCP 实时数据 |
| **规范性** | 文档驱动 | Rules 自动注入 + Hooks 强制检查 |
| **安全性** | PR Review | 分级权限 + 敏感操作拦截 + Secret 扫描 |
| **合规性** | 人工排查 | 许可证白名单/黑名单 + 字体/素材合规检查 |
| **效率** | 全人工 | PRISM 工作流 + 23 个技能 + 一键脚手架 |

**核心设计理念**：

- **Intent-First** — 先理解 Why，再执行 What
- **Slow-to-Fast** — 复杂先规划，简单快速响应
- **Evidence-Based** — 基于文档和数据决策
- **Fail-Safe** — 宁可多问，不破坏现有功能

---

## 环境要求

| 工具 | 最低版本 | 用途 |
|------|---------|------|
| Cursor IDE | 2.4+ | 原生支持 Skills 和 Subagents |
| Node.js | 18+ | 前端构建、commitlint |
| PHP | 8.1+ | 后端运行 |
| Composer | 2.x | PHP 依赖管理 |
| Swoole | 5.0+ | 协程引擎 |
| MySQL | 8.0+ | 数据库 |
| Redis | 7.x | 缓存和队列 |
| Git | 2.30+ | 版本控制 |

---

## 快速开始

### 方式一：Workspace 模式（推荐）

将 `vibe-cursor-pro` 本身作为 Cursor 工作区根目录，前后端业务项目放置为子目录，各自独立管理 Git。AI 可同时感知规则、技能与前后端业务代码，上下文最完整。

**目录结构**

```
vibe-cursor-pro/              <- 用 Cursor 打开这个目录
├── .cursor/                  <- Rules + Skills + MCP（AI 配置）
├── docs/                     <- 项目知识库（填写你的业务文档）
├── scripts/                  <- 自动化工具脚本
├── Case-Database-Backend/    <- Hyperf 后端（gitignored，独立 git 仓库）
├── Case-Database-Frontend-user/   <- Vue 3 用户端（gitignored，独立 git 仓库）
├── Case-Database-Frontend-admin/  <- Vue 3 管理端（gitignored，独立 git 仓库）
└── Case-Database-Frontend-shared/ <- 共享类型/工具（gitignored，可选独立仓库）
```

> **双前端说明**：`Case-Database-Frontend-user/` 面向终端用户（移动优先），`Case-Database-Frontend-admin/` 面向管理人员（桌面优先，Element Plus）。AI 通过 `011-vue.mdc` 中的双前端上下文规则自动感知目标前端并应用不同设计原则。

**初始化步骤**

```bash
# 1. Clone 本模板作为工作区
git clone https://github.com/your-org/vibe-cursor-pro.git my-workspace
cd my-workspace

# 2. 将已有项目放入对应目录（或初始化新项目）
git clone <your-backend-repo> Case-Database-Backend
git clone <your-frontend-user-repo> Case-Database-Frontend-user
git clone <your-frontend-admin-repo> Case-Database-Frontend-admin

# 3. 用 Cursor 打开 my-workspace/，AI 配置自动生效
```

### 方式二：选择性复制

```bash
cp -r vibe-cursor-pro/.cursor       your-project/
cp -r vibe-cursor-pro/docs          your-project/
cp -r vibe-cursor-pro/scripts       your-project/
cp    vibe-cursor-pro/.cursorignore  your-project/
```

### 初始化后的配置

1. **配置 MCP 服务** — 编辑 `.cursor/mcp.json`，填入 Token 和连接信息
2. **设置信任等级** — 编辑 `002-safety.mdc` 末尾的 `项目状态`（new_project / established / trusted）
3. **填写项目知识库** — 在 `docs/` 目录下填写你的 PRD、架构、数据模型等文档
4. **健康检查** — `bash scripts/context-doctor.sh`

---

## 日常使用指南

### 快捷指令

| 指令 | 作用 |
|------|------|
| `@planning` | 进入规划模式，输出结构化执行计划 |
| `@review` | 对当前文件做代码审查 |
| `@debug` | 进入调试模式，系统化排查 |
| `@refactor` | 重构模式，测试先行、小步安全改善 |
| `/test` | 为当前代码生成对应测试 |
| `/doc` | 更新相关文档或生成 ADR |
| `/skill-name` 或 `@skill-name` | 显式调用指定技能 |
| `停止` / `STOP` / `ABORT` | 紧急停止当前所有操作 |

### 常见场景

**端到端开发** — 直接描述需求，AI 自动编排 `full-feature` 技能完成数据库 -> API -> UI 全链路

**创建后端模块** — AI 自动加载 `skill-backend-scaffold` 规则，生成 Controller / Service / Repository / FormRequest

**创建前端页面/组件** — AI 自动加载 `skill-vue-page` 或 `skill-component-scaffold` 规则

**排查 Bug** — AI 自动加载 `skill-debugging` 规则（alwaysApply），按七步法系统排查

**代码审查** — `@review` 触发，从安全/正确/可维护/性能/可测试/一致性六维度审查

**性能优化** — AI 自动加载 `022-performance` 规则，包含诊断流程和编码规范

### PRISM 工作流

AI 处理所有任务都遵循 PRISM 流程：

```
Scan      -> 理解意图、匹配相关技能
Plan      -> 分析复杂度（L1~L4），制定执行计划
Retrieve  -> 加载文档和 MCP 工具
Implement -> 逐步执行，每步验证
Synthesize -> 质量检查、变更摘要、更新文档
Monitor   -> 记录决策、提供后续建议
```

| 复杂度 | 特征 | AI 行为 |
|--------|------|---------|
| L1 | 单文件、明确需求 | 直接执行 |
| L2 | 多文件、需上下文 | 简要规划后执行 |
| L3 | 架构变更、跨系统 | 输出计划，等确认后执行 |
| L4 | 生产环境、不可逆 | 强制规划 + 人工审批 |

---

## Rules 规则系统

Rules 是 AI 的"行为手册"，控制 AI **怎么写代码**。共 33 个 `.mdc` 文件，按三种机制自动加载。

### 加载机制

| 机制 | 说明 | 文件数 |
|------|------|--------|
| **alwaysApply** | 每次对话必定注入，构成 AI 的行为底线 | 5 |
| **globs** | 编辑匹配文件时自动注入（如编辑 `.vue` 文件触发 Vue 规则） | 16 |
| **SEMANTIC** | Cursor 根据用户意图语义匹配注入（如讨论"性能优化"触发性能规则） | 12 |

### 完整规则清单

#### alwaysApply — 每次对话自动加载（5 个）

| 文件 | 大小 | 作用 |
|------|------|------|
| `000-constitution.mdc` | 3.1KB | **AI 宪法**：身份定义（15 年全栈架构师）、核心 Vibe（Intent-First / Slow-to-Fast / Evidence-Based / Fail-Safe）、基本承诺与禁止行为、MCP 自动调用规则、交互语言、紧急停止关键词 |
| `001-workflow.mdc` | 3.0KB | **PRISM 工作流**：Scan -> Plan -> Retrieve -> Implement -> Synthesize -> Monitor 六步法、复杂度判定（L1~L4）、L2+ 规划输出格式、Synthesize 验证门、完成报告格式、快捷指令表 |
| `002-safety.mdc` | 2.5KB | **安全权限**：四级操作权限（GREEN/YELLOW/ORANGE/RED）、敏感操作清单（删文件/改配置/装依赖/git push 等）、绝对禁止项、敏感信息自动检测（AWS/GitHub/Stripe 密钥格式）、文件保护清单、信任等级开关 |
| `003-skills.mdc` | 2.1KB | **Skills 微索引**：两层激活机制说明（自动激活层 skill-*.mdc + 按需加载层 SKILL.md）、技能间依赖关系图、10 个低频技能的兜底路由表、SKILL.md 标准格式、验证门规则 |
| `skill-debugging.mdc` | 1.9KB | **调试技能（始终可用）**：信号解析（错误消息/复现步骤/影响区域/环境信息）、调试策略路由（PHP/API/DB/Vue/样式各有首选方式）、七步法核心流程（复现->收集->假设->验证->修复->回归）、硬停止条件、验证清单 |

#### globs — 按文件类型自动注入（16 个）

**编码规范类**（编辑对应类型文件时自动加载）：

| 文件 | 匹配 globs | 作用 |
|------|-----------|------|
| `010-typescript.mdc` | `*.ts` `*.mjs` `*.vue` | **TypeScript 规范**：ES2022+ 语法、JSDoc 类型注释、命名约定（camelCase 变量/PascalCase 类型/UPPER_CASE 常量）、错误处理模式、import 排序 |
| `011-vue.mdc` | `*.vue` `*/src/**/*.ts` | **Vue 3 规范 + 双前端上下文**：Composition API / Pinia / Composable 规范、Props 数据流模式（禁止直接修改 prop）、Emits camelCase 命名、单向数据流。内含双前端上下文规则：自动识别用户端（Headless UI + Tailwind，禁止 Element Plus）vs 管理端（Element Plus，权限守卫/二次确认/表单验证/分页），以及共享层约束（纯 TS，无 UI 依赖） |
| `012-tailwind.mdc` | `*.vue` | **Tailwind CSS 规范**：类名排序、响应式设计、暗色模式、管理端 Element Plus 主题桥接、用户端纯 Tailwind |
| `013-backend.mdc` | `*.php` | **Hyperf 后端规范**：分层架构（Controller->Service->Repository->Model）、依赖注入、RESTful API、认证授权、Swoole 协程安全 |
| `014-database.mdc` | 数据库相关文件 | **数据库规范**：Hyperf ORM 使用、Migration 规范、查询优化、索引策略、高并发表设计 |
| `015-testing.mdc` | `*.test.*` `*.spec.*` `__tests__/**` `phpunit.xml` | **测试规范（后端为主）**：通用测试原则（测行为/单一职责/不为覆盖率写无意义测试）、后端 PHPUnit 金字塔（Unit 60% / Integration 30% / Static 持续）、PHPStan 配置、AAA 模式、覆盖率目标。前端测试的具体工作流由 `skill-vue-testing.mdc` 负责 |
| `016-swoole.mdc` | `*.php` | **Swoole 规范**：协程安全（禁止全局变量、static 状态）、连接池管理、Channel 通信、defer 用法、内存泄漏防护 |
| `018-responsive.mdc` | `*.vue` | **响应式设计**：断点体系、移动优先策略、触摸目标尺寸、管理端 Element Plus 适配 |
| `021-deployment.mdc` | `docker-compose*` `Dockerfile*` `.github/workflows/**` `.env*` | **部署规范**：Docker Compose 配置、CI/CD 流程、环境管理、蓝绿部署、PHP+Vue 双栈构建 |
| `023-accessibility.mdc` | `*.vue` `*.html` | **无障碍规范**：WCAG AA 标准、语义化 HTML、ARIA 属性、键盘导航、Vue 3 无障碍实践 |
| `026-secure-coding.mdc` | `*.php` `*.ts` `*.vue` | **安全编码**：SQL 注入防护、XSS 防护、禁用加密算法、IDOR/Mass Assignment 防护、Session 安全、文件上传校验 |

**技能规则类**（编辑对应类型文件时自动加载执行摘要）：

| 文件 | 匹配 globs | 作用 |
|------|-----------|------|
| `skill-backend-scaffold.mdc` | `**/Controller/**/*.php` `**/Service/**/*.php` `**/Repository/**/*.php` | **后端模块脚手架**（合并了原 api-scaffold + hyperf-service）：新建 API 端点或 Service 模块时激活。含完整执行流程（加载规范->确认规格->生成文件->事务/日志/重试）、分层约定、异常体系（Business/Validation/System）、验证清单 |
| `skill-component-scaffold.mdc` | `**/components/**/*.vue` `**/composables/**/*.ts` | **Vue 组件脚手架**：新建组件或重大组件拆分时激活。含前端识别（管理端 Element Plus / 用户端 Headless UI）、文件结构输出、行数限制（SFC <= 150 行）、设计决策树 |
| `skill-database-migration.mdc` | `**/migrations/**/*.php` | **数据库迁移**：Schema 变更时激活。安全等级 ORANGE。核心原则（每次变更都是迁移/Schema 与 Data 分离/迁移部署后不可变/新字段 nullable）、执行流程、验证清单 |
| `skill-vue-page.mdc` | `**/router/**/*.ts` `**/views/**/*.vue` | **Vue 页面脚手架**：新建路由页面时激活。含强制拆分分析（多视图检测/行数预估/重复 UI 检测）、文件结构输出、页面类型（list/detail/form/dashboard/multi-view） |
| `skill-vue-testing.mdc` | `**/*.test.*` `**/__tests__/**` | **前端测试工作流**：新建或更新测试文件时激活。含测试决策树（纯函数->单元/UI 交互->组件/跨页面->E2E）、核心原则（逻辑提取/穷举排列/AAA/单一行为）、增量式工作流、覆盖率目标 |

#### SEMANTIC — 按用户意图语义匹配（12 个）

Cursor 根据用户消息的语义自动判断是否注入，无需文件匹配。

**编码规范类**：

| 文件 | 触发场景 | 作用 |
|------|---------|------|
| `017-architecture.mdc` | 讨论水平扩展、限流降级、熔断、高可用架构 | **百万级并发架构**：无状态服务、读写分离、缓存策略、队列削峰、灰度发布 |
| `019-modular.mdc` | 新建模块、讨论架构设计、模块划分、依赖方向 | **模块化架构**：DDD 边界、依赖方向单向、循环依赖检测、文件拆分阈值 |
| `020-git.mdc` | 讨论 Git 操作、分支策略、提交规范 | **Git 规范**：分支策略（Git Flow）、Conventional Commits、PR 模板 |
| `022-performance.mdc` | 报告页面慢、打包体积大、性能优化、Core Web Vitals | **性能规范 + 审计流程**（合并了原 skill-performance-audit）：诊断流程（基线收集->四维度审计->输出建议）+ 编码规范（Vite 构建/Swoole 调优/数据库查询/缓存/Nginx/连接池） |
| `024-monitoring.mdc` | 讨论日志、监控、告警、Sentry | **日志与监控**：Hyperf Monolog 配置、Vue 3 错误处理、Swoole 监控、告警策略 |
| `025-licensing.mdc` | 讨论版权、许可证、素材合规 | **版权合规**：许可证白名单/黑名单、字体/图标/图片素材选用规范 |

**技能规则类**：

| 文件 | 触发场景 | 作用 |
|------|---------|------|
| `030-subagents.mdc` | 需要委托子任务给独立 Agent 并行执行 | **Subagent 编排**：调用方式（Read agents/*.md -> Task 工具）、3 个可用 Subagent（repo-scout/test-runner/security-sentinel）、使用模式（清洁上下文/并行/链式/扇出） |
| `033-refactoring.mdc` | 重构代码、清理技术债、优化代码结构 | **安全重构工作流**（合并了 SKILL.md 内容）：黄金规则（行为不变/小步快跑/测试先行）、坏味道与重构手法对照表（10 种模式）、禁止事项、验证清单 |
| `skill-code-review.mdc` | 要求 review 代码、检查质量、审查 PR | **六维度代码审查**：安全性->正确性->可维护性->性能->可测试性->一致性，含预提交检查命令和结构化输出格式 |
| `skill-full-feature.mdc` | 端到端功能开发（数据库到 API 到 UI） | **全链路功能开发**：Phase 1 规划 -> Phase 2 数据层 -> Phase 3 后端 API -> Phase 4 前端 UI -> Phase 5 集成验证 -> Phase 6 收尾。自动编排其他技能协同 |
| `skill-i18n.mdc` | 添加多语言支持、翻译、vue-i18n | **国际化**：i18n 初始化流程、键命名公式（{feature}.{context}.{action}）、标准命名空间、验证清单 |
| `skill-security-audit.mdc` | 安全审查、漏洞扫描、OWASP 检查 | **安全审计**：安全等级 RED、依赖扫描、OWASP Top 10 逐项检查、PHP/前端/密钥扫描、中间件链验证、分级输出报告 |

### 两层架构说明

v4.0 引入两层技能激活机制，解决了技能命中率低的问题：

```
自动激活层（skill-*.mdc）— Cursor 通过 globs/description 自动注入
  ↓ 精简执行摘要，Agent 直接遵循
  ↓ 需要完整模板时...
按需加载层（SKILL.md）— Agent 主动 Read 获取完整详情
```

每个 `skill-*.mdc` 顶部都标注了对应 SKILL.md 的路径，Agent 需要深度参考时可自行 Read。

---

## Skills 技能系统

Skills 定义**可复用的任务工作流**，控制 AI **怎么完成任务**。共 23 个技能，位于 `.cursor/skills/`。

### 与 Rules 的区别

| | Rules (.mdc) | Skills (SKILL.md) |
|---|---|---|
| **职责** | 编码规范 + 执行摘要 | 完整任务工作流 + 模板 |
| **加载** | Cursor 平台自动注入 | Agent 按需 Read |
| **解决** | "代码怎么写" | "任务怎么完成（完整版）" |

### 两层加载

```
Tier 1 — 自动激活:  skill-*.mdc 精简摘要，Cursor 自动注入  (~1-2KB/个)
Tier 2 — 按需深入:  SKILL.md 完整流程 + references/ 深度参考 (~2-8KB/个)
```

13 个高频技能有 `.mdc` 自动激活入口（见上方 Rules 清单），其余 10 个低频技能需要 Agent 手动 Read。

### 技能清单

**已有 .mdc 自动激活入口的技能（13 个）**：

| 技能 | 激活方式 | 说明 |
|------|---------|------|
| `debugging` | alwaysApply | 七步法系统化调试 |
| `component-scaffold` | globs | Vue 3 SFC 组件脚手架 |
| `vue-page` | globs | Vue Router 页面脚手架 |
| `api-scaffold` | globs（via backend-scaffold） | Hyperf API 端点脚手架 |
| `hyperf-service` | globs（via backend-scaffold） | Hyperf Service 模块脚手架 |
| `database-migration` | globs | Hyperf 数据库迁移 |
| `vue-testing` | globs | Vitest 前端测试工作流 |
| `code-review` | SEMANTIC | 六维度代码审查 |
| `full-feature` | SEMANTIC | 端到端功能开发 |
| `refactoring` | SEMANTIC（via 033-refactoring） | 安全重构工作流 |
| `security-audit` | SEMANTIC | OWASP 安全审计 |
| `performance-audit` | SEMANTIC（via 022-performance） | 性能审计流程 |
| `i18n` | SEMANTIC | 国际化工作流 |

> `api-scaffold` 和 `hyperf-service` 合并为 `skill-backend-scaffold.mdc`；`performance-audit` 合并到 `022-performance.mdc`；`refactoring` 合并到 `033-refactoring.mdc`。

**仅 SKILL.md 按需加载的技能（10 个）**：

| 技能 | 触发场景 | 说明 |
|------|---------|------|
| `anti-scraping` | 反爬虫/Bot 防护 | T1~T5 五级反爬虫策略 |
| `bug-reproduce` | 复现 Bug/回归测试 | 结构化复现框架，不修复 |
| `documentation` | 写文档/README/ADR | 结构化文档生成 |
| `env-setup` | 环境配置/项目初始化 | PHP+Node 双栈环境初始化 |
| `mcp-builder` | 构建 MCP Server | TypeScript MCP SDK 封装 |
| `message-queue` | 消息队列/异步任务 | Hyperf AsyncQueue + Redis |
| `nginx-config` | 配置 Nginx/反向代理 | SSL/Gzip/安全头/负载均衡 |
| `redis-cache` | 添加 Redis 缓存 | Cache-Aside/分布式锁/连接池 |
| `skill-creator` | 创建新技能 | 生成符合规范的 SKILL.md |
| `websocket-service` | WebSocket/实时通信 | Swoole WebSocket 服务 |

### 使用方式

**自然语言触发**（推荐）— 直接描述任务，AI 自动匹配技能

**显式调用** — `/skill-name` 或 `@skill-name`

**管理脚本**：

```bash
bash scripts/skill-manager.sh list       # 列出所有技能
bash scripts/skill-manager.sh validate   # 验证格式合规性
bash scripts/skill-manager.sh stats      # 查看统计信息
bash scripts/skill-manager.sh create <name>  # 创建新技能
```

### 创建自定义技能

```
.cursor/skills/my-skill/
├── SKILL.md          # 必须：主流程 + 验证，含 YAML frontmatter
├── references/       # 可选：深度内容（模板、示例）
├── scripts/          # 可选：自动化脚本
└── assets/           # 可选：模板文件
```

```yaml
---
name: my-skill
description: "做什么 + 什么时候用（< 250 字符）"
requires: [dep-skill]  # 可选：声明依赖
---
```

---

## Subagents 任务委托

Subagents 通过 `Task` 工具将子任务委托给独立 Agent 执行，实现上下文隔离和并行处理。

### 内置 3 个委托模板

位于 `.cursor/agents/`：

| Agent | 职责 | 模式 |
|-------|------|------|
| `repo-scout` | 代码库探索、文件定位 | 只读 |
| `test-runner` | 运行测试、分析失败 | 读写（后台） |
| `security-sentinel` | 安全扫描、密钥泄漏检测 | 只读 |

### 编排模式

- **链式**：Repo Scout 探索 -> 主 Agent 实现 -> Test Runner 验证
- **扇出**：同一任务拆分给多个 Agent 并行处理

---

## MCP 服务配置

`.cursor/mcp.json` 配置 AI 可调用的外部工具。

### 已启用服务

| 服务 | 用途 |
|------|------|
| `context7` | 获取最新库/框架文档 |
| `filesystem` | 文件系统读写 |
| `git` | Git 仓库操作 |
| `fetch` | 网络请求 |
| `memory` | 跨对话知识图谱记忆 |
| `sequential-thinking` | 复杂问题分步推理 |

### 按需启用（需凭证）

| 服务 | 用途 | 配置项 |
|------|------|--------|
| `github` | PR / Issue 管理 | `GITHUB_TOKEN` |
| `mysql` | 直接查询数据库 | 连接信息 |
| `brave-search` | 网页搜索 | `BRAVE_API_KEY` |
| `playwright` | 浏览器自动化 | 按需 |

---

## 文档知识库

`docs/` 目录是项目的结构化知识库，AI 按需读取以理解业务背景。

```
docs/
├── vision/
│   ├── PRD.md                    # 产品需求
│   └── roadmap.md                # 路线图
├── architecture/
│   ├── system-design.md          # 系统架构
│   ├── data-model.md             # 数据模型
│   ├── api-contracts.md          # API 契约
│   ├── frontend-strategy.md      # 双前端架构策略
│   └── decisions/                # ADR 架构决策记录
├── guides/
│   ├── style-guide.md            # 代码风格
│   ├── ui-specs-user.md          # 用户端 UI 规范
│   ├── ui-specs-admin.md         # 管理端 UI 规范
│   └── testing-strategy.md       # 测试策略
├── reference/                    # 参考文档
└── runbooks/                     # 运维手册
```

---

## 自动化脚本

所有脚本位于 `scripts/`，纯 Bash 实现。

| 脚本 | 用途 |
|------|------|
| `setup.sh` | 一键初始化：创建目录结构、配置 Git Hooks |
| `ai-guard.sh` | 质量门禁：Lint + 类型检查 + 测试 + 安全扫描 |
| `skill-manager.sh` | Skills 管理：列出/验证/统计/创建 |
| `pre-commit` | Git pre-commit Hook |
| `context-doctor.sh` | 健康检查：验证规则/技能/MCP 配置 |

---

## 项目结构

```text
vibe-cursor-pro/
│
├── .cursor/                              # Cursor 配置中心
│   ├── rules/                            # 33 个 .mdc 规则文件
│   │   ├── 000-constitution.mdc          # [alwaysApply] AI 宪法
│   │   ├── 001-workflow.mdc              # [alwaysApply] PRISM 工作流
│   │   ├── 002-safety.mdc               # [alwaysApply] 安全权限
│   │   ├── 003-skills.mdc               # [alwaysApply] Skills 微索引
│   │   ├── 010-typescript.mdc            # [globs] TypeScript 规范
│   │   ├── 011-vue.mdc                   # [globs] Vue 3 规范 + 双前端上下文
│   │   ├── 012-tailwind.mdc              # [globs] Tailwind CSS 规范
│   │   ├── 013-backend.mdc              # [globs] Hyperf 后端规范
│   │   ├── 014-database.mdc             # [globs] 数据库规范
│   │   ├── 015-testing.mdc              # [globs] 测试规范（后端为主）
│   │   ├── 016-swoole.mdc               # [globs] Swoole 协程规范
│   │   ├── 017-architecture.mdc          # [SEMANTIC] 并发架构设计
│   │   ├── 018-responsive.mdc            # [globs] 响应式设计
│   │   ├── 019-modular.mdc              # [SEMANTIC] 模块化架构
│   │   ├── 020-git.mdc                  # [SEMANTIC] Git 规范
│   │   ├── 021-deployment.mdc            # [globs] 部署规范
│   │   ├── 022-performance.mdc           # [SEMANTIC] 性能规范+审计流程
│   │   ├── 023-accessibility.mdc         # [globs] 无障碍规范
│   │   ├── 024-monitoring.mdc            # [SEMANTIC] 日志与监控
│   │   ├── 025-licensing.mdc             # [SEMANTIC] 版权合规
│   │   ├── 026-secure-coding.mdc         # [globs] 安全编码
│   │   ├── 030-subagents.mdc             # [SEMANTIC] Subagent 编排
│   │   ├── 033-refactoring.mdc           # [SEMANTIC] 安全重构工作流
│   │   ├── skill-backend-scaffold.mdc    # [globs] 后端模块脚手架
│   │   ├── skill-code-review.mdc         # [SEMANTIC] 代码审查
│   │   ├── skill-component-scaffold.mdc  # [globs] Vue 组件脚手架
│   │   ├── skill-database-migration.mdc  # [globs] 数据库迁移
│   │   ├── skill-debugging.mdc           # [alwaysApply] 调试技能
│   │   ├── skill-full-feature.mdc        # [SEMANTIC] 全链路功能开发
│   │   ├── skill-i18n.mdc               # [SEMANTIC] 国际化
│   │   ├── skill-security-audit.mdc      # [SEMANTIC] 安全审计
│   │   ├── skill-vue-page.mdc            # [globs] Vue 页面脚手架
│   │   ├── skill-vue-testing.mdc         # [globs] 前端测试工作流
│   │   └── references/                   # 规则深度内容（Tier 3）
│   │
│   ├── skills/                           # 23 个技能（SKILL.md + references/）
│   │   ├── api-scaffold/                 # API 端点脚手架
│   │   ├── anti-scraping/                # 反爬虫防护
│   │   ├── bug-reproduce/                # Bug 复现框架
│   │   ├── code-review/                  # 代码审查
│   │   ├── component-scaffold/           # Vue 组件脚手架
│   │   ├── database-migration/           # 数据库迁移
│   │   ├── debugging/                    # 调试工作流
│   │   ├── documentation/                # 文档生成
│   │   ├── env-setup/                    # 环境初始化
│   │   ├── full-feature/                 # 全链路功能开发
│   │   ├── hyperf-service/               # Hyperf Service 模块
│   │   ├── i18n/                         # 国际化
│   │   ├── mcp-builder/                  # MCP Server 构建
│   │   ├── message-queue/                # 消息队列
│   │   ├── nginx-config/                 # Nginx 配置
│   │   ├── performance-audit/            # 性能审计
│   │   ├── redis-cache/                  # Redis 缓存
│   │   ├── refactoring/                  # 重构工作流
│   │   ├── security-audit/               # 安全审计
│   │   ├── skill-creator/                # 创建新技能
│   │   ├── vue-page/                     # Vue 页面脚手架
│   │   ├── vue-testing/                  # 前端测试
│   │   └── websocket-service/            # WebSocket 服务
│   │
│   ├── agents/                           # 3 个 Subagent 模板
│   │   ├── repo-scout.md                 # 代码库探索
│   │   ├── test-runner.md                # 测试执行
│   │   └── security-sentinel.md          # 安全扫描
│   │
│   └── mcp.json                          # MCP 服务配置
│
├── docs/                                 # 项目知识库
├── scripts/                              # 自动化脚本
│
├── Case-Database-Backend/                # Hyperf 后端（gitignored）
├── Case-Database-Frontend-user/          # Vue 3 用户端（gitignored）
├── Case-Database-Frontend-admin/         # Vue 3 管理端（gitignored）
├── Case-Database-Frontend-shared/        # 共享层（gitignored）
│
├── .cursorignore                         # Cursor 索引排除
├── .gitignore
├── .editorconfig
├── .prettierrc
├── commitlint.config.ts
└── README.md
```

---

## 定制化指南

### 适配不同技术栈

宪法级规则（000-003）和大部分技能都是技术栈无关的。

**需要替换的文件**：

| 文件 | 修改内容 |
|------|---------|
| `010-typescript.mdc` | 替换为对应语言规范 |
| `011-vue.mdc` | 替换为 React / Svelte / Angular 规范 |
| `012-tailwind.mdc` | 替换为你的 CSS 方案 |
| `013-backend.mdc` | 替换为 Node.js / Go / Java 后端规范 |
| `014-database.mdc` | 替换为 PostgreSQL / MongoDB 规范 |
| `016-swoole.mdc` | 不使用 Swoole 可删除 |

**不需要修改**：000-003 宪法级、020-git、023-accessibility、debugging/code-review/refactoring 等通用技能。

### 添加新规则

在 `.cursor/rules/` 下创建 `.mdc` 文件：

```yaml
---
description: "规则描述（用于 SEMANTIC 匹配）"
globs:                    # 可选：文件匹配模式
  - "**/*.vue"
alwaysApply: false        # 可选：是否始终加载
---

# 规则内容（Markdown）
```

### 添加新技能

```bash
bash scripts/skill-manager.sh create my-new-skill
```

---

## 常见问题

### Rules 没有生效？

1. 确认扩展名为 `.mdc`
2. 确认 YAML frontmatter 格式正确
3. 运行 `bash scripts/context-doctor.sh`
4. 重启 Cursor

### Skills 没有自动触发？

v4.0 引入了两层激活机制，13 个高频技能已有 `.mdc` 自动入口，应能自动触发。如仍未触发：

1. 尝试显式调用：`/skill-name` 或 `@skill-name`
2. 检查对应 `skill-*.mdc` 的 `description` 是否覆盖了你的使用场景
3. 检查 SKILL.md 的 `description` 字段

### Token 消耗太高？

1. 检查 `alwaysApply: true` 的规则数量 — 仅保留 5 个（000/001/002/003/debugging）
2. 当前 alwaysApply 总量约 12.6KB（~3,600 tokens），在合理范围内
3. globs 触发的规则仅在编辑匹配文件时注入
4. SEMANTIC 规则仅在用户意图匹配时注入

---

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| v4.0 | 2026-03-01 | **Skill 命中率优化三轮迭代**：引入两层激活机制（skill-*.mdc 自动注入 + SKILL.md 按需加载）；alwaysApply 从 32KB 降至 12.6KB（-60%）；消除 available_skills 幻觉概念；合并冗余规则（api-scaffold + hyperf-service -> backend-scaffold / 022-performance 吸收 audit / 011-vue 吸收 context / 015-testing 去重前端）；019-modular 和 017-architecture 从 globs 改 SEMANTIC 降低注入量；13 个技能有 .mdc 自动入口，10 个低频技能按需 Read；策略 B 双向标注（.mdc 指向 SKILL.md，SKILL.md 标注 .mdc）|
| v3.7 | 2026-02-26 | 双前端架构适配：新增用户端/管理端/共享层目录和规则 |
| v3.6 | 2026-02-26 | Workspace 模式（推荐）：vibe-cursor-pro 作为主工作区 |
| v3.5 | 2026-02-24 | 全栈防爬（T1~T5）；新增 018/019/025 规则；版权合规 |
| v3.4 | 2026-02-24 | 深度对齐旧项目分析报告 |
| v3.3 | 2026-02-24 | PHPbase：迁移至 Vue 3 + PHP Hyperf + Swoole |
| v3.0 | 2026-02-12 | Cursor 专属重构 |