OpenSpec 规范驱动开发：从零到上手的完整集成指南

将「先写规范再写代码」的工程实践，与 AI 编程助手深度结合，让变更管理可追溯、可协作、可自动化。

一、OpenSpec 是什么？

OpenSpec 是一套规范驱动开发（Spec-Driven Development）工作流工具，帮助你：

结构化变更：每个功能变更都有清晰的 proposal、specs、design、tasks
AI 友好：与 Cursor、Claude 等 AI 工具集成，让 AI 按规范生成和实现代码
可追溯：变更从提案到归档全流程可查，便于复盘与协作

适用场景：中小型团队、个人项目、希望用 AI 辅助开发但需要可控流程的开发者。

二、环境准备

2.1 前置要求

Node.js：20.19.0 及以上
包管理器：npm 或 pnpm
AI 工具（可选）：Cursor、Claude Code 等

2.2 安装 OpenSpec

bash 复制代码

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

# 或使用 pnpm
pnpm install -g @fission-ai/openspec@latest

验证安装：

bash 复制代码

openspec --version

三、项目初始化

3.1 初始化命令

在项目根目录执行：

bash 复制代码

# 仅配置 Cursor（推荐）
openspec init --tools cursor

# 配置所有支持的 AI 工具
openspec init --tools all

# 配置多个指定工具
openspec init --tools claude,cursor

# 强制覆盖旧配置（不提示）
openspec init --tools cursor --force

3.2 初始化完成后的输出

复制代码

√ Setup complete for Cursor
4 skills and 4 commands in .cursor/
Config: openspec/config.yaml (exists)

Getting started:
  Start your first change: /opsx:propose "your idea"

Restart your IDE for slash commands to take effect.

重要：若使用 Cursor，需重启 IDE 后斜杠命令才会生效。

四、目录结构与工件关系

4.1 初始化后的整体结构

复制代码

your-project/
├── openspec/
│   ├── config.yaml              # 项目配置（含 context 供 AI 参考）
│   ├── changes/                 # 进行中的变更
│   │   └── {change-name}/
│   │       ├── .openspec.yaml   # 变更元数据
│   │       ├── proposal.md      # 变更说明（为什么、改什么）
│   │       ├── specs/           # 需求与规范
│   │       │   └── {capability}/
│   │       │       └── spec.md
│   │       ├── design.md        # 技术设计与架构
│   │       └── tasks.md         # 实现任务清单
│   └── archive/                 # 已归档变更
└── .cursor/
    ├── commands/                # Cursor 斜杠命令
    │   ├── opsx-propose.md
    │   ├── opsx-apply.md
    │   ├── opsx-explore.md
    │   └── opsx-archive.md
    └── skills/                  # OpenSpec 技能
        ├── openspec-propose/
        ├── openspec-apply-change/
        ├── openspec-explore/
        └── openspec-archive-change/

4.2 工件依赖关系（spec-driven 模式）

复制代码

proposal.md  ──┬──→  design.md
               │
               └──→  specs/**/*.md
                          │
                          └──→  tasks.md  ──→  /opsx:apply 可执行

即：先有 proposal，再衍生 design 和 specs，最后生成 tasks，AI 才能按 tasks 实现代码。

五、配置项目上下文（可选但推荐）

编辑 openspec/config.yaml，补充项目背景，供 AI 生成更贴合项目的规范：

yaml 复制代码

schema: spec-driven

# 项目上下文（可选）
context: |
  项目：你的项目名称
  技术栈：前端框架 + 后端框架 + 数据库
  API 规范：REST / GraphQL 等
  Commit 规范：如 Conventional Commits

# 按工件定制规则（可选）
# rules:
#   proposal:
#     - 提案控制在 500 字以内
#     - 必须包含「非目标」章节
#   tasks:
#     - 每个任务不超过 2 小时

六、完整工作流示例

以下以「用户反馈统计功能」为例，演示从创建到归档的全流程。

6.1 创建变更

bash 复制代码

openspec new change user-feedback-stats

6.2 变更目录结构

复制代码

openspec/changes/user-feedback-stats/
├── .openspec.yaml
├── proposal.md
├── specs/
│   └── feedback-stats/
│       └── spec.md
├── design.md
└── tasks.md

6.3 proposal.md 示例

markdown 复制代码

## Why

需要统计用户反馈的数量、类型分布和趋势，用于产品决策和运营分析。当前仅有列表展示，无法做数据洞察。

## What Changes

- 新增反馈统计 API（按类型、时间维度聚合）
- 新增管理后台统计展示页
- 支持导出 CSV 报表

## Capabilities

### New Capabilities
- `feedback-stats`: 反馈统计能力，包含 API、服务层、管理端 UI

### Modified Capabilities
- （无）

## Impact

- 后端：FeedbackStatsController、FeedbackStatsService
- 前端：stats 页面、图表组件
- 依赖：可选图表库（如 ECharts）

6.4 specs/feedback-stats/spec.md 示例

markdown 复制代码

# 反馈统计能力规范

## 概述

管理员可查看反馈的统计信息，包括数量、类型分布、时间趋势。

## 功能需求

### 统计维度
- 按反馈类型（建议/投诉/咨询）聚合
- 按日期/周/月聚合
- 支持时间范围筛选

### 展示形式
- 概览卡片：总数、各类型占比
- 趋势图：时间序列折线图
- 列表：支持分页与导出

## 非目标
- 不在此次实现：实时推送、自定义报表

6.5 design.md 示例

markdown 复制代码

# 反馈统计技术设计

## 架构

- Controller: FeedbackStatsController（GET 统计接口）
- Service: FeedbackStatsService（聚合逻辑、缓存）
- 前端：stats 页面 + 图表组件

## 关键决策

- 聚合：使用 SQL GROUP BY，避免全量加载
- 缓存：统计结果缓存 5 分钟，减轻数据库压力
- 导出：流式生成 CSV，避免大结果集 OOM

## 接口

- GET /admin/feedback-stats?type=&start=&end=
- GET /admin/feedback-stats/export?type=&start=&end=

6.6 tasks.md 示例

markdown 复制代码

# 实现任务

- [ ] 1. 创建 FeedbackStatsService 聚合方法
- [ ] 2. 实现 FeedbackStatsController 统计与导出接口
- [ ] 3. 实现管理端 stats 页面框架
- [ ] 4. 集成图表组件展示趋势
- [ ] 5. 联调测试与文档更新

七、常用命令速查

命令	说明
`openspec init --tools cursor`	初始化并配置 Cursor
`openspec new change <name>`	创建新变更
`openspec list`	列出进行中的变更
`openspec list --specs`	列出主规范
`openspec show <name>`	查看变更详情
`openspec status --change <name>`	查看变更工件完成状态
`openspec validate <name> --strict`	校验变更格式
`openspec archive <name> --yes`	归档已完成变更

八、Cursor 斜杠命令

命令	说明
`/opsx:propose "想法描述"`	创建变更并生成 proposal、specs、design、tasks
`/opsx:apply [变更名]`	按 tasks.md 实现代码
`/opsx:explore`	探索当前变更与规范
`/opsx:archive [变更名]`	归档已完成变更

使用技巧：

在 /opsx:propose 后直接描述想法，AI 会推导变更名并生成完整工件
/opsx:apply 会按 tasks.md 逐项实现，适合分步推进
使用前需重启 Cursor，确保命令已加载

九、对话式触发（无需斜杠命令）

若项目配置了技能自动匹配（如 trae-skills-auto-apply），可通过自然对话触发工作流：

对话示例	自动匹配技能
新建变更、创建提案、开一个新功能、写个 proposal	openspec-propose
开始实现、按 tasks 实现、执行 tasks、继续实现	openspec-apply-change
归档变更、归档完成、变更完成	openspec-archive-change
看看当前变更、探索规范、有哪些变更	openspec-explore

当用户在 openspec/ 目录下时，会优先匹配 OpenSpec 相关技能。

十、与现有工程实践的关系

OpenSpec 不替代现有文档和规范，而是补充：

.cursorrules / .cursor/rules：通用编码规范、提交规范等，与 OpenSpec 并存
doc/：详细设计文档可作为 design.md 的参考来源
Git 工作流：每个变更可对应一个 feature 分支，归档后再合并

OpenSpec 侧重规范驱动流程，提供结构化的变更管理与 AI 协作工作流。

十一、最佳实践建议

先写 proposal 再写代码：避免「想到哪写到哪」，让 AI 有清晰上下文
善用 context：在 config.yaml 中写好技术栈和约束，减少 AI 猜测
任务粒度适中：tasks.md 中每个任务建议 1--2 小时可完成，便于分步实现
及时归档 ：变更完成后执行 openspec archive，保持 changes 目录清爽
与 Git 结合 ：变更名与分支名对应，如 feature/user-feedback-stats

十二、小结

OpenSpec 将「先规范后实现」的工程实践与 AI 编程助手结合，通过：

结构化工件：proposal → specs → design → tasks
CLI + IDE 集成：命令行创建变更，斜杠命令驱动 AI 实现
可追溯归档：变更从提案到完成全流程可查

适合希望提升 AI 协作效率、又需要可控流程的团队与个人。从 openspec init --tools cursor 开始，用 /opsx:propose "你的想法" 启动第一个变更吧。

相关链接

OpenSpec 官方仓库（如有）
Cursor 官网