OpenSpec：规格驱动开发的轻量级实践框架

发表于： 2026-02-27 分类于：思维改变生活

字数： 1219 阅读：≈ 6分钟

在 AI 辅助编程时代，我们见证了代码生成效率的惊人提升，但也面临着一个新的挑战:当 AI 能够快速生成大量代码时，如何确保系统的一致性、可维护性和演进方向？在上一篇文章《规格驱动开发与Spec-Kit：人工智能时代的软件工程范式》中，我们深入探讨了 GitHub 推出的完整工程化体系 Spec-Kit。本文将介绍另一个更轻量级的选择——OpenSpec，一个开源的规格驱动框架，为追求快速迭代的团队提供了一个优雅的解决方案。

从"氛围编程"到规格驱动的范式转变

AI 编程时代的新困境

2024年末到2025年初，“氛围编程”(Vibe Coding)成为开发者社区的热门话题。这种开发模式的特点是:开发者通过不断的碎片化提示词与 AI 助手交互，依靠 AI 的概率性预测来拼凑代码。虽然这种方式在原型构建中展现了惊人的速度，但在处理复杂系统时，问题逐渐显现:

架构漂移:缺乏整体设计，代码结构混乱
上下文丢失:聊天历史消失后，AI 无法保持一致性
技术债务累积:为了快速实现功能而忽略长期可维护性
AI 幻觉:AI 可能生成看似合理但实际错误的代码

规格驱动开发的核心理念

OpenSpec 代表的规格驱动开发(Specification-Driven Development， SDD)提出了一个根本性的转变:从"编写代码"转向"定义规格"。

如果将软件开发比作建造大楼:

氛围编程像是在没有蓝图的情况下指挥机器人边盖边拆
规格驱动则是先绘制出精确的数字蓝图，让 AI 严格按照蓝图执行

这种转变带来了一个重要的"权力反转":

传统模式:代码是真理来源，文档服务于代码
规格驱动:规格是真理来源，代码是规格的临时表达

OpenSpec 的设计哲学

OpenSpec 秉持"流动而非僵化"的哲学:

→ fluid not rigid (流动而非僵化)
→ iterative not waterfall (迭代而非瀑布)
→ easy not complex (简单而非复杂)
→ built for brownfield not just greenfield (为成熟项目而非仅为新项目设计)
→ scalable from personal projects to enterprises (从个人项目到企业规模)

核心特性

通用性(Universal)
- 支持 20+ AI 编码工具(Claude Code、Cursor、Windsurf、GitHub Copilot 等)
- 不绑定特定编程语言或技术栈
- 基于简单的 Markdown 格式
开源与自主可控
- GitHub: https://github.com/Fission-AI/OpenSpec/
- MIT 许可证
- 所有规格文件存储在本地代码仓库
- 无需 API Keys 或 MCP 协议
轻量级流程
- 最小化规划开销，快速开始编码
- 支持渐进式演进和迭代更新
- 强调行动而非阶段锁定

核心概念

1. Delta Specs (增量规格)

OpenSpec 的关键创新是 Delta Specs——不是重写整个规格，而是描述变更:

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

## REMOVED Requirements

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

2. 项目结构

初始化后的目录结构:

openspec/
├── specs/              # 真理来源(系统当前行为)
│   └── <domain>/
│       └── spec.md
├── changes/            # 提议的变更(每个变更一个文件夹)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Delta specs(变更内容)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # 项目配置(可选)

3. 工件(Artifacts)

每个变更包含四类工件:

工件	作用
`proposal.md`	“为什么"和"做什么”——捕获意图、范围和方法
`specs/`	Delta specs 展示 ADDED/MODIFIED/REMOVED 需求
`design.md`	“怎么做”——技术方案和架构决策
`tasks.md`	实现清单(带复选框)

工件间的依赖关系:

graph LR A[proposal] --> B[specs] B --> C[design] C --> D[tasks] D --> E[implement] E -.随时回退和完善.-> A E -.随时回退和完善.-> B E -.随时回退和完善.-> C

快速开始

安装

要求: Node.js 20.19.0 或更高版本

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

# 在项目中初始化
cd your-project
openspec init

选择工作流配置

OpenSpec 提供两种工作流配置:

# 查看和选择配置
openspec config profile

# 应用配置
openspec update

core profile (默认): 快速路径，包含 propose、explore、apply、archive
扩展工作流: 包含更细粒度的控制命令

工作流模式

默认快速路径 (Core Profile)

最简单的三步走:

graph LR A["/opsx:propose"] --> B["/opsx:apply"] B --> C["/opsx:archive"]

示例对话:

You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this
     ✓ 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.

探索模式

当需求不清晰时使用 /opsx:explore:

You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle rate limiting for our API?

AI:  Let me investigate your current setup...
     [分析代码库, 考虑模式]

     I see three approaches:
     1. Middleware-based (simple, per-endpoint)
     2. Redis-backed (scalable, shared state)
     3. Token bucket per user (fair, complex)

     Your current stack suggests #1 or #2. What's your scale?

You: We expect 1000 req/s. Let's go with Redis.

You: /opsx:propose add-redis-rate-limiting

AI:  Created change based on our exploration...

扩展工作流 (可选)

对于需要更精细控制的场景:

graph LR A["/opsx:new"] --> B["/opsx:ff"] A --> C["/opsx:continue
(逐步创建工件)"] B --> D["/opsx:apply"] D --> E["/opsx:verify"] E --> F["/opsx:archive"]

逐步控制 vs 快进:

命令	何时使用
`/opsx:ff`	需求明确，快速创建所有规划工件
`/opsx:continue`	复杂变更，需要逐步审查每个工件
`/opsx:verify`	实现前验证完整性、正确性、一致性

核心命令参考

默认 Core Profile 命令

命令	用途
`/opsx:propose`	一步创建变更和规划工件
`/opsx:explore`	探索和调研，需求澄清
`/opsx:apply`	执行任务清单中的实现
`/opsx:archive`	归档完成的变更，合并 specs

扩展工作流命令

命令	用途
`/opsx:new`	创建变更脚手架
`/opsx:continue`	创建下一个工件(逐步)
`/opsx:ff`	快进创建所有规划工件
`/opsx:verify`	验证实现与工件匹配
`/opsx:sync`	手动合并 delta specs (archive 会自动提示)
`/opsx:bulk-archive`	批量归档多个变更

CLI 工具

除了与 AI 对话的斜杠命令，OpenSpec 还提供命令行工具:

# 列出所有活动变更
openspec list

# 查看变更详情
openspec show add-dark-mode

# 验证规格格式
openspec validate add-dark-mode

# 交互式仪表板
openspec view

实际使用示例

示例: 添加深色模式

第 1 步: 提出变更

You: /opsx:propose add-dark-mode

生成的 proposal.md:

# Proposal: Add Dark Mode

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

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

## Approach
Use CSS custom properties with React context for state management.

第 2 步: 查看 Delta Specs

specs/ui/spec.md:

# Delta for UI

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

第 3 步: 实现

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext
     ✓ 1.2 Added CSS custom properties
     ✓ 1.3 Implemented localStorage persistence
     All tasks complete!

第 4 步: 归档

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!

OpenSpec vs 其他工具

与 GitHub Spec-Kit 的对比

维度	OpenSpec	Spec-Kit
哲学	流动迭代，行动驱动	严格阶段，流程驱动
学习曲线	低，3个核心命令即可开始	中等，7个标准化阶段
灵活性	高，随时更新工件	中，鼓励完成后再进入下一阶段
工具支持	20+ AI 编码助手	需要特定 AI 助手支持
设置	`npm install` 即可	需要 Python 环境和依赖
适用场景	个人到中型团队	大型企业，合规性要求高

与 Kiro 的对比

特性	OpenSpec	Kiro (AWS)
工具锁定	可用任何AI助手	锁定在 Kiro IDE
模型选择	支持所有模型	仅限 Claude 模型
部署	本地文件，无云依赖	AWS 云服务
成本	开源免费	商业服务

与"无规格"的对比

无规格开发的问题:

模糊的提示词导致不可预测的结果
AI 需要不断重复理解上下文
团队成员难以理解变更意图
无法追踪需求演进历史

OpenSpec 带来的改进:

明确的规格文档减少歧义
持久化上下文，无需重复说明
变更意图清晰记录
Delta specs 提供审计轨迹

最佳实践

1. 保持变更聚焦

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

为什么重要:

更容易审查和理解
更清晰的归档历史
可以独立发布
失败时更容易回滚

2. 需求不明确时先探索

You: /opsx:explore

AI:  What would you like to explore?

You: How should we implement user notifications?

AI:  Let me check your current tech stack...
     [分析代码库]

     I see three options:
     1. WebSockets (real-time, more complex)
     2. Server-Sent Events (simpler, one-way)
     3. Polling (simplest, but inefficient)

     What's your priority: simplicity or real-time?

3. 使用 verify 检查实现

You: /opsx:verify

AI:  Verifying add-dark-mode...

     COMPLETENESS
     ✓ All tasks checked
     ✓ All requirements implemented
     ⚠ Scenario "System preference" has no test

     CORRECTNESS
     ✓ Implementation matches spec intent
     ✓ Edge cases handled

     COHERENCE
     ✓ Design decisions reflected in code
     ⚠ Design mentions "CSS variables" but using Tailwind

     SUMMARY: Ready to archive (with 2 warnings)

4. 清晰命名变更

Good:                          Avoid:
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

编写高质量规格

OpenSpec 推荐的规格结构:

# [Feature Name] Specification

## Purpose
简要说明该功能的业务价值(1-2句话)

## Requirements

### Requirement: [具体要求]
系统应该做什么(使用 SHALL/MUST/SHOULD)

#### Scenario: [使用场景]
- GIVEN [前置条件]
- WHEN [触发事件]
- THEN [预期结果]
- AND [额外条件]

关键原则:

聚焦"What"而非"How": 描述需求而非实现细节
使用场景驱动: 通过 GIVEN-WHEN-THEN 明确行为
可测试性: 每个场景应可转化为自动化测试
渐进完善: 初版不必完美，随迭代补充细节

常见陷阱与应对

1. 过度规划

❌ 错误: 试图在开始前定义所有细节
✅ 正确: 定义核心需求即可开始，遇到问题时补充

2. 文档与代码脱节

❌ 错误: 代码改了但规格没更新
✅ 正确: 将规格更新作为变更的一部分，archive 时自动合并

3. 技术细节污染

❌ 错误: “用户点击按钮后，调用 POST /api/login 接口”
✅ 正确: “用户提交登录凭证后，系统验证身份”

高级功能

并行工作

同时处理多个变更:

graph TD A1["Change A: /opsx:propose"] --> A2["Change A: /opsx:apply (进行中)"] A2 -.切换上下文.-> B1["Change B: /opsx:propose"] B1 --> B2["Change B: /opsx:apply"] B2 --> B3["Change B: /opsx:archive"] B3 -.回到 A.-> A3["Change A: /opsx:apply (继续)"] A3 --> A4["Change A: /opsx:archive"]

完成后使用 /opsx:bulk-archive 批量归档:

You: /opsx:bulk-archive

AI:  Found 3 completed changes:
     - add-dark-mode
     - fix-login-bug
     - update-footer

     Checking for spec conflicts...
     ⚠ add-dark-mode and update-footer both touch specs/ui/

     Will apply in chronological order.
     Archive all 3 changes?

You: Yes

AI:  ✓ Archived all changes
     Specs merged: add-dark-mode → update-footer

自定义工作流

OpenSpec 支持自定义 schema 来定义工件序列。详见官方文档。

团队协作

使用 OpenSpec 的团队可以:

通过 Git 协作: 规格和变更都是 Markdown 文件，可以 PR 审查
共享上下文: 新成员阅读 openspec/specs/ 快速了解系统
追踪历史: changes/archive/ 提供完整的变更审计轨迹
并行开发: 每个变更独立的文件夹，减少冲突

更新 OpenSpec

升级包:

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

刷新 AI 指令(在每个项目中):

openspec update

这会重新生成 AI 指导文件，确保最新的斜杠命令生效。

遥测与隐私

OpenSpec 收集匿名使用统计(仅命令名称和版本号)，不含参数、路径、内容或个人信息。

退出:

export OPENSPEC_TELEMETRY=0
# 或
export DO_NOT_TRACK=1

结语:行动而非阶段

OpenSpec 最重要的理念是:行动，而非阶段。

传统方法将你锁定在阶段中:

graph LR A[PLANNING] --> B[IMPLEMENTING] B --> C[DONE] A -.不能回退.-> B

OpenSpec 提供的是行动:

graph LR A[proposal] --> B[specs] B --> C[design] C --> D[tasks] D --> E[implement] E -.随时回退和完善.-> A E -.随时回退和完善.-> B E -.随时回退和完善.-> C

依赖关系是赋能者，而非限制者——它们展示什么是可能的，而不是强制你必须做什么。

在 AI 放大我们能力的时代，真正的效率不是"多快写完代码"，而是"多快交付正确的系统"。OpenSpec 通过轻量级的规格驱动，帮助我们在速度与质量之间找到平衡。

相关资源:

官网: https://openspec.dev/
GitHub: https://github.com/Fission-AI/OpenSpec/
Discord 社区: https://discord.gg/YctCnvvshC
支持的工具列表: Supported Tools

延伸阅读:

规格驱动开发与Spec-Kit:人工智能时代的软件工程范式