Cursor AI 编辑器与 SDD 开发工作流实战指南：从入门到精通

在当前 AI 编程领域，Cursor 已成为开发者不可或缺的效率工具，能够显著提升编码速度。然而，仅有工具并不足够——关键在于如何确保 AI 输出精准可靠、如何让它真正理解项目意图。本文将系统梳理从 Cursor 基础操作、Rules/Skills 高级配置，到 OpenSpec 规格驱动开发（SDD）完整工作流，提供一站式实战指南，帮助你快速掌握这套高效开发体系。

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

1.1 下载与安装（全平台支持）

官方下载地址：cursor.com/download/

• Windows：下载 .exe 安装包，双击运行即可使用
• macOS：下载 .dmg，直接拖入 Applications 文件夹
• Linux：下载 .AppImage 或 .deb 包

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 → 改前端组件 → 跑类型检查

1.3 上下文控制：@ 引用

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

实战技巧：

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

原则很简单：先收窄上下文，再执行大改动；上下文越精准，无效输出越少。

1.4 模型选择

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

二、Rules：为 AI 设置行为规范

2.1 什么是 Rules

Rules 是你写给 AI 的「永久指令」，放置在项目根目录后，每次对话 AI 都会自动遵循。它的作用非常明确：

• 统一代码风格（"用 TypeScript strict 模式"、"禁止使用 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

三、Skills：为 AI 扩展能力

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/

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

设计哲学：

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

五、完整实战：从零开始构建一个功能

场景

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

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

八、延伸资源