目标：掌握 Cursor 基础使用、Skills/Rules 配置、OpenSpec SDD 完整工作流

1.1 下载与安装（全平台）

官方下载 ：cursor.com/download/

• Windows ：下载 .exe 安装包，双击运行即可
• macOS ：下载 .dmg，拖入 Applications
• Linux ：下载 .AppImage 或 .deb

Cursor 基于 VS Code 分支，原有 VS Code 的插件、快捷键、主题大多兼容。 首次打开后可导入已有 VS Code 配置（Settings Sync）。

1.2 核心概念：三种交互方式

Cursor 提供三种与 AI 交互的方式，适用场景不同，不要混用：

Tab 补全

最轻量的交互------写代码时 Cursor 自动预测下一段代码，按 Tab 接受：

// 你打了一行注释 // 计算用户的年龄 function calculateAge( ← 此时 Cursor 自动补全函数签名和实现体

Chat 聊天

打开侧边栏聊天面板，向 AI 提问。适合：

• "这段代码在做什么？"
• "帮我写一个正则表达式，匹配邮箱格式"
• "这个函数有没有 bug？"

Chat 中可以用 @ 引用把文件、文件夹、文档喂给 AI（后面详述）。

Agent 模式（重点）

Agent 模式 = AI 可以 读文件 + 改文件 + 跑终端命令，全自动循环直到完成任务。

典型用法：

你："帮我给 User 模型加一个 avatar 字段，数据库迁移也一起做" Agent：读 schema → 改 model → 生成 migration → 跑 migrate → 改前端组件 → 跑类型检查

注意：Agent 有权限控制，首次使用时建议设置为"需要确认"模式------AI 每次改文件或跑命令前会问你确认。 熟练后可以切到"自动"模式（YOLO mode），让它自己跑。

1.3 上下文控制：@ 引用

AI 质量 = 模型能力 × 上下文质量 。@ 引用是喂上下文最直接的方式：

实战技巧：

❌ "帮我改一下登录逻辑"（AI 不知道代码在哪，会瞎猜） ✅ "帮我改一下 @src/auth/login.ts 里的登录逻辑，参考 @src/auth/register.ts 的错误处理方式"

原则：先收窄上下文，再要大改；上下文越准，废话越少。

1.4 模型选择

Cursor 支持多种模型，不同任务用不同模型：

把强模型用在「一次判断省一小时」的地方，而不是每一句闲聊。

2.1 什么是 Rules

Rules 是你写给 AI 的「永久指令」，放在项目中后，每次对话 AI 都会遵守。

作用：

• 统一代码风格（"用 TypeScript strict mode"、"不用 any"）
• 约定技术栈（"后端用 NestJS + Prisma"、"前端用 React + Zustand"）
• 约定目录结构（"组件放在 src/components/ 下"）
• 约定验证方式（"每次改完跑 pnpm test"）

2.2 创建 Rules

在项目根目录创建 .cursor/rules/ 文件夹，放入 .mdc 规则文件：

项目根目录/ ├── .cursor/ │ └── rules/ │ ├── general.mdc # 通用规则 │ ├── frontend.mdc # 前端规则 │ └── backend.mdc # 后端规则 ├── src/ └── ...

规则文件示例

.cursor/rules/general.mdc：

--- description: 项目通用开发规范 globs: alwaysApply: true --- # 项目规范 技术栈 - 语言：TypeScript（strict 模式） - 包管理器：pnpm - 测试框架：Vitest 代码规范 - 不使用 any 类型 - 函数必须有明确的返回类型 - 错误处理使用自定义 Error 类，不用裸字符串 - 提交信息格式：feat(scope): 描述 / fix(scope): 描述 验证命令 - 类型检查：pnpm tsc --noEmit - 单元测试：pnpm test - 代码检查：pnpm lint

.cursor/rules/frontend.mdc（按文件类型触发）：

--- description: 前端 React 组件规范 globs: src/components//*.tsx, src/pages//*.tsx alwaysApply: false --- # 前端组件规范 - 使用函数组件 + Hooks，不用 Class 组件 - 状态管理：简单状态用 useState，跨组件用 Zustand - 样式方案：Tailwind CSS - 组件文件结构：组件 + 类型定义放在同一文件中

2.3 Rules 的类型

2.4 另一种方式：AGENTS.md

在项目根目录放 AGENTS.md，效果类似 Rules 但写法更自由，适合写：

• 项目怎么跑起来（启动命令）
• 关键环境变量名（不要写真实密钥）
• 目录结构说明
• 协作约定

# AGENTS.md 启动方式 pnpm install && pnpm dev 环境变量 需要在 .env.local 中配置：DATABASE_URL, NEXTAUTH_SECRET 目录结构 - app/ --- Next.js App Router 页面 - lib/ --- 工具函数和服务 - components/ --- 共享 UI 组件 - prisma/ --- 数据库 schema

3.1 什么是 Skills

Skills 是比 Rules 更重量级的「能力包」------包含详细的操作步骤、代码模板、工作流程。

Rules vs Skills：

3.2 常用 Skills 类型

3.3 Skills 的安装与使用

Skills 安装后放在本地特定目录，AI 会在合适的时机自动调用。你也可以手动提示它：

你："按照 SDD 流程帮我实现这个需求" AI：（自动加载 spec-driven-dev skill，按 proposal → spec → design → tasks → implement 流程执行）

3.4 OpenSpec 作为 Skill

OpenSpec 项目本身可以作为 Cursor 的 Skill 集成。安装后，你可以直接在对话中使用 OpenSpec 命令：

你：/opsx:propose add-user-avatar AI：自动创建 proposal.md → specs/ → design.md → tasks.md

3.5官方skills仓库

仓库地址： skills.sh/

4.1 为什么需要 SDD

没有 SDD 时的问题：

你："帮我做一个用户管理功能" AI：（理解各异，写出的代码可能不是你要的） 你："不对，我要的不是这个......" AI：（推翻重来） 你："还是不对......" → 浪费 3 轮对话 + 大量 token

有 SDD 时：

你："帮我做一个用户管理功能" AI：先输出 Proposal（意图+范围）→ 你确认 AI：再输出 Spec（行为契约）→ 你确认 AI：再输出 Design（技术方案）→ 你确认 AI：最后输出 Tasks（实现清单）→ 逐个实现 → 每一步对齐，减少返工

核心理念：先对齐需求，再写代码。

4.2 OpenSpec 项目介绍

GitHub ：github.com/Fission-AI/...

OpenSpec 是一个开源的规格驱动开发框架，专为 AI 编程助手设计。

设计哲学：

4.3 安装 OpenSpec

前提：Node.js >= 20.19.0

# 全局安装 npm install -g @fission-ai/openspec@latest # 进入你的项目目录 cd your-project # 初始化 openspec init

初始化后，项目中会生成如下结构：

openspec/ ├── specs/ # 源头规格（系统当前行为描述） │ └── 
          
            / │ └── spec.md ├── changes/ # 变更提案（每次改动一个文件夹） │ └── 
           
             / │ ├── proposal.md # 为什么做、做什么 │ ├── design.md # 怎么做（技术方案） │ ├── tasks.md # 实现清单 │ └── specs/ # Delta Specs（变更了哪些行为） │ └── 
            
              / │ └── spec.md └── config.yaml # 项目配置（可选） 
             
            
          

4.4 SDD 完整工作流程

全局视图

┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌───────────┐ ┌──────────┐ │ 1. PROPOSE │───►│ 2. SPEC │───►│ 3. DESIGN │───►│ 4. TASKS │───►│ 5. APPLY │ │ 为什么做 │ │ 做什么 │ │ 怎么做 │ │ 执行清单 │ │ 写代码 │ │ + 范围 │ │ 行为契约 │ │ 技术方案 │ │ 可勾选 │ │ 逐个实现 │ └─────────────┘ └──────────────┘ └─────────────┘ └───────────┘ └──────────┘ ▲ ▲ ▲ │ └──────────────────┴──────────────────┴────── 实现中发现问题可随时回退修正 ──┘

步骤 1：Propose（提案）

在 Cursor 对话中输入：

/opsx:propose add-dark-mode

AI 会自动创建变更文件夹并生成所有制品：

✓ proposal.md --- 意图、范围、方法 ✓ specs/ --- 行为要求和场景 ✓ design.md --- 技术方案 ✓ tasks.md --- 实现清单

Proposal 示例：

# Proposal: Add Dark Mode Intent 用户反馈夜间使用刺眼，需要暗色模式减少眼部疲劳。 Scope In scope: - 设置页面添加主题切换开关 - 检测系统偏好自动切换 - 本地持久化用户偏好 Out of scope: - 自定义主题色（未来版本） - 每页独立主题设置 Approach 使用 CSS 自定义属性实现主题切换，React Context 管理状态。

步骤 2：Spec（行为契约）

Spec 不描述「怎么实现」，只描述「系统应该表现出什么行为」：

# Delta for UI ADDED Requirements Requirement: Theme Selection 系统 SHALL 允许用户在亮色和暗色主题间切换。 # Scenario: 手动切换 - GIVEN 用户在任意页面 - WHEN 用户点击主题切换按钮 - THEN 主题立即切换 - AND 偏好保存到本地，跨会话生效 # Scenario: 跟随系统 - GIVEN 用户没有保存的偏好 - WHEN 应用加载 - THEN 使用操作系统的偏好配色方案

关键语法：

• MUST / SHALL：必须实现
• SHOULD：推荐实现，允许例外
• MAY：可选实现
• GIVEN / WHEN / THEN：可验证的场景描述

步骤 3：Design（技术设计）

# Design: Add Dark Mode Architecture Decisions Decision: Context over Redux 选择 React Context 因为： - 简单的二元状态（亮/暗） - 不需要复杂状态转换 - 避免引入 Redux 依赖 Decision: CSS Custom Properties 选择 CSS 变量而非 CSS-in-JS 因为： - 与现有样式表兼容 - 无运行时开销 - 浏览器原生方案 File Changes - `src/contexts/ThemeContext.tsx` --- (new) - `src/components/ThemeToggle.tsx` --- (new) - `src/styles/globals.css` --- (modified)

步骤 4：Tasks（实现清单）

# Tasks 1. Theme Infrastructure - [ ] 1.1 Create ThemeContext with light/dark state - [ ] 1.2 Add CSS custom properties for colors - [ ] 1.3 Implement localStorage persistence 2. UI Components - [ ] 2.1 Create ThemeToggle component - [ ] 2.2 Add toggle to settings page 3. Styling - [ ] 3.1 Define dark theme color palette - [ ] 3.2 Update components to use CSS variables

步骤 5：Apply（执行实现）

/opsx:apply

AI 逐个读取 tasks.md 中的任务，写代码、改文件、跑命令，完成后打勾：

Working on 1.1: Create ThemeContext... ✓ 1.1 Complete Working on 1.2: Add CSS custom properties... ✓ 1.2 Complete ...All tasks complete!

步骤 6：Verify + Archive（验证 + 归档）

/opsx:verify ← 检查实现是否匹配 Spec /opsx:archive ← 归档变更，Delta Specs 合入主规格

归档后：

• Delta Specs 合入 openspec/specs/ 成为新的「系统当前行为」
• 变更文件夹移入 openspec/changes/archive/ 保留审计记录

4.5 Delta Specs：增量规格

Delta Specs 是 OpenSpec 最核心的概念------不重写整个规格，只描述「变了什么」：

为什么用 Delta 而不是全量覆盖：

• 清晰看出「改了什么」，而不是在整份文档里找差异
• 多个变更可以并行而不冲突
• Code Review 时只看变化部分

4.6 OpenSpec 命令速查

核心路径（默认）

扩展路径（高级，需开启）

自定开启 openspec config profile

在 Cursor 中命令语法为 /opsx-propose（短横线替换冒号）。

场景

在现有项目中添加「用户头像上传」功能。

Step 1：确保环境就绪

 
       
    
         
 
          
# 确认 OpenSpec 已安装 
 
          
openspec –version
 
          
进入项目并初始化（如未初始化过）
 
          
cd my-project openspec init
 
         

 
Step 2：确保 Rules 已配置
 

检查 .cursor/rules/ 下有项目规范文件。

Step 3：发起提案

在 Cursor Agent 对话中输入：

 
       
    
         
 
          
/opsx:propose add-user-avatar
 
         
 
AI 自动产出 4 个制品文件，逐个审阅并确认。
 

Step 4：审阅制品

关键审阅点：

如有问题，直接告诉 AI 修改：

你："proposal 的 scope 里应该排除批量上传，只做单张头像上传" AI：（修改 proposal.md）

Step 5：执行实现

 
       
    
         
 
          
/opsx:apply
 
         
 
AI 逐项实现，你可以在每一步确认或纠正。
 

Step 6：验证并归档

 
       
    
         
 
          
/opsx:verify ← 检查完整性、正确性、一致性 
 
          
/opsx:archive ← 归档，Delta Specs 合入主规格
 
         

6.1 常见坑

6.2 **实践

1. 先小后大：先用 Chat 理解代码 → 再用 Agent 做修改
2. 先规格后实现：用 SDD 流程对齐需求再写代码
3. 频繁验证：每完成一组任务跑一次测试 / 类型检查
4. 迭代修正：制品不是一次性的，实现过程中发现不对就回去改
5. 保持干净的上下文：新功能开新对话，不要在一个超长对话里做所有事

6.3 安全注意

• 永远不要把真实密钥、密码写进 Rules / AGENTS.md / 对话中
• 审阅 diff：Agent 改完代码后，逐文件审阅变更再接受
• 安装依赖要确认 ：AI 要 npm install 新包时，检查包名是否正确

 
        
    
          
 
           
Cursor 使用要点 
 
           
├── 三种交互：Tab 补全 / Chat 聊天 / Agent 代理 ├── 上下文控制：@ 引用（文件、文件夹、文档、Web、Git） ├── Rules：项目规范，让 AI 守规矩 ├── Skills：给 AI 加能力包 └── 模型选择：简单任务用快模型，复杂决策用强模型
 
           
SDD 工作流（OpenSpec） ├── 安装：npm install -g @fission-ai/openspec@latest && openspec init ├── 核心流程：Propose → Spec → Design → Tasks → Apply → Archive ├── 关键概念：Delta Specs（增量规格） ├── 核心命令：/opsx:propose /opsx:apply /opsx:archive └── 理念：先对齐需求，再写代码；流式迭代，不卡阶段