OpenSpec 完整使用流程笔记 （SDD)

OpenSpec 完整使用流程笔记 （SDD)

OpenSpec 完整使用流程笔记 （SDD)📌 什么是 OpenSpec？ OpenSpec 是一个 AI 辅助开发 - 掘金
 

📌 什么是 OpenSpec？

OpenSpec 是一个 AI 辅助开发的结构化工作流工具。它通过一系列斜杠命令（/opsx:）引导开发者与 AI 协作，从需求探索、规划、编码到验证、归档，每一步都清晰可控，避免沟通偏差，提升开发效率和质量。

OpenSpec 的核心思想是  “先约定，后编码” ——在写代码前，先与 AI 共同明确需求、设计规范、拆解任务；代码实现后，再验证其是否符合约定，最后归档变更，形成可追溯的历史记录。

🚀 快速开始：安装与初始化

1. 安装 OpenSpec CLI

bash

 
css
代码解读
复制代码
npm install -g @fission-ai/openspec@latest

2. 在项目中初始化

进入你的项目根目录，执行：

bash

 
csharp
代码解读
复制代码
openspec init

这将创建必要的目录结构（如 openspec/、changes/ 等）和配置文件。

⚙️ 配置工作流：启用全部命令

OpenSpec 默认只启用核心命令（explore、apply、archive 等 4 个）。要使用完整功能（包括 new、continue、ff、verify、sync 等 11 个命令），需要切换配置文件。

步骤

  1. 切换 Profile

    bash

     
    arduino
    代码解读
    复制代码
    openspec config profile

    选择 Expanded Profile（完整工作流）。

  2. 手动选择 Workflows（可选）
    如果你只想启用部分命令，可以选择 Workflows only，然后用空格键勾选/取消具体命令。

  3. 刷新配置

    bash

     
    sql
    代码解读
    复制代码
    openspec update

  4. 重启 AI 编辑器（如 Cursor、VS Code + Copilot），使新的斜杠命令生效。

现在，你的 AI 编辑器中将出现所有 /opsx: 命令。

📚 核心概念

  • 变更（Change） ：一次独立的开发任务，对应一个需求或功能点。每个变更在 changes/ 下拥有一个独立目录（如 changes/20250311-add-login/）。
  • 工件（Artifact） ：变更过程中的产出物，包括提案（proposal）、规范（specs）、设计（design）、任务清单（tasks）、代码实现、验证报告等。
  • 规范（Specs） ：记录项目全局或模块的设计约定，存储在 openspec/specs/ 中，可被多个变更共享。
  • 快进（Fast-forward） ：一次性生成规划阶段的所有工件，跳过逐步创建的中间步骤。

🧭 分阶段流程详解

一个完整的 OpenSpec 工作流分为 探索 → 规划 → 执行 → 验证 → 同步 → 归档 六个阶段。

1. 探索阶段：/opsx:explore

在动手写代码前，与 AI 进行纯粹的讨论，分析需求、调研技术方案、梳理潜在风险。

  • 命令：/opsx:explore
  • 适用场景：需求模糊、技术选型不确定、需要头脑风暴。
  • 行为：AI 进入“只读模式”，不会创建任何文件，只生成讨论性回答。
  • 输出：通常是一段对话记录，可手动保存到项目文档中作为参考。

2. 规划阶段：从想法到任务清单

规划阶段的目标是产出清晰的 提案、规范、设计和任务清单，作为后续编码的依据。

2.1 启动新变更：/opsx:new

  • 命令：/opsx:new
  • 行为：在 changes/ 下创建一个以当前时间戳命名的新目录，并生成基础文件框架（如 proposal.md、tasks.md 等占位文件）。
  • 提示：需要你描述本次变更的目标（一句话或一段文字）。

2.2 逐步完善：/opsx:continue

如果你希望按顺序创建每个工件，可以使用 continue 命令逐个推进。

  • 命令：/opsx:continue
  • 行为：根据当前变更的进度，生成下一个缺失的工件。例如，已有 proposal.md，运行 continue 会生成 specs/ 目录和初步规范；再运行一次生成 design.md；再运行生成 tasks.md。
  • 优点：每一步你都可以审查、修改，确保方向正确。

2.3 快速完成规划：/opsx:ff（快进）

如果你对需求很明确，希望 AI 一次性生成所有规划工件，直接进入编码阶段，可以使用快进命令。

  • 命令：/opsx:ff
  • 行为：一次性生成 proposal.md、specs/（含规范）、design.md、tasks.md。
  • 适用场景：需求清晰、变更范围小、经验丰富的开发者。

规划阶段产出物

  • proposal.md：描述变更的背景、目标、验收标准。
  • specs/ ：存放与该变更相关的详细规范（接口设计、数据结构、UI 约定等）。
  • design.md：技术设计方案，包括模块划分、关键算法、依赖等。
  • tasks.md：拆解后的可执行任务清单（通常带复选框），供后续 apply 使用。

3. 执行阶段：/opsx:apply

当任务清单准备就绪后，就可以让 AI 根据任务列表编写代码。

  • 命令：/opsx:apply
  • 行为：AI 读取当前变更下的 tasks.md，逐个任务生成代码，并将代码文件放到项目中的正确位置。
  • 交互：每完成一个任务，AI 可能会请求确认或提供解释；你也可以中途打断，修改任务清单后继续。

4. 验证阶段：/opsx:verify

代码实现后，需要检查其是否完全符合当初制定的规范和设计。

  • 命令：/opsx:verify
  • 行为：AI 分析变更中的代码，对照 specs/ 和 design.md 进行一致性检查，生成一份 验证报告（通常在变更目录下生成 verify-report.md）。
  • 报告内容：指出符合项、不符合项、潜在问题、建议修复方案。
  • 后续：如果发现问题，可以手动修改代码或调整规范，然后再次运行 verify 直至通过。

5. 同步规范：/opsx:sync

在变更过程中，你可能会产生新的、可复用的规范（如一个通用的组件接口、API 设计模式）。这些规范应该合并到项目的主规范库中，供未来变更使用。

  • 命令：/opsx:sync
  • 行为：将当前变更中新增或修改的规范文件（位于 changes/<change>/specs/）复制或合并到项目根目录的 openspec/specs/ 中。
  • 注意：此命令不会归档变更，变更本身仍处于活跃状态，可继续开发。

6. 归档阶段：/opsx:archive 与 /opsx:bulk-archive

当变更所有工作（编码、验证）完成，并已同步规范后，就可以归档本次变更。

6.1 单个归档：/opsx:archive

  • 命令：/opsx:archive

  • 行为：

    • 将变更目录从 changes/active/ 移动到 changes/archived/（按日期组织）。
    • 再次运行 sync（确保最新规范已合并）。
    • 更新变更日志（CHANGELOG.md）。
    • 标记变更状态为“已完成”。

6.2 批量归档：/opsx:bulk-archive

当有多个已完成变更等待归档时，使用此命令批量处理。

  • 命令：/opsx:bulk-archive

  • 行为：

    • 列出所有可归档的活跃变更。
    • 让你选择要归档的变更（可多选）。
    • 依次执行归档操作，并自动检测规范冲突（如果两个变更修改了同一规范文件，会提示手动解决）。
    • 更新变更日志。

📋 命令速查表

命令 阶段 功能
/opsx:explore 探索 只读模式讨论需求，不生成文件
/opsx:new 规划 创建新变更目录及基础文件
/opsx:continue 规划 按进度生成下一个工件
/opsx:ff 规划 快进：一次性生成所有规划工件
/opsx:apply 执行 根据任务清单编写代码
/opsx:verify 验证 检查代码是否符合规范，生成报告
/opsx:sync 同步 将变更中的规范合并到主规范库
/opsx:archive 归档 归档单个已完成变更
/opsx:bulk-archive 归档 批量归档多个变更
/opsx:onboard 学习 交互式教程（约15分钟）

💡 最佳实践与典型场景

场景一：复杂功能开发（逐步推进）

  1. /opsx:explore – 与 AI 讨论需求、技术选型。
  2. /opsx:new – 创建变更。
  3. /opsx:continue – 生成 proposal，审阅后继续。
  4. /opsx:continue – 生成 specs，审阅后继续。
  5. /opsx:continue – 生成 design，审阅后继续。
  6. /opsx:continue – 生成 tasks，审阅后定稿。
  7. /opsx:apply – 执行任务清单，生成代码。
  8. /opsx:verify – 验证代码一致性，修复问题。
  9. /opsx:sync – 将新增规范合并到主库。
  10. /opsx:archive – 归档变更。

场景二：小型快速迭代

  1. /opsx:ff – 快进生成所有规划工件（需确保需求明确）。
  2. /opsx:apply – 编码。
  3. /opsx:verify – 验证。
  4. /opsx:archive – 归档。

场景三：规范先行，团队协作

  • 在项目启动时，先通过 /opsx:explore 和 /opsx:new 建立全局规范（如代码风格、API 设计原则），并存放在 openspec/specs/ 中。
  • 后续每个功能变更，都从主规范派生，开发完成后通过 /opsx:sync 更新主规范，确保团队知识库同步。

❓ 常见问题

Q1：命令在我的编辑器中不显示怎么办？

  • 确保已运行 openspec update。
  • 重启编辑器（Cursor / VS Code）。
  • 检查项目根目录下是否存在 .openspec/ 和 openspec/ 文件夹。
  • 确认你正在使用支持斜杠命令的 AI 工具（如 Cursor、Claude Code）。

Q2：/opsx:ff 和 /opsx:continue 有什么区别？

ff 是一次性生成所有规划工件，适合需求明确、变更简单时使用；continue 是逐个生成，适合需要逐步审阅、风险较高的变更。

Q3：如何查看当前变更的进度？

AI 会记录当前变更的状态，你也可以直接查看变更目录下的文件。例如，如果 tasks.md 已存在，说明规划阶段已完成。

Q4：sync 和 archive 都需要更新规范，有什么区别？

  • sync 只合并规范，变更本身仍活跃，可继续开发。
  • archive 在归档前会自动执行一次 sync，确保规范已被合并，然后归档变更。

🎯 总结

OpenSpec 通过结构化的命令和工作流，将 AI 从“代码生成器”转变为“遵循规范的协作者”。掌握这些命令，你就能：

  • 在探索阶段利用 AI 进行深度分析。
  • 在规划阶段与 AI 共同构建清晰的设计蓝图。
  • 在执行阶段让 AI 按任务清单精准编码。
  • 在验证阶段自动检查一致性，避免返工。
  • 在归档阶段沉淀规范，积累团队资产。

开始使用 OpenSpec，让 AI 辅助开发变得更加可控、高效！

 

AI开发范式---OpenSpec 新手入门教程

什么是OpenSpec？

OpenSpec 是一个为AI编码助手设计的规范驱动开发工具，它通过轻量级的工作流程，确保人类开发者和AI助手在编写任何代码之前就能对需求达成明确共识。

核心特点

  • 🚀 轻量级：无需API密钥，最小化设置
  • 🔄 现有项目优先：特别适合修改现有功能 (1→n)
  • 📋 变更跟踪：提案、任务和规范差异的完整生命周期管理
  • 🤖 AI工具集成：支持多种主流AI编码助手

为什么需要OpenSpec？

传统AI编码助手的问题

当您使用AI编码助手时，是否遇到过以下情况：

  • ❌ AI根据模糊提示生成不符合需求的代码
  • ❌ 遗漏重要功能要求
  • ❌ 添加了不必要的功能
  • ❌ 代码行为不可预测

OpenSpec的解决方案

OpenSpec通过规范驱动开发解决这些问题：

✅ 明确共识：在编码前确定所有要求
✅ 结构化变更：所有相关文档集中管理
✅ 可审查输出：AI根据明确规范生成代码
✅ 版本控制：完整追踪所有变更历史

准备工作

系统要求

  • Node.js >= 20.19.0
  • 支持的AI编码助手（见支持的AI工具）

检查Node.js版本

node --version

如果版本不符合要求，请访问 Node.js官网 更新。

快速开始

第一步：安装OpenSpec CLI

npm install -g @fission-ai/openspec@latest

验证安装

openspec --version

第二步：在项目中初始化OpenSpec

cd your-project-directory
openspec init

初始化过程会：

  1. 询问您使用的AI工具（Claude Code、Cursor等）
  2. 自动配置相应的斜杠命令
  3. 创建 openspec/ 目录结构
  4. 生成 AGENTS.md 文件

第三步：验证设置

openspec list

如果您的AI助手没有立即显示新的斜杠命令，请重启它。

核心概念

1. 双文件夹模型

OpenSpec使用两个主要目录：

openspec/
├── specs/          # 当前真理源规范
│   └── auth/
│       └── spec.md
├── changes/        # 变更提案
│   └── feature-name/
│       ├── proposal.md
│       ├── tasks.md
│       └── specs/
└── project.md      # 项目级别约定

2. 规范格式

规范使用Markdown格式，包含：

# Auth Specification
## Purpose
Authentication and session management.
## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT on successful login.
#### Scenario: Valid credentials
- WHEN a user submits valid credentials
- THEN a JWT is returned

3. 变更差异

变更通过"差异"格式显示：

# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.
#### Scenario: OTP required
- WHEN a user submits valid credentials
- THEN an OTP challenge is required

完整工作流程

OpenSpec遵循四步工作流程：

1️⃣ 起草变更提案

# 使用AI助手或直接创建
/openspec:proposal Add profile search filters

AI会自动创建：

  • openspec/changes/feature-name/proposal.md - 变更说明
  • openspec/changes/feature-name/tasks.md - 实施任务
  • openspec/changes/feature-name/specs/ - 规范差异

2️⃣ 审查与对齐

# 查看变更详情
openspec show feature-name

# 验证规范格式
openspec validate feature-name

与AI助手讨论，直到所有人同意：

您：能否为角色和团队过滤器添加验收标准？
AI：我来更新规范差异，添加角色和团队过滤器的场景。
[编辑相应文件]

3️⃣ 实施任务

# 开始实施
/openspec:apply feature-name

AI会按照 tasks.md 中的清单逐步实施，每完成一个任务会标记为 ✓。

4️⃣ 归档与更新规范

# 归档完成的变更
openspec archive feature-name --yes

归档会将批准的变更合并回 openspec/specs/ 中，并移动到 archive/ 目录。

实际示例

让我们通过一个完整的示例来理解整个流程：

示例：添加用户资料搜索过滤功能

步骤1：创建变更提案

您：请为添加按角色和团队过滤的用户资料搜索创建一个OpenSpec变更提案
[或使用快捷命令：/openspec:proposal Add profile search filters]

AI响应：

AI：我来为您创建用户资料过滤器的OpenSpec变更提案。
*创建 openspec/changes/add-profile-filters/ 目录，包含 proposal.md、tasks.md 和规范差异文件*

步骤2：验证和审查

# 确认变更文件夹存在
openspec list

# 验证规范格式
openspec validate add-profile-filters

# 审查提案、任务和规范差异
openspec show add-profile-filters

步骤3：完善规范

您：能否为角色和团队过滤器添加验收标准？

AI更新相应的规范差异和任务列表。

步骤4：实施变更

您：规范看起来很好，让我们实施这个变更吧。
[或使用：/openspec:apply add-profile-filters]

AI按任务清单逐步实施，并标记完成状态。

步骤5：归档

您：请归档这个变更
[或使用：/openspec:archive add-profile-filters]

支持的AI工具

原生斜杠命令支持

AGENTS.md兼容工具

  • Amp
  • Jules
  • Gemini CLI
  • 其他兼容AGENTS.md的工具

常用命令

查看和管理变更

openspec list                    # 查看所有活动变更
openspec view                    # 交互式规范仪表板
openspec show <change-name>      # 显示变更详情
openspec validate <change-name>  # 验证规范格式

归档变更

openspec archive <change-name>   # 交互式归档
openspec archive <change-name> --yes  # 非交互式归档

工具管理

openspec update                  # 刷新AI指导，重新生成斜杠命令

团队采用指南

1. 初始化团队项目

# 在团队仓库中运行
openspec init

2. 从新功能开始

要求团队成员将即将到来的工作作为变更提案与AI助手讨论。

3. 增量式发展

每个完成的变更都会归档到记录您系统的实时规范中。

4. 保持工具灵活性

不同团队成员可以使用Claude Code、Cursor或任何AGENTS.md兼容工具，同时共享相同的规范。

5. 工具切换

当有人切换到不同AI工具时，运行：

openspec update

项目上下文设置（可选但推荐）

初始化后，建议完善项目上下文：

使用示例提示

请阅读 openspec/project.md，并帮助我填写关于我的项目、技术栈和约定的详细信息。

project.md 内容示例

# Project Context

## Tech Stack
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL
- Styling: Tailwind CSS

## Code Conventions
- 使用 TypeScript 严格模式
- 组件名使用 PascalCase
- 函数名使用 camelCase
- 常量使用 UPPER_SNAKE_CASE

## Architecture Patterns
- 采用组件化设计
- 前后端分离
- RESTful API 设计
- 响应式设计原则

规范文件理解

Delta格式

差异文件显示规范如何变化：

## ADDED Requirements          # 新功能
## MODIFIED Requirements       # 行为变更（包含完整更新文本）
## REMOVED Requirements        # 已废弃功能

格式要求

  • 使用 ### Requirement: 作为标题
  • 每个要求至少需要一个 #### Scenario: 块
  • 在要求文本中使用 SHALL/MUST

升级和维护

升级OpenSpec

npm install -g @fission-ai/openspec@latest

刷新AI指导

# 在每个项目中运行
openspec update

常见问题

Q1: AI助手没有显示新的斜杠命令怎么办？

A: 重启您的AI编码助手，然后运行 openspec update 刷新指导。

Q2: 可以同时处理多个变更吗？

A: 是的，OpenSpec支持同时存在多个变更提案，但一次只能应用一个。

Q3: 如何修改已归档的规范？

A: 创建一个新的变更提案，通过相同的流程来更新现有规范。

Q4: OpenSpec适用于绿地项目吗？

A: OpenSpec特别适合修改现有功能，但也可用于新项目。通常建议从简单功能开始。

Q5: 团队成员使用不同AI工具可以吗？

A: 可以！OpenSpec的AGENTS.md兼容性确保所有AI工具都能理解相同的规范。

与其他工具对比

vs. 没有规范

  • 传统方式：AI根据模糊提示生成代码，常常遗漏要求或添加不必要功能
  • OpenSpec：通过明确规范带来可预测性

vs. spec-kit

  • spec-kit：适合0→1新功能项目
  • OpenSpec：在修改现有行为和跨多规范更新时表现更优

vs. Kiro

  • Kiro：将更新分散到多个规范文件夹
  • OpenSpec：将相关变更分组在一个文件夹中，便于跟踪

社区和支持

总结

OpenSpec通过轻量级但结构化的规范驱动开发方法，成功解决了AI编码助手的不可预测性问题。无论您是个人开发者还是团队协作，OpenSpec都能帮助您：

✅ 提高开发效率：减少因需求不明确导致的返工
✅ 确保代码质量：AI根据明确规范生成可预测的代码
✅ 改善团队协作：所有人共享相同的规范理解
✅ 简化变更管理：结构化的变更追踪和归档

 

 AI开发范式---OpenSpec 新手入门教程 - 知乎

posted @ 2026-09-28 13:47  charyGao  阅读(62)  评论(0)    收藏  举报