OpenSpec 介绍与使用：让 AI 编程从“聊天驱动”变成“规格驱动”
一、为什么需要 OpenSpec？
AI 编程工具越来越强，但很多人在使用 AI 写代码时会遇到一个问题：需求都在聊天记录里，代码越写越快，但上下文越来越乱，最终很难判断 AI 实现的到底是不是最初想要的东西。
OpenSpec 解决的正是这个问题。
它不是一个新的 IDE，也不是一个代码生成器，而是一个面向 AI Coding Assistant 的 Spec-Driven Development（规格驱动开发，SDD）工具。它的核心思想是：先把要做什么说清楚，再让 AI 按规格去实现，最后把完成的变更沉淀回项目规格中。
OpenSpec 官方对自己的定位是：为 AI 编程助手提供一层轻量级规格层，让人和 AI 在写代码前先对齐目标、行为和边界。它支持通过 slash commands 与 20 多种 AI 助手集成，并且每个变更都会被组织到独立目录中，包含 proposal、specs、design、tasks 等文档。
二、OpenSpec 是什么？
简单来说，OpenSpec 是一个帮助你管理需求 → 设计 → 任务 → 实现 → 归档的开发工作流工具。
它会在项目中维护一个openspec/目录，大致分为两部分：
openspec/ ├── specs/ # 当前系统真实行为的规格说明 └── changes/ # 正在进行或已完成的变更其中，specs/是项目当前状态的事实来源，也就是系统现在应该如何工作的说明；changes/则保存每一次计划中的修改。OpenSpec 的文档明确说明：specs 描述当前行为，changes 描述拟议修改，变更归档时会把 delta specs 合并回主 specs。
这和普通写需求文档最大的不同在于：
- 普通文档经常写完就过期；
- OpenSpec 希望规格随着代码一起演进。
也就是说，OpenSpec 不只是“写需求”，而是让需求、设计、任务、实现和历史记录形成一个闭环。
三、OpenSpec 的核心理念
OpenSpec 的设计理念可以概括为四点：灵活、迭代、轻量、适合已有项目。官方 concepts 文档中也明确提到，它强调 fluid not rigid、iterative not waterfall、easy not complex、brownfield-first。
1. 灵活，而不是死板流程
OpenSpec 不要求你必须严格按照瀑布式流程走完所有阶段。
你可以先写 proposal，也可以在理解代码后补充 design；某些简单需求甚至可以跳过 design，直接进入 tasks。
2. 迭代，而不是一次性定稿
现实开发中，需求经常会变。AI 在阅读代码后，也可能发现之前的方案不合理。
OpenSpec 允许你在实现过程中继续更新文档，而不是把规格当成不可修改的合同。
3. 轻量，而不是复杂仪式
相比一些比较重的规格驱动工具，OpenSpec 更偏向“够用就好”。它的默认工作流是：proposal → specs → design → tasks → implement
官方文档也说明，默认的 spec-driven schema 适合大多数希望在实现前先对齐规格的功能开发。
4. 适合已有项目，而不只是新项目
OpenSpec 很强调 brownfield-first，也就是适合已有代码库。
因为大多数真实工作不是从零开始写项目，而是在已有系统上增加、修改、删除行为。OpenSpec 通过 delta specs 来描述变化，而不是每次都重写完整规格。
四、OpenSpec 的核心工作流
OpenSpec 最常见的工作流可以分成三个阶段：
Propose → Apply → Archive
也可以理解为：提出变更 → 按规格实现 → 归档并更新主规格
官方 README 的快速示例中，初始化后可以让 AI 执行/opsx:propose <what-you-want-to-build>，然后通过/opsx:apply实现任务，最后通过/opsx:archive归档变更。
五、OpenSpec 安装与初始化
OpenSpec 需要 Node.js 20.19.0 或更高版本。官方推荐通过 npm 全局安装：
npminstall-g@fission-ai/openspec@latest进入你的项目目录：
cdyour-project初始化 OpenSpec：
openspec init初始化后，项目中会生成 OpenSpec 相关目录和 AI 助手指令。之后你就可以在支持的 AI 编程工具中使用类似下面的命令：
/opsx:propose 添加用户登录功能六、常用命令说明
1. /opsx:propose
用于创建一个新的变更提案。
示例：
/opsx:propose 增加用户登录功能，支持邮箱和密码登录，并提供错误提示这一步的目标不是直接写代码，而是先让 AI 帮你整理目录结构：
openspec/changes/add-user-login/ ├── proposal.md ├── specs/ ├── design.md └── tasks.md其中 proposal.md 说明为什么要做，specs/ 描述行为变化，design.md 描述实现方案，tasks.md 拆分具体任务。
2. /opsx:apply
用于根据已经确认的 proposal、specs、design 和 tasks 进行实现。
示例：
/opsx:applyAI 会按照任务清单逐项实现，并在完成后更新任务状态。
这一步最大的价值是：AI 不再只依赖你的一句话，而是依赖已经整理好的规格和任务清单来写代码。
3. /opsx:archive
用于在功能完成后归档变更。
示例：
/opsx:archive归档时，OpenSpec 会把变更中的 delta specs 合并回openspec/specs/，并把该变更移动到openspec/changes/archive/下。官方文档说明，归档会合并 delta、移动 change 文件夹，并保留 proposal、design、tasks 等上下文，方便之后追溯为什么做这个改动。
归档后的结构类似：
openspec/ ├── specs/ │ └── auth/ │ └── spec.md └── changes/ └── archive/ └── 2026-05-19-add-user-login/ ├── proposal.md ├── design.md ├── tasks.md └── specs/七、Delta Specs：OpenSpec 最重要的概念之一
OpenSpec 的一个关键设计是 Delta Specs。
Delta Specs 不要求你重写完整系统说明，而是只描述这次变更带来的差异。
常见格式包括：
## ADDED Requirements 新增的行为 ## MODIFIED Requirements 修改的行为 ## REMOVED Requirements 删除的行为示例：
## ADDED Requirements ### Requirement: 用户邮箱登录 系统 MUST 支持用户使用邮箱和密码登录。 #### Scenario: 登录成功 - GIVEN 用户输入正确的邮箱和密码 - WHEN 用户点击登录按钮 - THEN 系统进入首页 #### Scenario: 登录失败 - GIVEN 用户输入错误的密码 - WHEN 用户点击登录按钮 - THEN 系统显示错误提示官方文档说明，Delta Specs 的价值在于清晰展示“本次到底改了什么”，减少冲突，提高评审效率，并且非常适合已有项目。归档时，ADDED 会追加到主规格，MODIFIED 会替换已有需求，REMOVED 会从主规格中删除。
八、OpenSpec 适合哪些场景？
1. AI 辅助开发
OpenSpec 很适合 Claude Code、Codex、Cursor、OpenCode 等 AI 编程工具。
规避传统对话式开发问题：
你：帮我做一个登录功能
AI：好的，我开始写
结果：实现方式和你想的不一致
使用 OpenSpec 后流程：
你：提出登录功能
AI：先生成 proposal/spec/design/tasks
你：确认或修改
AI：再按照规格实现
AI 输出会更加稳定可控。
2. 中大型功能开发
对于稍微复杂一点的需求，直接让 AI 写代码很容易遗漏边界情况。
OpenSpec 会强制你提前梳理：
- 这个功能解决什么问题？
- 有哪些用户场景？
- 哪些行为是必须支持的？
- 哪些行为不能做？
- 失败情况如何处理？
- 任务如何拆分？
3. 已有项目持续迭代
OpenSpec 的 delta 机制高度适配存量项目迭代。
日常开发大多是：
- 修改一个已有能力
- 补充一个边界场景
- 删除一个旧逻辑
- 替换一个实现方案
而非从零搭建全新模块。
4. 需要长期维护规格的项目
如果你希望项目文档不是“一次性文档”，而是能随着功能一起演进，OpenSpec 会比较合适。
它的 archive 机制可以把已完成的变更沉淀回主规格，让openspec/specs/始终尽量接近当前系统真实行为。
九、OpenSpec 的优势
降低 AI 随机发挥
AI 最怕模糊需求。OpenSpec 通过 proposal、specs、design、tasks 把需求拆清楚，AI 写代码时就不容易跑偏。让需求可评审
从只评审代码，前置为评审规格，提前排查需求不全、边界缺失、任务粒度不合理、方案不合理等问题。让历史可追溯
每个变更都会完整留存 proposal、design、tasks 和 specs，复盘功能时可追溯设计初衷与迭代思路。更适合小步迭代
不鼓励一次性堆砌大量需求，支持拆分小变更独立推进，开发节奏更平稳。可定制 Schema
OpenSpec 支持自定义流程模板，示例命令：
openspec schema init research-first openspec schema fork spec-driven research-first可自由新增调研文档、ADR、安全评审等自定义文档类型。
十、OpenSpec 的不足和注意点
简单需求可能显得繁琐
仅修改文案、调整小配置这类极小改动，完整走全流程效率偏低，建议简化使用或直接不用。需要团队纪律
工具价值依托于规格持续同步更新，代码变更后不归档、不更新主规格，最终依旧会变成过期文档。依赖 AI 工具配合
OpenSpec 仅为工作流与规格管理层，代码落地依旧依靠 AI 编程助手与人工校验，官方更推荐搭配高推理能力大模型使用。拒绝过度规格化
按需使用：
- 适用：复杂功能、核心模块、多人协作、长期维护业务
- 不适用：临时改动、测试实验、一次性脚本
十一、一个完整使用示例
需求：开发用户登录功能
第一步：初始化项目
npminstall-g@fission-ai/openspec@latestcdmy-project openspec init第二步：提出变更
在 AI 工具输入指令：
/opsx:propose 增加用户登录功能，支持邮箱密码登录、错误提示、登录状态保持自动生成完整变更目录与配套文档。
第三步：检查 proposal
核对功能目标、业务范围、排除项、整体定位是否合理。
第四步：检查 specs
确认登录成功、登录失败、参数校验、状态维持、退出登录全场景规则。
第五步：检查 tasks
任务要求粒度细小可执行，示例：
## 1. 登录页面 - [ ] 1.1 创建邮箱输入框 - [ ] 1.2 创建密码输入框 - [ ] 1.3 添加登录按钮状态 ## 2. 登录逻辑 - [ ] 2.1 调用登录接口 - [ ] 2.2 处理登录成功 - [ ] 2.3 处理登录失败 ## 3. 状态保持 - [ ] 3.1 保存 token - [ ] 3.2 启动时恢复登录态 - [ ] 3.3 支持退出登录第六步：执行实现
/opsx:applyAI 依照任务清单逐点开发。
第七步：验证（可选）
/opsx:verify校验代码实现是否严格匹配既定规格。
第八步：归档闭环
/opsx:archive变更归档入库，差异规格合并至项目主规格，完成全流程闭环。
十二、OpenSpec 和普通提示词开发的区别
普通 AI 编程
一句话需求 → AI 直接写代码 → 人工核查 → 反复返工
特点：上手快、自由度高，极易偏离预期，不适合长期维护。
OpenSpec 规格驱动开发
需求梳理 → 提案定义 → 规格编写 → 方案设计 → 任务拆分 → 代码实现 → 规格校验 → 归档沉淀
特点：前期稍慢，流程标准化，交付稳定，可追溯易维护。
总结：普通提示词适合快速试错，OpenSpec 适合正式业务落地。
十三、推荐实践
单个变更范围尽量精简
一个 change 只聚焦一个独立业务目标，不堆砌多项无关功能。提案明确划定业务边界
在 proposal 中写明功能包含内容与排除内容，示例：
## Out of Scope - 本次不支持第三方登录 - 本次不支持短信验证码 - 本次不调整用户注册流程规格多用场景化描述
优先使用 Given / When / Then 标准句式定义业务行为，对齐人与 AI 理解。拆分轻量化任务
拒绝笼统大任务，拆解为可快速完成的最小执行单元。功能上线务必执行归档
归档是规格自动迭代的核心环节，不归档无法同步最新业务规则，会造成后续规格断层。
十四、总结
OpenSpec 的核心价值并非提升代码编写速度，而是规范 AI 编程流程，统一协作认知。
它将碎片化聊天需求转化为标准化结构化规格，把临时开发动作沉淀为可追溯变更记录，让静态文档升级为和项目同步迭代的权威事实依据。
适用人群与场景
适合：AI 日常开发、复杂业务模块设计、存量项目迭代、团队多人协作、长期迭代维护项目、需要沉淀研发设计历史的技术团队。
不适合：微小临时改动、一次性测试脚本、无文档维护意愿的轻量项目。
一句话总结：
OpenSpec 是一款让 AI 编程从“凭感觉生成代码”走向“按规格稳定交付”的轻量级规格驱动开发工具。