Cursor AI 编辑器 + SDD 开发工作流实战指南

Cursor AI 编辑器 + SDD 开发工作流实战指南

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

---

一、Cursor 编辑器：AI 辅助开发入门

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 补全	Tab	写代码时的行内补全、续写	光标处直接插入代码
Agent 模式	Ctrl+L / Chat 面板切换	跨文件重构、端到端实现需求	直接读写文件、执行终端命令

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 质量 = 模型能力 × 上下文质量 。@ 引用是喂上下文最直接的方式：

引用语法	含义	用途
@filename.ts	引用具体文件	让 AI 精准理解某个文件
@folder/	引用整个文件夹	给 AI 一个模块的全貌
@codebase	语义搜索整个仓库	"不知道代码在哪"时用
@docs	引用外部文档	让 AI 读框架文档而非靠记忆
@web	搜索互联网	获取最新信息、查版本
@git	引用 Git 历史	查看最近改了什么

实战技巧：

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

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

1.4 模型选择

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

模型层次	适合任务	说明
快速模型	Tab 补全、简单重命名、格式化	低延迟、成本低
强模型	架构设计、复杂 bug 分析、跨模块重构	推理强、成本高

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

---

二、Rules：给 AI 立规矩

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 的类型

类型	触发方式	配置
Always（全局）	每次对话都生效	alwaysApply: true
Auto（自动）	匹配到特定文件时生效	globs: "*.tsx"
Agent Requested	AI 自己判断是否需要	写好 description
Manual	需手动 @ruleName 引用	不设 globs，不设 alwaysApply

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

---

三、Skills：给 AI 加技能

3.1 什么是 Skills

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

Rules vs Skills：

对比	Rules	Skills
定位	约束和规范	能力和方法论
触发	自动/按文件类型	AI 判断后主动调用
内容	简短的规则清单	详细的操作流程 + 模板
场景	"代码风格要这样"	"遇到这种需求要按这个流程做"

3.2 常用 Skills 类型

Skill 名称	用途
brainstorming	在实现前先探索需求、做方案设计
writing-plans	写实现计划，拆解任务
test-driven-development	TDD 流程：先写测试再实现
systematic-debugging	遇到 bug 时系统化排查
subagent-driven-development	将独立任务分派给并行子 Agent
verification-before-completion	完成前必须跑验证命令确认

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/

四、SDD：Spec-Driven Development（规格驱动开发）

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 编程助手设计。

设计哲学：

原则	说明
Fluid not Rigid	流式迭代，不搞阶段门控
Iterative not Waterfall	边做边学，随时修正
Easy not Complex	轻量设置，最少仪式感
Brownfield-first	面向已有代码库的增量开发

4.3 安装 OpenSpec

前提：Node.js >= 20.19.0

# 全局安装
npm install -g @fission-ai/openspec@latest

# 进入你的项目目录
cd your-project

# 初始化
openspec init

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

openspec/
├── specs/              # 源头规格（系统当前行为描述）
│   └── <domain>/
│       └── spec.md
├── changes/            # 变更提案（每次改动一个文件夹）
│   └── <change-name>/
│       ├── proposal.md     # 为什么做、做什么
│       ├── design.md       # 怎么做（技术方案）
│       ├── tasks.md        # 实现清单
│       └── specs/          # Delta Specs（变更了哪些行为）
│           └── <domain>/
│               └── 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 最核心的概念------不重写整个规格，只描述「变了什么」：

区段	含义	归档时操作
## ADDED Requirements	新增行为	追加到主规格
## MODIFIED Requirements	修改行为	替换主规格中对应条目
## REMOVED Requirements	移除行为	从主规格中删除

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

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

4.6 OpenSpec 命令速查

核心路径（默认）

命令	作用
/opsx:propose <name>	创建变更 + 一次性生成所有制品
/opsx:explore	探索思考，不创建制品
/opsx:apply	按 tasks 逐项实现
/opsx:archive	归档已完成变更

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

自定开启 openspec config profile

命令	作用
/opsx:new <name>	只创建变更骨架
/opsx:continue	按依赖顺序创建下一个制品
/opsx:ff	快进：一次创建所有规划制品
/opsx:verify	验证实现是否匹配 Spec
/opsx:sync	将 Delta Specs 合入主规格（不归档）
/opsx:bulk-archive	批量归档
/opsx:onboard	交互式引导教程

在 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：审阅制品

关键审阅点：

制品	重点检查
proposal.md	范围是否正确？有没有超出本次要做的？
specs/	行为描述是否和你理解的一致？场景覆盖边界了吗？
design.md	技术方案是否合理？是否和现有架构冲突？
tasks.md	任务粒度是否合适？有没有遗漏步骤？

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

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

Step 5：执行实现

/opsx:apply

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

Step 6：验证并归档

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

---

六、常见问题与注意事项

6.1 常见坑

现象	原因	对策
AI 改了一堆无关文件	上下文过大、任务描述太泛	缩小 @ 引用范围；写清"只改这几个文件"
AI 编造不存在的 API	缺乏真实文档	用 @docs 喂入官方文档；贴已有代码示例
重复犯同样的错	没有固化规范	写进 Rules，一劳永逸
Diff 太大难审阅	一次改太多	拆任务；先接口后实现
制品与代码脱节	实现中改了方案但没更新制品	发现问题后回 Spec/Design 修正再继续

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
└── 理念：先对齐需求，再写代码；流式迭代，不卡阶段

---

八、延伸资源

资源	链接
Cursor 官网	cursor.com
Cursor 下载	cursor.com/download
OpenSpec GitHub	github.com/Fission-AI/...
OpenSpec 入门文档	Getting Started
OpenSpec 命令手册	Commands
OpenSpec 核心概念	Concepts
OpenSpec 工作流	Workflows