第一部分概述

OpenSpec 是一个专为 AI 编程助手设计的规范驱动开发（Spec-Driven Development，SDD）框架。它通过在代码编写之前建立轻量级的规范层，让开发者和 AI 助手在"要构建什么"上达成共识，从而减少模糊提示带来的不可预测结果。本文梳理了 OpenSpec 的核心理念、工作流程、命令体系以及定制化能力。从其"流动而非僵化"的设计哲学出发，逐步解析了规范、变更、工件等核心概念的工作原理，并通过实际示例展示了从提案到归档的完整开发周期。读完本文，你将理解如何利用 OpenSpec 让 AI 编程助手更可靠地执行开发任务，并能在自己的项目中灵活运用这套方法论。

第二部分核心理念与设计哲学

2.1 四大设计原则

OpenSpec 的设计围绕四个核心原则展开，这些原则决定了框架的每一个细节。

流动而非僵化。传统的规范系统将开发过程锁定在固定的阶段：先规划，再实现，然后结束。OpenSpec 打破了这种束缚——你可以按照任何合理的顺序创建工件，没有强制的阶段门槛。

迭代而非瀑布。需求会变化，理解会加深。项目开始时看似合理的方案，在深入了解代码库后可能不再适用。OpenSpec 拥抱这一现实，允许在实现过程中随时回溯和调整。

简单而非复杂。有些规范框架需要大量设置、僵化的格式或繁琐的流程。OpenSpec 选择轻量化路线：几秒钟完成初始化，立即开始工作，仅在需要时才进行定制。

存量优先而非仅限新建。大多数软件开发工作并非从零开始，而是修改现有系统。OpenSpec 的增量规范（Delta Spec）方法让描述对现有行为的修改变得自然，而非只能描述全新系统。

2.2 为什么需要规范层

AI 编程助手功能强大，但当需求仅存在于聊天历史中时，其行为往往不可预测。一个模糊的"添加深色模式"请求可能产生完全不同的实现结果——取决于 AI 如何理解"深色模式"的具体含义、范围边界和技术方案。

OpenSpec 通过引入规范层解决这个问题。规范层的作用是让开发者和 AI 在编写任何代码之前，先就"要构建什么"达成明确共识。这不是要回归瀑布模型的繁重文档，而是用最轻量的方式记录意图、范围和方案，让 AI 的执行有据可依。

第三部分核心概念解析

3.1 规范（Specs）：系统行为的真实来源

规范目录 openspec/specs/ 是系统的真实来源，描述系统当前的行为方式。规范按领域组织，每个领域包含一个规范文件。


openspec/specs/
├── auth/
│   └── spec.md           # 认证行为
├── payments/
│   └── spec.md           # 支付处理
├── notifications/
│   └── spec.md           # 通知系统
└── ui/
    └── spec.md           # UI 行为和主题

规范文件采用结构化格式，包含需求（Requirements）和场景（Scenarios）。需求描述系统必须具备的行为，场景提供可验证的具体示例。

markdown
### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.

#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard

规范使用 RFC 2119 关键词（SHALL、MUST、SHOULD、MAY）表达需求强度。SHALL/MUST 表示绝对要求，SHOULD 表示推荐但允许例外，MAY 表示可选。

规范的本质

规范是行为契约，而非实现计划。好的规范描述外部可观察的行为——用户或下游系统依赖的输入、输出和错误条件。避免在规范中包含内部类名、框架选择或实现细节，这些内容属于设计文档。

3.2 变更（Changes）：提议修改的独立单元

变更是对系统的提议修改，以文件夹形式打包，包含理解和实现该修改所需的一切。


openspec/changes/add-dark-mode/
├── proposal.md           # 为什么做、做什么
├── design.md             # 技术方案
├── tasks.md              # 实现清单
├── .openspec.yaml        # 变更元数据
└── specs/                # 增量规范
    └── ui/
        └── spec.md       # UI 规范的变更内容

将变更打包为文件夹有几个好处：所有相关内容集中一处；多个变更可以并行进行而不冲突；归档后完整保留上下文形成审计历史；变更文件夹易于审查。

3.3 工件（Artifacts）：引导工作的文档

工件是变更文件夹内引导工作的文档，按依赖关系形成流程。


proposal ──► specs ──► design ──► tasks ──► implement
   │           │          │                    │
   └───────────┴──────────┴────────────────────┘
            随着理解加深随时更新

提案（proposal.md） 捕捉意图、范围和高层方案。它回答"为什么做"和"做什么"。

增量规范（specs/） 描述相对于当前规范的变更内容，使用 ADDED/MODIFIED/REMOVED 标记。

设计（design.md） 记录技术方案和架构决策，回答"怎么做"。

任务（tasks.md） 是实现清单，用复选框追踪进度。

3.4 增量规范（Delta Specs）：存量开发的关键

增量规范是 OpenSpec 适配存量开发的核心概念。它描述"什么在变化"，而非重述整个规范。

markdown
# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.

## MODIFIED Requirements

### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

归档时，ADDED 需求追加到主规范，MODIFIED 需求替换现有版本，REMOVED 需求从主规范删除。这种增量方式让修改现有行为变得自然，而非只能描述新系统。

第四部分工作流程详解

4.1 两种模式：快速路径与扩展路径

OpenSpec 提供两种工作模式，适应不同的开发场景。

核心模式（core profile） 是默认配置，提供最精简的命令集：


/opsx:propose ──► /opsx:apply ──► /opsx:archive

适合大多数开发场景，快速完成从提案到归档的完整周期。

扩展模式 提供更细粒度的控制，需要通过配置启用：


/opsx:new ──► /opsx:ff 或 /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

适合需要逐步审查工件、验证实现或处理复杂变更的场景。

4.2 快速功能开发流程

当需求明确、准备直接执行时，使用快速功能流程。


/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

/opsx:new 创建变更文件夹骨架。/opsx:ff（fast-forward）一次性创建所有规划工件。/opsx:apply 执行任务清单。/opsx:verify 验证实现与工件的一致性。/opsx:archive 归档变更并合并增量规范。

适用场景

适合中小型功能、缺陷修复、范围明确的变更。当你能 upfront 描述完整范围时，使用 /opsx:ff；边探索边确定时，使用 /opsx:continue。

4.3 探索式开发流程

当需求不清晰或需要先调查问题时，使用探索式流程。


/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

/opsx:explore 开启探索性对话，不创建任何工件。AI 助手会调查代码库、比较方案、创建可视化图表来澄清思路。当洞察成形后，可以过渡到 /opsx:new 开始正式变更。

这种流程适合性能优化、调试、架构决策、需求模糊的场景。探索阶段不产生工件，专注于理解问题空间。

4.4 并行变更处理

OpenSpec 支持同时处理多个变更，适合并行工作流或紧急中断场景。


变更 A: /opsx:new ──► /opsx:ff ──► /opsx:apply (进行中)
                                        │
                                   上下文切换
                                        │
变更 B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

当有多个完成的变更时，使用 /opsx:bulk-archive 批量归档。批量归档会检测规范冲突，通过检查实际实现来智能解决。

4.5 完整示例：添加深色模式

以添加深色模式为例，演示完整工作流程。

第一步：启动变更


You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

第二步：审查生成的工件

提案文件捕捉意图和范围：

markdown
# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

增量规范定义新需求：

markdown
## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

任务清单提供实现步骤：

markdown
## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

第三步：实现


You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     All tasks complete!

第四步：归档


You: /opsx:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

归档后，增量规范合并到主规范，变更文件夹移至归档目录保留完整历史。

第五部分命令体系

5.1 斜杠命令一览

OpenSpec 的斜杠命令在 AI 编程助手的聊天界面中调用。

命令	用途
`/opsx:propose`	创建变更并生成规划工件（核心模式默认）
`/opsx:explore`	探索想法、调查问题
`/opsx:new`	创建变更骨架（扩展模式）
`/opsx:continue`	创建下一个工件（扩展模式）
`/opsx:ff`	快进创建所有规划工件
`/opsx:apply`	实现任务清单
`/opsx:verify`	验证实现与工件一致性
`/opsx:sync`	合并增量规范到主规范
`/opsx:archive`	归档完成的变更
`/opsx:bulk-archive`	批量归档多个变更
`/opsx:onboard`	交互式教程

5.2 验证命令详解

/opsx:verify 从三个维度验证实现质量。

完整性：检查所有任务是否完成、所有需求是否实现、场景是否覆盖。

正确性：检查实现是否匹配规范意图、边缘情况是否处理、错误状态是否匹配定义。

一致性：检查设计决策是否反映在代码中、命名约定是否与设计一致。

验证不会阻止归档，但会提示需要关注的问题。

5.3 CLI 命令参考

OpenSpec CLI 提供终端命令用于项目设置、验证和状态检查。

类别	命令	用途
设置	`init`, `update`	初始化和更新项目
浏览	`list`, `view`, `show`	探索变更和规范
验证	`validate`	检查变更和规范问题
生命周期	`archive`	归档完成的变更
工作流	`status`, `instructions`, `templates`, `schemas`	工件驱动工作流支持
模式	`schema init`, `schema fork`, `schema validate`	创建和管理自定义模式
配置	`config`	查看和修改设置

CLI 命令支持 --json 输出供 AI 助手和脚本程序化使用。

第六部分工具集成与定制化

6.1 支持的 AI 编程工具

OpenSpec 支持 25+ AI 编程助手，包括 Claude Code、Cursor、Windsurf、GitHub Copilot、Gemini CLI 等。

初始化时，OpenSpec 为选中的工具安装技能文件和命令文件。技能文件位于工具特定的 skills/ 目录，命令文件位于工具的命令目录。

bash
# 配置特定工具
openspec init --tools claude,cursor

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

不同工具的命令语法略有差异。Claude Code 使用 /opsx:propose，Cursor 和 Windsurf 使用 /opsx-propose。意图相同，只是呈现方式因集成方式而异。

6.2 项目配置

openspec/config.yaml 是定制 OpenSpec 的最简单方式。

yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format

配置中的 context 会注入到所有工件的生成提示中，rules 仅注入到匹配的工件。这让 AI 助手生成符合项目约定的工件。

6.3 自定义模式（Schema）

当项目配置不够时，可以创建完全自定义的工作流模式。

bash
# 从现有模式派生
openspec schema fork spec-driven my-workflow

# 从零创建
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks"

模式定义工件类型及其依赖关系：

yaml
artifacts:
  - id: proposal
    generates: proposal.md
    requires: []

  - id: tasks
    generates: tasks.md
    requires: [proposal]

自定义模式存放在项目的 openspec/schemas/ 目录，随代码一起版本控制。

6.4 多语言支持

OpenSpec 支持生成非英语工件。在配置中添加语言指令：

yaml
context: |
  语言：中文（简体）
  所有产出物必须用简体中文撰写。
  技术术语如 API、REST、GraphQL 保持英文。

所有生成的工件将使用指定语言。

第七部分最佳实践与常见问题

7.1 保持变更聚焦

每个变更应该是一个逻辑工作单元。如果你在做"添加功能 X 并重构 Y"，考虑拆分为两个独立变更。

聚焦的变更更易审查和理解，归档历史更清晰，可以独立交付，回滚更简单。

7.2 命名变更清晰

好的变更名称让 openspec list 输出有意义：


推荐：add-dark-mode, fix-login-redirect, optimize-product-query
避免：feature-1, update, changes, wip

7.3 验证后再归档

使用 /opsx:verify 检查实现与工件的一致性，在归档前捕获不匹配问题。

7.4 更新还是新建变更

当需要调整时，何时更新现有变更，何时新建？

更新现有变更：意图相同、执行方式调整；范围缩小（先 MVP，其余后续）；基于实现发现的修正。

新建变更：意图根本改变；范围扩展到完全不同的工作；原变更可以独立标记完成。

7.5 常见问题处理

变更未找到：明确指定变更名称 /opsx:apply add-dark-mode，或检查变更文件夹是否存在。

无工件就绪：运行 openspec status --change <name> 查看阻塞原因，创建缺失的依赖工件。

命令未识别：确保已初始化 openspec init，重新生成技能 openspec update，重启 AI 工具。

第八部分总结

OpenSpec 为 AI 编程助手引入了规范驱动开发的方法论，通过轻量级的规范层让开发者和 AI 在编写代码前达成共识。其核心价值在于：增量规范适配存量开发，工件流程提供结构化引导，并行变更支持复杂工作流，归档机制保留完整历史。

框架的设计哲学——流动而非僵化、迭代而非瀑布、简单而非复杂——使其能够融入实际开发流程，而非强加繁重的文档负担。无论是快速功能开发还是探索式问题解决，OpenSpec 都提供了适配的工作模式。

对于正在使用 AI 编程助手的开发者，OpenSpec 提供了一种让 AI 执行更可靠、结果更可预测的实践路径。从安装初始化到第一个变更的完整周期，只需几分钟即可体验其核心价值。

参考资料：