OpenSpec入门指南：轻量级规格驱动开发框架

简介

OpenSpec 是一个轻量级的规格驱动开发（Spec-Driven Development, SDD）框架，专为 AI 编码助手设计。

项目数据：42K+ GitHub Stars | 60+ Contributors | MIT 开源 | TypeScript

为什么需要 OpenSpec？

AI 编码助手很强大，但当需求只存在于聊天历史中时，它们就变得不可预测。OpenSpec 添加了一个轻量级的规格层，让你在编写任何代码之前就与 AI 达成一致。

核心问题：

AI 输出与你期望不符
需求模糊导致实现模糊
聊天历史中的上下文丢失
团队协作时意图传递困难

OpenSpec 的解决方案：

先同意再构建 — 人类和 AI 在编写代码之前对齐规格
保持组织 — 每个变更都有自己的文件夹，包含提案、规格、设计和任务
流畅工作 — 随时更新任何产物，没有刚性阶段门槛
使用你的工具 — 通过斜杠命令支持 25+ AI 助手

核心理念

→ fluid not rigid        （流畅而非僵化）
→ iterative not waterfall（迭代而非瀑布）
→ easy not complex       （简单而非复杂）
→ built for brownfield not just greenfield（为棕地构建，而非仅绿地）

为什么这些理念很重要

流畅而非僵化：传统规格系统将你锁定在阶段中：先计划，再实现，然后完成。OpenSpec 更灵活 — 你可以按任何合理的顺序创建产物。

迭代而非瀑布：需求会变化，理解会加深。开始时看似好的方法在看到代码库后可能站不住脚。OpenSpec 拥抱这一现实。

简单而非复杂：一些规格框架需要大量设置、僵化格式或重量级流程。OpenSpec 不妨碍你。几秒钟初始化，立即开始工作。

棕地优先：大多数软件工作不是从零构建 — 而是修改现有系统。OpenSpec 的增量方法使指定对现有行为的修改变得容易。

快速入门 (5分钟)

系统要求

Node.js 20.19.0 或更高版本
支持的 AI 编码助手

安装

# 全局安装（推荐）
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version

初始化项目

# 进入项目目录
cd your-project

# 初始化 OpenSpec
openspec init

开始使用

告诉你的 AI：

1	/opsx:propose "your idea"

启用扩展工作流

如果需要扩展工作流命令（/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:sync、/opsx:bulk-archive、/opsx:onboard）：

# 配置工作流配置文件
openspec config profile

# 应用更新
openspec update

核心概念

大局观

OpenSpec 将你的工作组织成两个主要区域：

┌─────────────────────────────────────────────────────────────────┐
│ openspec/                                                       │
│                                                                 │
│ ┌─────────────────────┐   ┌──────────────────────────────┐     │
│ │ specs/              │   │ changes/                     │     │
│ │                     │   │                              │     │
│ │ Source of truth     │◄──│ Proposed modifications       │     │
│ │ How your system     │   │ Each change = one folder     │     │
│ │ currently works     │   │ Contains artifacts + deltas  │     │
│ │                     │   │                              │     │
│ └─────────────────────┘   └──────────────────────────────┘     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Specs（规格） 是真实来源 — 它们描述系统当前的行为。

Changes（变更） 是建议的修改 — 它们存在于单独的文件夹中，直到你准备好合并它们。

Specs（规格）

规格使用结构化的需求和场景描述系统的行为。

结构

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

按领域组织规格 — 对系统有意义的逻辑分组。常见模式：

按功能区域：auth/、payments/、search/
按组件：api/、frontend/、workers/
按限界上下文：ordering/、fulfillment/、inventory/

规格格式

# Auth Specification

## Purpose
Authentication and session management for the application.

## Requirements

### 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

#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued

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

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
- AND the user must re-authenticate

关键元素

元素	用途
`## Purpose`	此规格领域的高级描述
`### Requirement:`	系统必须具有的特定行为
`#### Scenario:`	需求的具体示例
SHALL/MUST/SHOULD	RFC 2119 关键字，指示需求强度

RFC 2119 关键字

MUST/SHALL — 绝对要求
SHOULD — 推荐，但存在例外
MAY — 可选

Changes（变更）

变更是对系统的建议修改，打包为一个文件夹，包含理解和实现它所需的一切。

变更结构

openspec/changes/add-dark-mode/
├── proposal.md           # 为什么和做什么
├── design.md             # 怎么做（技术方法）
├── tasks.md              # 实现检查清单
├── .openspec.yaml        # 变更元数据（可选）
└── specs/                # 增量规格
    └── ui/
        └── spec.md       # ui/spec.md 中的变化

每个变更都是自包含的。它包含：

Artifacts（产物） — 捕获意图、设计和任务的文档
Delta specs（增量规格） — 正在添加、修改或删除的规格
Metadata（元数据） — 此特定变更的可选配置

为什么变更是文件夹

一切在一起 — 提案、设计、任务和规格在一个地方
并行工作 — 多个变更可以同时存在而不冲突
清晰历史 — 归档时，变更移动到 changes/archive/，保留完整上下文
易于审查 — 变更文件夹易于审查

Artifacts（产物）

产物是变更中指导工作的文档。

产物流程

proposal ──────► specs ──────► design ──────► tasks ──────► implement
    │               │             │              │
   why            what           how          steps
 + scope        changes       approach      to take

产物相互构建。每个产物为下一个提供上下文。

Proposal（提案）

提案在高级别捕获意图、范围和方法。

# Proposal: Add Dark Mode

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

## Scope
In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage

Out of scope:
- Custom color themes (future work)
- Per-page theme overrides

## Approach
Use CSS custom properties for theming with a React context
for state management. Detect system preference on first load,
allow manual override.

Design（设计）

设计捕获技术方法和架构决策。

# Design: Add Dark Mode

## Technical Approach
Theme state managed via React Context to avoid prop drilling.
CSS custom properties enable runtime switching without class toggling.

## Architecture Decisions

### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency

### Decision: CSS Custom Properties
Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution

## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)

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
- [ ] 1.4 Add system preference detection

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables
- [ ] 3.3 Test contrast ratios for accessibility

Delta Specs（增量规格）

增量规格是使 OpenSpec 适用于棕地开发的关键概念。它们描述正在变化的内容，而不是重述整个规格。

格式

# Delta for Auth

## ADDED Requirements

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

#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation

## 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. Users should re-authenticate each session.)

增量部分

部分	含义	归档时发生什么
`## ADDED Requirements`	新行为	追加到主规格
`## MODIFIED Requirements`	更改的行为	替换现有需求
`## REMOVED Requirements`	弃用的行为	从主规格删除

为什么用增量而非完整规格

清晰：增量准确显示正在变化的内容。

避免冲突：两个变更可以触及同一规格文件而不冲突，只要它们修改不同的需求。

审查效率：审查者看到变更，而非未更改的上下文。

棕地适配：大多数工作修改现有行为。增量使修改成为一等公民。

OPSX 工作流

OPSX 是 OpenSpec 的标准工作流。它是一个流畅、迭代的工作流，没有刚性阶段 — 只有你可以随时采取的操作。

Core 工作流（默认）

命令	作用
`/opsx:propose`	一步创建变更并生成规划产物（默认快速路径）
`/opsx:explore`	思考想法、调查问题、澄清需求
`/opsx:apply`	实现任务，根据需要更新产物
`/opsx:archive`	完成后归档

Expanded 工作流

命令	作用
`/opsx:new`	启动新的变更脚手架
`/opsx:continue`	创建下一个产物
`/opsx:ff`	快进规划产物
`/opsx:verify`	根据产物验证实现
`/opsx:sync`	将增量规格同步到主规格（可选）
`/opsx:bulk-archive`	批量归档多个已完成的变更
`/opsx:onboard`	端到端变更的引导式演练

工作流对比

方面	Legacy (`/openspec:proposal`)	OPSX (`/opsx:*`)
结构	一个大提案文档	具有依赖关系的离散产物
工作流	线性阶段：plan → implement → archive	流畅操作 — 随时做任何事
迭代	回退很尴尬	随着学习更新产物
定制	固定结构	模式驱动（定义自己的产物）

实战示例

示例：添加暗色模式

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!

You: /opsx:apply
AI:  Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     ✓ 2.2 Wire up localStorage
     All tasks complete!

You: /opsx:archive
AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

示例：添加”记住我”功能

You: /opsx:propose Add remember me checkbox with 30-day sessions

AI:  Searching existing specs for authentication requirements...
     Read(openspec/specs/auth-session/spec.md)
     Searching existing codebase for session handling...
     Read(src/auth/session.ts)
     Creating proposal and breaking down implementation tasks...
     
     Created change proposal with ID add-remember-me
     
     openspec/changes/add-remember-me/
     ├── proposal.md ← describe the change
     ├── design.md ← technical decisions
     ├── tasks.md ← implementation tasks
     └── specs/ ← spec deltas
         └── auth-session/
             └── spec.md
     
     This change affects 1 spec, with 3 phases and 8 tasks

CLI 命令参考

命令分类

类别	命令	用途
设置	`init`, `update`	初始化和更新项目中的 OpenSpec
浏览	`list`, `view`, `show`	探索变更和规格
验证	`validate`	检查变更和规格的问题
生命周期	`archive`	完成已完成的变更
工作流	`status`, `instructions`, `templates`, `schemas`	产物驱动工作流支持
模式	`schema init`, `schema fork`, `schema validate`, `schema which`	创建和管理自定义工作流
配置	`config`	查看和修改设置
实用	`feedback`, `completion`	反馈和 shell 集成

常用命令

# 初始化项目
openspec init

# 更新代理指令
openspec update

# 列出变更和规格
openspec list

# 查看特定项目
openspec show <item>

# 验证
openspec validate

# 查看状态
openspec status

# 获取下一步指令
openspec instructions

# 配置
openspec config profile

JSON 输出（用于代理/脚本）

命令	人类使用	代理使用
`openspec list`	浏览变更/规格	`--json` 获取结构化数据
`openspec show <item>`	读取内容	`--json` 用于解析
`openspec validate`	检查问题	`--all --json` 批量验证
`openspec status`	查看产物进度	`--json` 获取结构化状态
`openspec instructions`	获取下一步	`--json` 获取代理指令

支持的 AI 工具

OpenSpec 支持 25+ AI 编码助手：

原生支持

工具	状态
Claude Code	✅ 原生支持
Cursor	✅ 原生支持
Codex	✅ 原生支持
GitHub Copilot	✅ 原生支持
OpenCode	✅ 原生支持
Windsurf	✅ 原生支持
Gemini CLI	✅ 原生支持
Antigravity	✅ 原生支持
Cline	✅ 原生支持
RooCode	✅ 原生支持
Kilo Code	✅ 原生支持
Amazon Q	✅ 原生支持
Qoder	✅ 原生支持
Auggie CLI	✅ 原生支持
Qwen Code	✅ 原生支持
CodeBuddy	✅ 原生支持

与竞品对比

vs. Spec Kit (GitHub)

方面	Spec Kit	OpenSpec
风格	彻底但重量级	轻量级
阶段	刚性阶段门槛	流畅，无阶段门槛
设置	Python 设置	Node.js，秒级初始化
迭代	较难回退	自由迭代

结论：OpenSpec 更轻量，让你自由迭代。

vs. Kiro (AWS)

方面	Kiro	OpenSpec
IDE	锁定他们的 IDE	使用你已有的工具
模型	仅限 Claude 模型	支持多种模型
灵活性	受限	高度灵活

结论：OpenSpec 与你已有的工具配合使用。

vs. 无规格开发

方面	无规格	OpenSpec
提示	模糊提示	结构化规格
结果	不可预测	可预测
上下文	聊天历史中丢失	持久化在代码库中

结论：OpenSpec 带来可预测性，无需繁文缛节。

高级功能

Schemas（模式）

模式定义工作流的产物类型及其依赖关系。

内置模式

spec-driven（默认）

标准规格驱动开发工作流：

1	proposal → specs → design → tasks → implement

最适合：大多数功能工作，你想在实现之前对齐规格。

自定义模式

# 从头创建
openspec schema init research-first

# 或分叉现有模式
openspec schema fork spec-driven research-first

示例自定义模式：

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []           # 先做研究

  - id: proposal
    generates: proposal.md
    requires: [research]   # 提案由研究支撑

  - id: tasks
    generates: tasks.md
    requires: [proposal]   # 跳过规格/设计，直接到任务

Archive（归档）

归档通过将增量规格合并到主规格并保留变更历史来完成变更。

归档过程

合并增量 — 每个增量规格部分（ADDED/MODIFIED/REMOVED）应用到相应的主规格
移动到归档 — 变更文件夹移动到 changes/archive/，带日期前缀
保留上下文 — 所有产物在归档中保持完整

归档前后

Before archive:

openspec/
├── specs/
│   └── auth/
│       └── spec.md ◄────────────────┐
└── changes/                         │
    └── add-2fa/                     │
        ├── proposal.md              │
        ├── design.md                │ merge
        ├── tasks.md                 │
        └── specs/                   │
            └── auth/                │
                └── spec.md ─────────┘

After archive:

openspec/
├── specs/
│   └── auth/
│       └── spec.md        # 现在包含 2FA 需求
└── changes/
    └── archive/
        └── 2025-01-24-add-2fa/    # 保留历史
            ├── proposal.md
            ├── design.md
            ├── tasks.md
            └── specs/
                └── auth/
                    └── spec.md

使用建议

模型选择

OpenSpec 最适合高推理模型。推荐：

Opus 4.5 — 规划和实现
GPT 5.2 — 规划和实现

上下文卫生

OpenSpec 受益于干净的上下文窗口：

在开始实现之前清除上下文
在整个会话中保持良好的上下文卫生

渐进式严谨

OpenSpec 旨在避免官僚主义。使用最轻的级别：

Lite 规格（默认）：

简短的行为优先需求
清晰的范围和非目标
几个具体的验收检查

Full 规格（高风险）：

跨团队或跨仓库变更
API/契约变更、迁移、安全/隐私问题
歧义可能导致昂贵返工的变更

大多数变更应保持 Lite 模式。

常见问题

Q: OpenSpec 与代理内置的计划模式有什么不同？

计划模式对单个聊天会话很好。我们关注跨越多个会话的计划，或你想与他人分享的计划。功能规划的工作空间让你更好地规划并随着进展进行优化。

Q: OpenSpec 与其他规划工具的区别？

轻量级 — 最少步骤，最少流程
棕地优先 — 关注成熟代码库
规格存在于代码中 — 其他工具只在规划期间使用需求，然后丢弃

Q: 为什么用规格而不是写详细提示？

规格作为对齐。一种在编写任何代码之前在单一空间中构建思维的方式。更清楚地了解你正在构建什么，代理在执行计划时有更好的上下文。

Q: 可以在现有代码库上使用 OpenSpec 吗？

可以！规格在构建时创建。我们的观点是，试图预先生成所有规格是浪费时间。根据需要创建规格，逐步构建。

Q: 切换编码代理时会发生什么？

我们的目标是成为你可以带到任何地方的通用规划层。编码代理正在快速改进。这个月流行的下个月可能就不流行了。你的规格不应该关心。

Q: 规格存在哪里？

在你的代码库中。我们的观点是它们应该被签入 — 它们提供系统如何工作以及构建意图的可见性。

Q: 这不就是瀑布吗？

瀑布失败是因为僵化的计划和数月的前期规划。这都不是。我们希望你得到足够好的计划并开始编码 — 最少的努力，轻量级的流程。

总结

OpenSpec 是一个轻量级的规格驱动开发框架，核心价值：

价值	实现方式
轻量级	秒级初始化，最少流程
流畅	无阶段门槛，随时更新产物
迭代	随着学习更新规格
棕地优先	增量规格，适合现有代码库
工具无关	支持 25+ AI 编码助手

核心理念：

规格是可执行的第一类产物，而非丢弃的脚手架。

先同意再构建，而非先构建再返工。