OpenSpec 介绍与使用：让 AI 编程从“聊天驱动”变成“规格驱动”

一、为什么需要 OpenSpecAI 编程工具越来越强但很多人在使用 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-gfission-ai/openspeclatest进入你的项目目录cdyour-project初始化 OpenSpecopenspec 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 SpecsOpenSpec 最重要的概念之一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复盘功能时可追溯设计初衷与迭代思路。更适合小步迭代不鼓励一次性堆砌大量需求支持拆分小变更独立推进开发节奏更平稳。可定制 SchemaOpenSpec 支持自定义流程模板示例命令openspec schema init research-first openspec schema fork spec-driven research-first可自由新增调研文档、ADR、安全评审等自定义文档类型。十、OpenSpec 的不足和注意点简单需求可能显得繁琐仅修改文案、调整小配置这类极小改动完整走全流程效率偏低建议简化使用或直接不用。需要团队纪律工具价值依托于规格持续同步更新代码变更后不归档、不更新主规格最终依旧会变成过期文档。依赖 AI 工具配合OpenSpec 仅为工作流与规格管理层代码落地依旧依靠 AI 编程助手与人工校验官方更推荐搭配高推理能力大模型使用。拒绝过度规格化按需使用适用复杂功能、核心模块、多人协作、长期维护业务不适用临时改动、测试实验、一次性脚本十一、一个完整使用示例需求开发用户登录功能第一步初始化项目npminstall-gfission-ai/openspeclatestcdmy-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 编程从“凭感觉生成代码”走向“按规格稳定交付”的轻量级规格驱动开发工具。