【Spec Coding】OpenSpec：AI 原生规格驱动开发（SDD）框架
告别"靠聊天记录驱动开发"的混乱时代，用结构化的规格管理让 AI 编程助手更可控、更可靠。
前言
AI 编程助手（如 Claude Code、Cursor 等）已经极大地提升了开发效率，但一个普遍的问题是：需求只存在于聊天记录中。当你和 AI 来回对话几十轮后，很难追踪"当前到底实现了什么"、“为什么要这样设计”。更糟糕的是，换一个 AI 会话或换一个工具，之前的上下文全部丢失。
OpenSpec正是为了解决这个问题而生的——它在你和 AI 之间建立了一层轻量级的规格层，让你在写任何代码之前先对齐"要构建什么"。
一、OpenSpec 是什么？
OpenSpec 是一个AI 原生的规格驱动开发框架，核心思路是：
用结构化的 Markdown 文件管理项目的"行为真相"，而不是靠聊天记录来追踪需求。
它提供了一套标准的命令行工具和 AI 斜杠命令，覆盖从需求调研、规格定义、代码实现到归档的全生命周期。
与传统开发的对比
| 方式 | 需求管理 | 可追踪性 | AI 协作 |
|---|---|---|---|
| 不用框架 | 散落在聊天记录里 | 几乎为零 | 不可预测 |
| GitHub Spec Kit | 严格阶段门控 | 好，但笨重 | 需 Python 环境 |
| AWS Kiro | 锁定 IDE 和模型 | 好 | 仅支持 Claude |
| OpenSpec | Markdown 文件管理 | 完善 | 25+ 工具自由选择 |
二、核心概念
2.1 生成文档的目录结构
your-project/ ├── openspec/ │ ├── specs/ # 主规格目录（系统当前行为的真相来源） │ │ └── <domain>/ # 按领域组织（如 auth/、payments/） │ │ ├── spec.md # 行为规格（WHAT & WHY） │ │ └── design.md # 技术设计（HOW，可选） │ ├── changes/ # 进行中的变更 │ │ └── <change-name>/ # 每个变更一个文件夹 │ │ ├── proposal.md # 变更提案（为什么做、做什么） │ │ ├── design.md # 技术设计（怎么做） │ │ ├── tasks.md # 实现任务清单 │ │ ├── .openspec.yaml # 变更元数据（schema、创建日期） │ │ └── specs/ # Delta 规格（增量变更） │ │ └── <domain>/ │ │ └── spec.md │ │ └── archive/ # 已完成的变更存档 │ │ └── YYYY-MM-DD-<name>/ # 带日期前缀的归档文件夹 │ └── config.yaml # 项目配置文件 │ ├── .claude/skills/ # Claude Code 技能文件（如选择了 claude） ├── .cursor/skills/ # Cursor 技能文件（如选择了 cursor） ├── .cursor/commands/ # Cursor OPSX 命令文件 └── ... # 其他 AI 工具配置2.2 Delta Spec：OpenSpec 的灵魂
Delta Spec 是 OpenSpec 最核心的设计。它用三个标记来描述"这次改了什么"：
# Delta for Auth ## ADDED Requirements ### Requirement: Two-Factor Authentication 系统必须要求用户在登录时提供第二因素认证。 #### Scenario: OTP required - GIVEN 一个启用了 2FA 的用户 - WHEN 用户提交了正确的用户名和密码 - THEN 系统应展示 OTP 验证页面 ## MODIFIED Requirements ### Requirement: Session Timeout 系统应在 30 分钟无操作后使会话过期。 （之前：60 分钟） ## REMOVED Requirements ### Requirement: Remember Me （被 2FA 功能取代，已弃用）Archive 时发生了什么？
当你执行/opsx:archive时：
- ADDED的需求追加到主规格文件
- MODIFIED的需求替换原有版本
- REMOVED的需求从主规格中删除
- 整个 change 目录移入
openspec/changes/archive/作为审计历史
这意味着你的openspec/specs/始终是项目当前行为的"唯一真相来源"。
三、安装与初始化
3.1 安装 CLI
npminstall-g@fission-ai/openspec@latest3.2 初始化项目
cdyour-project openspec initopenspec init会自动检测你已安装的 AI 工具（Claude Code、Cursor、Windsurf 等 25+ 工具），并生成对应的斜杠命令配置文件。
3.3 验证安装
openspec--versionopenspec list# 查看当前活跃的变更（此时应为空）四、完整开发流程
OpenSpec 默认使用Core Profile，核心流程只有三步：
/opsx:propose ──► /opsx:apply ──► /opsx:archive4.1 第一步：提出变更（Propose）
当你要开发一个新功能时，只需在 AI 助手（以 Claude Code 为例）中输入：
/opsx:propose add-user-loginAI 会自动创建openspec/changes/add-user-login/目录，并生成四个标准产物：
| 文件 | 内容 | 作用 |
|---|---|---|
proposal.md | 为什么要做这个功能、影响范围 | 对齐动机 |
specs/ | 用 ADDED/MODIFIED/REMOVED 标记的 Delta Specs | 定义行为 |
design.md | 技术方案、架构决策 | 指导实现 |
tasks.md | 分步骤的实现任务清单（带 checkbox） | 跟踪进度 |
这一步的关键价值在于：在写任何代码之前，你和 AI 先就"要构建什么"达成共识。
4.2 第二步：实现（Apply）
确认 proposal 和 specs 没问题后，直接：
/opsx:applyAI 会按照tasks.md中的清单逐项实现代码，边做边打勾：
✓ 1.1 创建用户模型 User model ✓ 1.2 实现密码哈希存储 ✓ 1.3 添加 JWT token 生成逻辑 ✓ 2.1 创建 /api/login 路由 ✓ 2.2 实现登录表单校验 ✓ 2.3 添加单元测试 ... 全部任务完成！4.3 第三步：归档（Archive）
功能开发完成、测试通过后：
/opsx:archiveAI 会自动将 Delta Specs 合并进主规格库，并将 change 移入归档目录：
Archiving add-user-login... ✓ Merged specs into openspec/specs/auth/spec.md ✓ Moved to openspec/changes/archive/2025-05-15-add-user-login/ Done! Ready for the next feature.此时你的主规格文件已经包含了最新的需求定义，随时可以开始下一个功能。
五、需求不明确时：先 Explore
如果你还不确定具体要做什么（例如性能优化、架构重构、Bug 排查），在 propose 之前先用：
/opsx:exploreAI 会帮你分析代码库、调研方案，再决定怎么做。例如：
You: /opsx:explore AI: 你想探索什么？ You: 我想提升页面加载性能，但不确定瓶颈在哪。 AI: 让我分析一下... [分析 bundle 大小、检查慢查询、审查组件渲染模式] 我发现了三个主要瓶颈： 1. 未优化的大图片（占比最高） 2. ProductList 中的同步数据获取 3. Context 变化导致的频繁重渲染 你想先解决哪个？ You: 先解决数据获取的问题。 You: /opsx:propose optimize-product-list-fetching六、流程全景图
七、常用命令速查
CLI 命令
openspec init# 初始化项目，自动检测 AI 工具openspec update# 更新 AI 指令文件openspec list# 查看所有活跃变更openspec show<name># 查看变更或规格详情openspec validate<name># 校验 spec 格式openspec view# 交互式仪表盘openspec archive<name># 归档已完成的变更openspec config profile# 管理 profile（core / custom）AI 斜杠命令
| 命令 | Profile | 作用 |
|---|---|---|
/opsx:propose | Core | 一步生成所有规划产物 |
/opsx:explore | Core | 先调研再规划 |
/opsx:apply | Core | 按 tasks.md 实现代码 |
/opsx:archive | Core | 合并规格、归档变更 |
/opsx:new | Custom | 创建新变更 |
/opsx:continue | Custom | 逐步生成规划产物 |
/opsx:ff | Custom | 跳过审查，快速推进 |
/opsx:verify | Custom | 验证实现与 specs 一致性 |
/opsx:bulk-archive | Custom | 批量归档 |
/opsx:onboard | Custom | 新成员快速了解项目结构 |
八、进阶功能
8.1 动态指令生成
OpenSpec 的 AI 不靠硬编码提示词工作。每次调用斜杠命令时，AI 会运行时执行：
openspec status--json# 获取当前变更状态openspec instructions--json# 获取动态组装的操作指令这确保了 AI 的行为随项目状态自适应，而不是执行固定脚本。
8.2 可定制的 Schema 系统
通过openspec/schemas/目录，你可以自定义工作流模板。社区也提供第三方 schema bundle，类似插件生态，可以集成更多工具和工作流。
8.3 Profile 切换
如果你需要更细粒度的工作流控制：
openspec config profile# 切换到 custom profileopenspec update# 应用配置，生成额外的斜杠命令九、为什么选择 OpenSpec？
与同类工具的对比
vs. GitHub Spec Kit
Spec Kit 功能全面但偏重，有严格的阶段门控、大量 Markdown 模板和 Python 环境依赖。OpenSpec 更轻量，允许自由迭代，没有刚性阶段锁。
vs. AWS Kiro
Kiro 功能强大，但锁定了 IDE 和模型（仅支持 Claude）。OpenSpec 支持 25+ AI 工具，你可以用自己喜欢的任何工具。
vs. 什么都不用
没有规格管理的 AI 编程 = 模糊的提示词 + 不可预测的结果。OpenSpec 在不增加过多仪式感的前提下，带来了可预测性和可追踪性。
核心优势
- 先对齐再构建：人和 AI 在写代码前就 spec 达成一致
- 结构化管理：每个功能独立文件夹，proposal / specs / design / tasks 四件套
- 灵活迭代：随时修改任何产物，没有刚性阶段门控
- 工具自由：不锁定 IDE，不锁定模型，支持 25+ AI 工具
- 审计历史：每次 archive 都是完整的变更记录
十、总结
OpenSpec 填补了 AI 辅助编程中"需求管理"这一关键空白。它不是要增加你的负担，而是用轻量级的 Markdown 文件 + 结构化的 Delta Spec 机制，让 AI 编程助手的工作成果更可控、更可追踪。
三步上手，今天就试试：
npminstall-g@fission-ai/openspec@latestcdyour-project openspec init然后在你的 AI 助手中输入/opsx:propose your-first-feature，体验"先对齐再构建"的开发方式。
参考链接
- OpenSpec GitHub 仓库
- OpenSpec 官方文档