vibe_coding/README.md

Vibe Cursor Pro

企业级 Cursor Vibe Coding 模板 v4.0

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

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

---

目录

• 为什么需要这个模板
• 环境要求
• 快速开始
• 日常使用指南
• Rules 规则系统
• Skills 技能系统
• Subagents 任务委托
• 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 中的双前端上下文规则自动感知目标前端并应用不同设计原则。

初始化步骤

# 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 配置自动生效

方式二：选择性复制

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 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/           # 可选：模板文件

---
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 配置

---

项目结构

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 文件：

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

# 规则内容（Markdown）

添加新技能

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 专属重构