OpenSpec：用SDD规范驱动开发解决AI编程的上下文管理难题

在使用 AI 进行编程一段时间后，很多人可能会遇到一个共同的尴尬处境：你和 AI 反复讨论了需求，它也生成了代码，但几天后当你需要继续迭代或回顾时，那些关键的需求讨论早已淹没在长长的聊天记录里，难以找回。更糟糕的是，如果你更换了 AI 工具（比如从 Cursor 换到 Claude Code），之前建立的所有上下文将彻底丢失。

OpenSpec 这个开源项目的核心目标，正是为了解决这个“需求对齐”与“上下文丢失”的痛点。

OpenSpec 是什么？

OpenSpec 是一个践行「规范驱动开发」（Specification-Driven Development，SDD）理念的框架。但它并非传统意义上让你撰写大量冗长文档的笨重工具。其核心理念很直接：在让 AI 动手编写代码之前，先将「要做什么」和「怎么做」明确地固定下来。

你可以把它理解为一个专门用于管理 AI编程 过程中需求对齐问题的项目管理工具。它会在你的项目根目录创建一个 openspec/ 文件夹，其内部结构主要分为两部分：

• specs/ – 存放当前系统的主行为规范，定义了“系统现在是如何工作的”。
• changes/ – 存放你计划进行的所有变更，每个变更都拥有自己独立的子文件夹。

这种设计颇具巧思——它将“工作区”与“主规范”分离开来。你可以并行推进多个变更任务而互不干扰；当一个变更完成并通过验证后，再将其“归档”并合并到主规范中。

它适用于哪些场景？

笔者认为，OpenSpec 在以下几类场景中能发挥最大价值：

第一，复杂功能的渐进式开发。 当你需要实现一个包含多步骤的复杂功能时，例如“为系统添加 OAuth 登录”，你肯定不希望这个需求的管理完全依赖于与 AI 的闲聊。OpenSpec 会引导你先撰写一个 proposal.md（提案），阐明背景和目标；然后是 design.md（设计文档），规划技术方案；最后是 tasks.md（任务清单），拆解实现步骤。

第二，在多 AI 编程工具间无缝切换。 如今的 AI 编程工具生态丰富，如 Claude Code、Cursor、Windsurf、GitHub Copilot、Cline 等，每个工具都有自己独特的“记忆”或上下文管理方式。OpenSpec 的聪明之处在于，它会为每个支持的 AI 工具在项目内生成对应的「技能文件」（例如 .claude/skills/ 或 .cursor/skills/）。这意味着，无论你使用哪个工具，都能读取并遵循同一套需求规范，实现了上下文的可迁移性。

第三，团队协作与知识传承。 当一名开发者使用 AI 完成一个功能后，另一名成员需要接手维护或迭代时，OpenSpec 生成的规范文档便成为最理想的交接材料。接手者无需翻阅数百条聊天记录，直接查看 openspec/changes/ 目录下的文档，就能清晰理解当初的设计意图和实现细节。

基本使用流程

OpenSpec 设计了一套流畅的使用体验，最简化的核心工作流如下：

/opsx:propose → /opsx:apply → /opsx:archive

第一步：/opsx:propose “功能名称”
向 AI 描述你想做什么，例如“添加深色模式”。AI 会协助你在 openspec/changes/add-dark-mode/ 目录下创建一系列“工件”（Artifact）：

• proposal.md – 阐述功能背景、价值和范围。
• design.md – 详述技术实现方案与架构决策。
• tasks.md – 拆解为具体的、可执行的任务清单。
• specs/ – 存放此变更涉及的增量行为规范（Delta Specs）。

第二步：/opsx:apply
AI 将依据 tasks.md 中的清单，逐步实现代码。你可以随时通过相关命令查看任务进度。

第三步：/opsx:archive
功能开发完成并测试通过后，执行归档命令。OpenSpec 会将 changes/ 目录下的 Delta Specs 合并到主 specs/ 目录中，并将已完成的变更文件夹移动到 changes/archive/ 下，作为项目历史记录保存。

除了这个简化流程，OpenSpec 还提供了一套更完整的命令集供细粒度控制，例如 /opsx:new（新建变更）、/opsx:continue（继续完善提案）、/opsx:ff（快速填充任务）、/opsx:verify（验证实现）等。

核心实现机制解析

阅读其源码后，笔者认为 OpenSpec 有几个设计点值得深入探讨。

1. Agent Skills 生成机制
这是 OpenSpec 最核心且巧妙的部分。它支持超过20种 AI 工具，并为每种工具生成其专属的「技能」配置文件。OpenSpec 在 src/core/templates/workflows/ 目录下定义了一套统一的工作流模板（如 propose.ts、apply-change.ts），然后通过适配器模式将其转换并写入各工具能识别的特定隐藏目录（如 .claude/skills/、.cursor/skills/）。这使得同一套工作流指令能在不同 AI 助手中无缝运行。

2. Delta Spec 的合并算法
Delta Spec 是 OpenSpec 对“变更”的抽象。每个变更的 specs/ 目录下会包含结构化的规范描述，例如：

## ADDED Requirements

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

## MODIFIED Requirements

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

## REMOVED Requirements

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

在执行归档时，OpenSpec 的合并算法会解析这些 ADDED、MODIFIED、REMOVED 标记，并智能地更新主规范文件。这个过程实现了变更历史的可追溯性与系统规范“单一真相源”的维护。

3. 基于 Schema 的工件管理
OpenSpec 引入了“工件”的概念，每个变更包含多个相互依赖的工件：提案（proposal）、设计（design）、任务（tasks）、规范（specs）等。源码中的 status.ts 可以检查工件的完成状态与依赖关系，instructions.ts 则能根据当前状态生成给 AI 的下一步指令。这套系统确保了 AI 在协作中始终明确“现在该做什么”，避免了在对话中迷失方向。

4. 分层式的 CLI 命令架构
OpenSpec 的 CLI 基于 commander.js 构建，其命令结构清晰分层：

• 顶层命令：如 openspec init（初始化）、openspec update（更新技能）、openspec list（列出变更）。
• 工作流命令：如 openspec status（查看状态）、openspec instructions（获取指令）、openspec new change（新建变更）。
• AI 技能命令：即 /opsx:* 系列的斜杠命令，它们由生成的技能文件提供，并在各 AI 工具内部被调用执行。
  这种架构让 OpenSpec 既能作为独立的 CLI 工具使用，又能深度集成到各类 AI 助手的交互流程中。

实战案例：为 Git AI Stats 添加分支快捷选择

理论或许有些抽象，让我们通过一个真实案例来感受 OpenSpec 的实际应用。笔者最近使用它完成了一个对内部工具“Git AI Stats”的微小但实用的改进。

需求背景
“Git AI Stats”工具中有一个“测试单项目统计”功能弹窗，用户需要手动输入要统计的分支名。反馈指出，绝大多数项目使用的都是 main 或 master 分支，每次手动输入效率低下。需求很明确：在分支输入框旁，增加 main 和 master 两个快捷选择按钮。

使用 OpenSpec 的实施流程

第一步：发起提案
执行命令：/opsx:propose git-ai-stats 工具中的测试单项目统计功能中，分支除了支持直接输入，还支持直接选择 main 或者 master分支。

OpenSpec 随即创建了变更目录 openspec/changes/git-stats-branch-quick-select/，并生成了完整的初始工件。其中，proposal.md 明确了“减少用户输入操作”的初衷；design.md 规划了使用纯 JavaScript 和 Tailwind CSS 实现交互的技术方案；tasks.md 列出了修改 HTML 结构、添加 JS 逻辑和样式的具体任务；specs/ 下的 Delta Spec 则用类似 Gherkin 的语法描述了新增的交互行为规范。

第二步：应用与实现
执行 /opsx:apply，AI 开始依据 tasks.md 逐项实现。在此过程中，笔者发现初始设计遗漏了“按钮高亮互斥”的细节，于是回头更新了 design.md 进行补充。这个“迭代更新设计”的过程被自然地记录了下来。

第三步：归档变更
功能测试通过后，执行 /opsx:archive。OpenSpec 自动将 Delta Spec 合并到主规范，并将整个变更文件夹移至 changes/archive/ 下，并附上日期标记，形成了清晰的历史记录。

这个案例带来的价值
开发这样一个简单功能，传统方式可能半小时就能写完代码，但所有决策上下文将随之消散。而使用 OpenSpec 后：

1. 需求可追溯：proposal.md 清晰记录了“减少输入操作”的原始动机。
2. 设计决策有据可查：为何将按钮置于下方而非右侧、为何采用事件监听而非状态管理，这些决策过程均记录在 design.md 中。
3. 行为规范可验证：spec.md 中的场景描述可直接作为自动化测试的验收标准。
4. 工具链兼容：基于 OpenSpec 生成的规范，该变更可以由 Claude Code 开始，并由 Cursor 无缝接手继续。

最关键的是，整个过程并未产生“为了写文档而写文档”的负担。每个工件都有其明确的实用目的：提案对齐意图、设计对齐方案、任务对齐执行、规范对齐行为。这正契合了 AI 编程时代所需的、人机协同的高效工作流。

总结

OpenSpec 的理念颇具启发性——它并非增加开发负担，而是旨在解决 AI 编程时代特有的“上下文管理”与“知识传承”问题。它承认一个现实：在人类与 AI 的协作中，需求会演化，理解会深化，因此规范本身也应该是可迭代、可生长的，而非一成不变。

为需求和实现之间建立一份清晰、可维护的“契约”，对于协作双方都大有裨益。当然，这也意味着需要更多的上下文 Token 来承载这份契约，这是追求清晰与可维护性时无法避免的权衡。

如果你也在探索如何更有效地管理 AI 编程项目，或对规范驱动开发感兴趣，不妨在 云栈社区 分享你的实践与见解。