OpenSpec:为 AI 编程助手打造的 Spec-Driven Development 框架

一句话总结：OpenSpec 是一个轻量级的规范驱动开发（Spec-Driven Development, SDD）框架，核心目标是让人类与 AI 在写代码之前就达成共识，从而解决 AI 编程中"需求模糊导致结果不可预测"的痛点。

一、解决了什么问题？

AI 编程的"黑箱"困境

随着 Claude Code、Cursor、GitHub Copilot 等 AI 编程工具的普及，开发者面临一个核心矛盾：

AI 能力很强：能写代码、修 Bug、重构架构
但需求对齐很难：人类脑子里的"做个暗色模式"和 AI 实际生成的代码之间，往往存在巨大偏差

这导致了三种典型痛点：

反复修改：AI 写完了，发现不对，再改，再不对，循环往复
上下文污染：在反复修改中，AI 的上下文窗口被无用信息填满，越往后越糊涂
无法并行协作：多个功能同时开发时，AI 容易把不同需求的改动混在一起

OpenSpec 的解法

OpenSpec 借鉴了传统软件工程中"先设计后实现"的理念，但去掉了瀑布模型的笨重感。它引入了一个轻量级的 Spec（规范）层，作为人类与 AI 之间的"契约"：

核心逻辑：先让 AI 理解"要做什么"（Spec），再让它动手做（Code）。如果理解错了，在 Spec 阶段就能纠正，代价远低于改代码。

二、核心功能

1. 双轨目录结构：现状 vs 变更

OpenSpec 在项目根目录下创建一个 openspec/ 文件夹，内部有两套体系：

openspec/├── specs/                    # 现状规范（Source of Truth）│   ├── auth/│   │   └── spec.md          # 认证系统当前行为│   ├── payments/│   │   └── spec.md          # 支付系统当前行为│   └── ui/│       └── spec.md          # UI 层当前行为│└── changes/                  # 变更提案（Proposed Changes）    ├── add-dark-mode/        # 每个变更一个独立文件夹    │   ├── proposal.md       # 为什么做、做什么    │   ├── design.md         # 技术方案    │   ├── tasks.md          # 任务清单（带复选框）    │   └── specs/            # Delta Spec：相对于现状的变更    │       └── ui/    │           └── spec.md   # 仅描述 UI 要改什么    │    └── archive/              # 已完成的变更归档        └── 2025-01-23-add-dark-mode/

关键设计：

specs/ 是系统的"活文档"，描述当前真实行为
changes/ 里的每个文件夹是一个隔离的变更单元，可以独立评审、并行开发
变更完成后归档，specs 被更新，形成可追溯的演进历史

2. OPSX 命令体系：AI 原生工作流

OpenSpec 定义了一套以 /opsx: 为前缀的斜杠命令，AI 助手可以直接解析执行：

/opsx:propose "idea" — 创建变更提案，自动生成 proposal.md、specs/、design.md、tasks.md
/opsx:apply — 按 tasks.md 的复选框清单自动实现代码
/opsx:archive — 归档已完成变更，将 Delta Spec 合并入主 specs
/opsx:sync — 同步更新 specs（扩展工作流）
/opsx:verify — 验证实现是否符合 spec（扩展工作流）

示例交互：

开发者: /opsx:propose add-dark-modeAI: 已创建 openspec/changes/add-dark-mode/    ✓ proposal.md — 变更意图与范围    ✓ specs/ — 需求与场景    ✓ design.md — 技术方案    ✓ tasks.md — 实现清单    准备就绪，可以开始实现！开发者: /opsx:applyAI: 正在执行任务...    ✓ 1.1 添加主题上下文 Provider    ✓ 1.2 创建切换组件    ✓ 2.1 添加 CSS 变量    ✓ 2.2 接入 localStorage 持久化    所有任务完成！开发者: /opsx:archiveAI: 已归档至 openspec/changes/archive/2025-01-23-add-dark-mode/    规范已更新。准备进行下一个功能。

3. Delta Spec：精准描述"变更"

这是 OpenSpec 最具技术深度的设计。不同于传统文档的"全量重写"，Delta Spec 只描述相对于当前系统的变化：

# UI 规范（Delta）## 新增### 主题系统- 支持 light / dark 两种主题- 通过 CSS 自定义属性（variables）实现- 切换时无闪烁（避免 FOUC）## 修改### 全局样式- 现有 `globals.css` 增加 `:root` 变量定义- 所有硬编码颜色值替换为变量引用## 移除- 无

好处：

AI 明确知道"哪些要动、哪些不动"
避免 AI 在实现时"过度发挥"，把没要求改的地方也改了
变更评审时，评审者只需看 Delta，不用重新理解整个系统

4. 多工具兼容：25+ AI 助手支持

OpenSpec 不绑定特定 AI 工具，支持市面上绝大多数主流 AI 编程助手：

IDE 内置：Cursor、GitHub Copilot、Windsurf、Cline
独立工具：Claude Code、OpenCode、CodeBuddy、Qoder
云端模型：Gemini、Qwen、IBM Bob Shell

每个工具通过"Agent Skills"或斜杠命令接入，开发者可以继续使用自己习惯的编辑器。

5. 协调工作空间（Workspace）：跨仓库协作（Beta）

针对微服务或多仓库项目，OpenSpec 提供了 Workspace 概念：

workspace-folder/├── changes/                    # 跨仓库的变更规划└── .openspec-workspace/    ├── workspace.yaml          # 共享配置（链接名称）    └── local.yaml             # 本地路径映射（不共享）

使用场景：

一个功能需要同时改 api 仓库和 web 仓库
在 Workspace 层面统一规划，在各仓库本地执行
通过 openspec workspace open 一键打开所有相关仓库

三、实现逻辑与技术细节

1. 初始化流程（openspec init）

当执行 openspec init 时，CLI 会执行以下操作：

Step 1：环境检测

检查 Node.js 版本（要求 >= 20.19.0）
检测当前目录是否已存在 openspec/ 目录（存在则报错或提示覆盖）
识别项目类型（通过 package.json、语言文件等推断技术栈）

Step 2：目录骨架生成

project-root/├── openspec/│   ├── specs/                    # 空目录，等待首次 spec 创建│   ├── changes/                  # 空目录，包含 archive/ 子目录│   │   └── archive/             # 预创建，存放历史变更│   └── config.yaml              # 项目配置文件├── AGENTS.md                     # 根级 Agent 上下文（项目级）└── .gitignore                    # 追加 openspec/changes/ 规则（可选）

Step 3：配置文件生成config.yaml 的初始内容：

version:1profile:core# 默认精简工作流language:zh# 根据环境推断，可手动指定project:name:"my-project"# 从 package.json 或目录名推断type:"web"# 项目类型标记capabilities: []                 # 初始为空，随变更累积

Step 4：Agent 指令注入 CLI 会将当前 profile 对应的 Agent 指令写入项目。这些指令是 AI 助手解析 /opsx: 命令的规则集，本质上是告诉 AI：

遇到 /opsx:propose 时，读取 openspec/specs/ 作为上下文，生成变更文件夹
遇到 /opsx:apply 时，读取 tasks.md 中的复选框，逐项实现
遇到 /opsx:archive 时，执行合并与归档逻辑

2. 配置分层与加载优先级

OpenSpec 采用三层配置体系，上层覆盖下层：

┌─────────────────────────────────────────┐│  Layer 3: 变更级（最高优先级）            ││  openspec/changes/<name>/local.yaml     ││  → 仅影响当前变更的临时覆盖               │├─────────────────────────────────────────┤│  Layer 2: 项目级                         ││  openspec/config.yaml                   ││  → profile、语言、项目元数据              │├─────────────────────────────────────────┤│  Layer 1: 用户级（全局默认）               ││  ~/.config/openspec/config.yaml         ││  → 默认 profile、telemetry 偏好           │├─────────────────────────────────────────┤│  Layer 0: 内置默认（最低优先级）          ││  硬编码在 CLI 二进制中                    ││  → core profile 定义、命令映射表          │└─────────────────────────────────────────┘

Profile 系统的实现： Profile 本质是一组"命令白名单" + "Agent 指令模板"：

Profile	包含命令	适用场景
`core`	propose, explore, apply, sync, archive	快速迭代，个人项目
`expanded`	new, continue, ff, verify, bulk-archive, onboard	团队协作，需要评审

切换命令：

openspec config profile   # 交互式选择# 底层操作：修改 config.yaml 中的 profile 字段# 然后执行 openspec update 将新 profile 的指令写入 AGENTS.md

3. /opsx:propose 的执行逻辑

当 AI 助手收到 /opsx:propose "add-dark-mode" 时，内部执行流程：

Phase 1：上下文收集

读取 openspec/specs/ 下所有 spec.md → 构建"系统现状图"
读取 openspec/config.yaml → 获取项目类型、语言
读取 AGENTS.md → 获取项目级背景信息
扫描项目代码树（可选，由 AI 工具决定）→ 获取当前文件结构

Phase 2：变更分析 AI 基于收集的上下文，判断：

这个变更涉及哪些 capability？（如 ui、auth）
是新增 capability 还是修改现有？
与现有 specs 是否存在冲突？

Phase 3：Artifacts 生成 在 openspec/changes/add-dark-mode/ 下创建：

文件	生成逻辑	内容来源
`proposal.md`	AI 根据用户意图生成	用户输入 + 项目背景
`specs/<cap>/spec.md`	对比现状 spec，输出 Delta	现状 spec + 变更需求
`design.md`	AI 基于 Delta Spec 设计技术方案	Delta Spec + 技术栈
`tasks.md`	AI 将 design.md 拆解为可执行步骤	design.md 中的架构决策

关键约束：

tasks.md 中的任务必须使用 Markdown 复选框语法（- [ ]）
任务编号采用层级格式（1.1、1.2、2.1），便于 AI 追踪依赖关系
如果变更涉及多个 capability，会在 specs/ 下创建多个子目录

4. /opsx:apply 的执行逻辑

这是 AI 实际写代码的阶段，执行流程：

Step 1：任务加载 AI 读取 tasks.md，解析所有未勾选的复选框项，构建任务队列。

Step 2：上下文准备

将 design.md 和 specs/ 注入 AI 上下文窗口
上下文卫生：清除与当前变更无关的历史对话（这是官方推荐的优化点）
如果任务涉及修改现有文件，AI 会先读取目标文件内容

Step 3：逐项实现

for task in tasks:    1. 读取 task 描述    2. 推断需要修改的文件    3. 生成代码变更（diff）    4. 应用变更到文件系统    5. 在 tasks.md 中勾选该任务（- [x]）    6. 如果任务失败，标记为 - [ ] 并附加错误说明

Step 4：完成确认 所有任务勾选后，AI 输出完成摘要。如果有失败任务，提示用户手动处理或重新执行 /opsx:apply。

实现细节：

AI 通过复选框状态判断"哪些做了、哪些没做"，这是状态持久化的核心机制
如果实现过程中发现 design.md 有缺陷，AI 会提示用户更新 design.md，而不是擅自偏离
支持增量 apply：如果上次执行到一半中断，重新 /opsx:apply 会从第一个未勾选任务继续

5. /opsx:archive 的合并算法

归档阶段是 OpenSpec 最核心的数据操作，涉及 Spec 合并：

Step 1：变更目录移动

mv openspec/changes/add-dark-mode \   openspec/changes/archive/2025-01-23-add-dark-mode/

时间戳格式：YYYY-MM-DD，确保归档目录按时间排序。

Step 2：Delta Spec 合并 这是最关键的操作。假设变更修改了 ui capability：

变更前：specs/ui/spec.md          ← 现状changes/add-dark-mode/specs/ui/spec.md  ← Delta（新增/修改/移除）合并后：specs/ui/spec.md          ← 合并结果

合并规则：

新增章节：直接追加到目标 spec
修改章节：用 Delta 中的内容替换目标 spec 的对应章节
移除章节：从目标 spec 中删除
冲突检测：如果目标 spec 在变更期间被其他变更修改过，标记冲突需人工解决

Step 3：Capability 注册 如果变更引入了全新的 capability（如之前没有 notifications），合并后会在 config.yaml 的 capabilities 数组中追加：

capabilities:-auth-payments-ui-notifications# ← 新增

Step 4：清理

删除变更目录中的临时文件
更新 AGENTS.md 中的项目状态摘要（可选）

6. Workspace 跨仓库协作机制（Beta）

Workspace 解决的是"一个功能跨多个仓库"的场景，其实现逻辑：

存储结构：

# 全局存储（按平台）$XDG_DATA_HOME/openspec/workspaces/           # Linux（XDG 合规）~/.local/share/openspec/workspaces/          # Linux（fallback）%LOCALAPPDATA%\openspec\workspaces\          # Windows# 每个 Workspaceworkspaces/├── platform/                               # workspace 名称│   ├── changes/                           # 跨仓库变更规划│   └── .openspec-workspace/│       ├── workspace.yaml                  # 共享：链接名称 + 元数据│       └── local.yaml                      # 本地：绝对路径映射└── registry.yaml                           # 名称 → 路径索引

workspace.yaml（可共享）：

version:1name:platformlinks:api: {}           # 仅声明链接名称，不存路径web: {}

local.yaml（本地专属，不提交 Git）：

version:1paths:api:/Users/dev/repos/api# 本机绝对路径web:/Users/dev/repos/web

命令执行链：

openspec workspace setup                    # 交互式创建  → 生成 workspace.yaml + local.yaml  → 注册到全局 registry.yamlopenspec workspace open                     # 打开工作空间  → 读取 local.yaml 中的 paths  → 根据 opener 类型执行：     - codex:      调用 codex CLI 打开多个目录     - claude:     调用 claude CLI     - github-copilot: 在 VS Code 中打开多根工作区     - editor:     调用系统默认编辑器

设计约束：

workspace open 仅用于探索和规划，不自动执行代码变更
实际实现仍需在各仓库内执行 /opsx:apply
命令、状态文件、JSON 输出格式可能随时变化（Beta 警告）

7. Telemetry 与隐私设计

OpenSpec 内置了轻量级遥测，但设计上极度克制：

采集项	说明
命令名称	如 `propose`、`apply`、`archive`
CLI 版本	用于兼容性统计
不采集	命令参数、文件路径、代码内容、PII

自动禁用场景：

检测到 CI 环境（CI=true 或常见 CI 变量）
手动设置 OPENSPEC_TELEMETRY=0 或 DO_NOT_TRACK=1

实现方式：每次命令执行后，向统计端点发送一个极简的 JSON payload，不包含任何项目敏感信息。

8. Agent 指令的更新机制

openspec update 命令的底层逻辑：

读取当前 config.yaml 中的 profile
从 CLI 内置模板库中提取对应 profile 的 Agent 指令
将指令写入 AGENTS.md（根目录）和/或各 AI 工具的配置目录
如果检测到 AI 工具版本变更，提示重新配置

这保证了：

升级 CLI 后，Agent 指令自动同步
不同项目可以用不同 profile，互不影响
AI 助手始终拥有最新的命令解析规则

四、使用方式

快速上手（3 步）

第 1 步：安装

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

第 2 步：初始化项目

cd my-projectopenspec init

第 3 步：开始第一个变更 在 AI 聊天中输入：

/opsx:propose "添加用户认证功能"

AI 会自动创建 openspec/changes/add-user-auth/ 目录及所有 artifacts。

扩展工作流

如需更精细的控制（分阶段推进、验证、批量归档）：

openspec config profile   # 选择 expanded profileopenspec update           # 应用配置更新

然后使用 /opsx:new、/opsx:ff、/opsx:verify 等命令。

常用 CLI 命令

openspec init                    # 初始化项目openspec config profile          # 切换工作流 profileopenspec update                  # 更新 agent 指令openspec workspace setup         # 设置跨仓库工作空间openspec workspace list          # 列出工作空间openspec workspace open          # 打开工作空间（IDE/编辑器）

模型建议

根据官方推荐：

规划阶段：Opus 4.5、GPT 5.2（强推理能力，适合生成 spec）
实现阶段：同样适用，但需注意上下文卫生——在 /opsx:apply 前清理无关上下文，保持窗口干净

五、竞品对比

工具	主要限制	OpenSpec 优势
Spec Kit (GitHub)	重量级，阶段门严格，需 Python 环境	轻量，可自由迭代
Kiro (AWS)	锁定自有 IDE，仅支持 Claude 模型	工具无关，模型无关
无框架裸用	提示词模糊，结果不可预测	可预测性 + 低仪式成本

六、总结

OpenSpec 的本质是给 AI 编程加一个"需求澄清层"。它不试图取代 AI 的编码能力，而是解决"AI 不知道你要什么"的前置问题。

对于个人开发者，它提供了结构化的变更管理，避免项目后期变成一团乱麻；对于团队协作，它提供了可评审、可归档的规范演进历史；对于企业，它的 Workspace 和 Profile 系统支持规模化推广。

如果你已经习惯用 AI 写代码，但厌倦了"说一遍改三遍"的拉锯战，OpenSpec 值得一试。

项目信息

仓库：https://github.com/Fission-AI/OpenSpec^[1]
许可证：MIT
Stars：46.3k | Forks：3.2k
安装：npm install -g @fission-ai/openspec@latest

引用链接

[1]https://github.com/Fission-AI/OpenSpec