1. 前言

聊聊当前AI编码助手的现状——Cursor、Claude Code、Copilot这些工具确实帮了不少忙，但有一个问题始终绕不开：AI太爱自由发挥了。动不动就改点不该改的代码、忘记你刚说过的约束、对话上下文一长就丢了关键信息……最后开发越走越偏，返工率居高不下。

传统玩法完全依赖对话窗口那点临时记忆——没有固定规范、没有可追溯的开发记录、也没有前置需求约定。结果就是代码质量看运气、需求说偏就偏、迭代效率越往后越差。

OpenSpec规范驱动开发（SDD） 正好打中这些痛点。它的核心思想很干脆：Spec First, Code Later——先定规范，再写代码。把AI开发从“对话驱动”的老路，拉到了“文档规范驱动”的新轨道上。AI不再是那个随性创作的代码生成器，而是变成一个守规矩、可追溯、高质量输出的标准化协作者。

这篇文章会基于官方完整文档，从零拆解OpenSpec+SDD的完整实战体系，涵盖环境部署、项目配置、核心命令、全流程实操、高阶工作流整合以及场景最佳实践。一句话总结：这是一套可以直接拿过去用的企业级AI开发规范指南。

2. 核心价值

2.1. 核心工具与开发理念

OpenSpec是Fission-AI团队开源的轻量级规范驱动开发工具，基于TypeScript构建，兼容20多款主流AI编码工具——它是SDD开发模式的主心骨。跟普通代码生成工具不一样，它的核心能力聚焦在规范管控、流程约束、变更追溯上，目标就是统一人和AI的开发共识，从源头掐掉AI幻觉、乱改代码、需求偏差这些毛病。零侵入项目结构、支持自定义工作流、全链路文档沉淀、适配棕地迭代、兼容主流AI编辑器，这些都是它的硬核特性。

SDD（Spec-Driven Development）是配合OpenSpec使用的核心开发理念，八字方针：先约定，后编码，先固化规范，再执行开发。这彻底碘伏了传统的“构思-编写-反复改码”那种无序模式，重构出一套标准化闭环：需求探索→规范定义→方案设计→任务拆解→编码实现→规范校验→归档沉淀。靠结构化工件文档，把所有的需求约束、技术决策、边界条件都永久固化在项目文件里，再也不依赖AI的对话记忆——信息丢失、开发偏差的问题从根本上解决了。

2.2. 核心落地价值

OpenSpec+SDD这套组合拳，能全方位优化AI开发流程，不管是个人开发还是团队协作都能用。核心价值主要在下面几点：

• 开发全程可控：所有代码生成和修改都要严格遵循前置规范，AI自由发挥、无效修改、逻辑幻觉这些问题全被挡在门外。

• 全链路可追溯：每次功能变更都留存提案、规范、设计、任务、验证报告，所有决策过程清清楚楚。

• 团队协作标准化：统一的工件文档体系消除沟通歧义，新成员看看项目规范就能快速上手，不用通读海量代码。

• 工程质量有保障：搭配Superpowers执行纪律，落地TDD开发、系统化调试、双阶段代码审查，低级bug和逻辑隐患基本能规避掉。

• 项目资产可沉淀：每轮迭代都在更新全局规范库，形成项目专属的动态活文档，长期迭代越用越好。

3. 环境部署与项目初始化

3.1. 前置环境要求

用OpenSpec之前，得先把基础环境搭好，不然命令执行失败、功能异常这些麻烦事少不了：

• Node.js 版本 ≥ 20.19.0

• 支持npm、pnpm、yarn、bun这些主流包管理器

• 适配Cursor、Claude Code、Trae、VS Code Copilot等20多个AI编辑器

3.2. 多方式安装与项目初始化

工具提供了全局安装、本地安装、临时运行三种模式。最推荐全局安装，这样本地所有项目都能直接用。各包管理器的完整安装命令如下：

# 方式1：全局安装（推荐，所有项目可直接调用）
npm install -g @fission-ai/openspec@latest# 方式2：项目本地安装（仅当前项目生效）
npm install --sa ve-dev @fission-ai/openspec# 方式3：临时运行（无需安装，直接初始化项目）
npx @fission-ai/openspec init# 其他包管理器安装命令
pnpm add -g @fission-ai/openspec@latest
yarn global add @fission-ai/openspec@latest
bun add -g @fission-ai/openspec@latest

核心要求：所有初始化操作必须在项目根目录执行，避免目录结构生成异常。初始化核心命令：

# 项目根目录执行初始化
openspec init

3.3. 初始化目录结构与完整工作流解锁

初始化完成后，项目里会生成OpenSpec的核心目录和配置文件。所有的规范、变更、开发工件都统一归档管理，标准目录结构如下：

your-project/
├── openspec/
│   ├── config.yaml        # 项目核心配置文件（自定义工作流、规则）
│   ├── specs/             # 全局永久规范库（项目活文档）
│   │   └── /spec.md  # 按业务模块拆分的规范文档
│   ├── changes/           # 所有开发变更的工件存储目录
│   │   ├── / # 活跃中未归档的功能变更
│   │   └── archive/       # 已完成归档的历史变更（按日期存储）
│   └── schemas/           # 自定义工作流模板、工件约束规则
└── .claude/skills/        # 自动生成的AI技能文件，适配编辑器斜杠命令

工具初始化后默认只开放4个核心命令，得手动切换配置才能解锁全部11个完整工作流命令，适配全场景开发：

# 1. 切换工作流为完整模式
openspec config profile# 选择：Expanded Profile（完整工作流，启用全部命令）
# 可选：Workflows only（自定义勾选部分命令）# 2. 刷新配置生效
openspec update

必做操作：配置更新后重启AI编辑器，就能正常使用所有 /opsx 斜杠命令了。

4. 项目核心配置

config.yaml是OpenSpec的核心配置文件，支持自定义工作流模式、项目全局上下文、工件生成规则，可以统一AI输出风格，适配项目专属的技术栈和业务场景。下面是一个可以直接复制使用的完整配置模板，附带核心参数释义：

4.1. 完整可复用配置模板

# 工作流模式（固定必填，规范驱动模式）
schema: spec-driven# 项目全局上下文（注入所有工件文档，AI全局生效）
context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e
  Code Style: ESLint + Prettier, strict TypeScript
  Business: 前端业务系统，面向用户端功能开发# 各阶段工件自定义生成规则
rules:
  # 变更提案规则
  proposal:
    - 中文编写，简洁清晰，不超过800字
    - 必须包含回滚方案、影响范围、验收标准
  # 规范文档规则
  specs:
    - 所有场景使用 Given/When/Then BDD 格式
    - 明确边界条件、异常处理、返回参数
  # 技术设计规则
  design:
    - 复杂流程必须包含时序图、模块划分
    - 技术选型必须写明理由与优缺点
  # 任务清单规则
  tasks:
    - 单任务耗时控制在1-2小时
    - 标注优先级 P0/P1/P2
    - 绑定对应spec规范场景

4.2. 核心参数释义

• schema：必填固定参数，统一为spec-driven，定义SDD规范驱动工作流模式。

• context：项目全局信息配置，包括技术栈、编码规范、业务场景。AI在生成文档和代码时会全程遵循这个上下文约束。

• rules：自定义各开发阶段工件的生成规则，强制AI按照团队标准化规范输出内容，统一项目代码和文档风格。

5. OPSX灵活动作工作流：核心命令与开发模式

OpenSpec新版采用OPSX动作式工作流，不再像以前那样必须走固定阶段，而是支持灵活组合命令，能适配从简单bug修复到中型功能迭代，再到大型复杂架构重构的所有开发场景——全程可控，灵活高效。

5.1. 核心命令与核心工件说明

九大核心斜杠命令覆盖开发全流程，各司其职，完整闭环。功能对比如下：

四类核心结构化工件是AI标准化开发的核心载体，它们替代了模糊的对话需求，全程可编辑、可校验、可追溯：

• proposal.md（提案）：定义需求本质，明确开发目的、开发范围、核心内容和验收标准。

• specs（规范）：人与AI的开发契约，定义接口、数据结构、业务场景、边界条件——代码实现的唯一标准。

• design.md（设计）：技术落地方案，包含模块划分、技术选型、依赖关系、核心逻辑流程。

• tasks.md（任务）：最小可执行开发清单，AI严格按清单编码，杜绝越界修改、超额开发。

5.2. 两种适配全场景的开发模式

针对不同需求复杂度，提供两套标准化流程，兼顾开发效率和工程质量：

• 快速迭代模式（简单需求/BUG修复）：需求清晰、改动范围小，极速落地。流程：/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive

• 探索迭代模式（复杂需求/架构优化）：需求模糊、需要技术调研，逐步探索、逐一审控。流程：/opsx:explore → /opsx:new → /opsx:continue（多次） → /opsx:apply → /opsx:verify → /opsx:archive

6. 高阶整合：OpenSpec+Superpowers企业级工作流

单独用OpenSpec能解决规范沉淀和变更追溯的问题，但约束不了AI的执行行为；单靠Superpowers纪律开发，又缺少持久化的设计共识和规范文档——这也是传统AI开发频繁翻车的核心原因。把二者整合起来，正好完美互补：OpenSpec管控“写什么”（规范与范围），Superpowers管控“怎么做”（执行与纪律），构建完整可控的企业级AI开发体系。

6.1. 整合核心设计理念

• 动作优先，灵活编排：不再固定必须走哪几个阶段，所有sdd-*命令都是独立可调用的能力，没有强制关卡。大特性走全流程，小迭代精简流程，按需灵活组合。

• 产物接力，永久持久化：所有开发状态都落地到项目文件中，不依赖对话记忆。清空上下文也不会丢失任何决策信息，上下文溢出、记忆丢失的问题彻底解决。完整链路：brainstorm.md → proposal.md → specs → design.md → tasks.md → plan.md → 代码实现 → 验证报告 → 归档资产

• 薄编排无侵入：SDD是上层编排层，不修改底层工具的源码和配置，只负责能力调度和流程管控。底层工具可以独立迭代升级，没有版本耦合风险，稳定性很强。

6.2. SDD三层闭环架构

整合后的体系分为三层，层层约束、职责清晰，构建标准化质量闭环：

1. 编排层（SDD Action Skills）：统一操作入口，提供全部sdd-*命令，负责流程调度、前置校验、循环审查、产物全流程管控。

2. 纪律层（Superpowers）：提供工程执行纪律，落地TDD开发、系统化调试、代码审查、分支管理、方案探索这些核心能力，规范AI编码行为。

3. 规范层（OpenSpec）：提供工件模板、规范约束、变更管理、归档同步能力，锁定开发范围和开发契约。

6.3. 工件依赖与核心分工

体系明确区分必需和可选工件，兼顾规范性与灵活性：proposal.md、specs、tasks.md是必需工件，所有变更都必须配置，保障开发有据可依；brainstorm.md、design.md、plan.md是可选工件，简单迭代可以跳过，复杂特性则必须补充。

特别区分两个容易搞混的核心工件：tasks.md由OpenSpec生成，是需求级任务清单，定义“做什么”，绑定规范场景、明确验收依据；plan.md由Superpowers生成，是分钟级的实操步骤，定义“怎么做”，包含完整的TDD编码、测试、验证流程。

7. SDD核心质量保障体系

7.1. 双层Review审查机制

通过自动内嵌审查和手动独立审查双重机制，从源头规避规范漏洞和代码缺陷，遵循“先做对、再做好”的原则。

• 内嵌自动审查：内置在流程动作中，不需要手动触发，完成即自检，包括方案完整性校验、任务粒度与TDD步骤合规校验。

• 手动独立审查：适配中大型特性，包括规范专项审查（校验需求完整性、场景覆盖率）、双阶段代码审查（核心流程）。

• 双阶段代码审查：第一阶段是Spec合规审查，校验代码完全匹配规范要求，没有漏实现、没有错实现；第二阶段是质量审查，校验代码可读性、架构合理性、性能与潜在bug。

7.2. 信息丢失防护与上下文规范

通过模板强制追溯、后置自动校验、全链路引用绑定，让所有开发决策都可逆向追溯，彻底解决多轮迭代、清空上下文后关键信息丢失的问题。

同时确立动作完成即清空上下文的核心使用习惯：所有开发状态永久留存项目文件，对话历史只做临时交互。只有sdd-brainstorm、sdd-plan、sdd-code这三类交互式动作，禁止中途清空上下文，避免打断开发迭代流程。

8. 全场景落地实战流程

8.1. 大型复杂特性标准流程

适用于新功能开发、架构迭代、复杂逻辑重构，全程可控可追溯：

# 1. 深度探索需求与技术方案
sdd-brainstorm
/clear# 2. 快速生成全套规划工件
sdd-ff
/clear# 3. 规范专项深度审查（大特性必做）
sdd-review-spec
/clear# 4. 细化TDD分钟级实施计划
sdd-plan
/clear# 5. 分批次TDD编码落地
sdd-code
/clear# 6. 单批次代码质量审查
sdd-review-code
/clear# 7. 循环编码+审查，直至全部任务完成# 8. 全维度最终合规验证
sdd-verify
/clear# 9. 同步全局规范+归档完整变更
sdd-ship

8.2. 小型迭代/BUG修复轻量化流程

精简冗余环节，保留核心规范，兼顾效率与质量。适用于简单迭代、线上bug修复、小范围调整：

sdd-propose → clear → sdd-ff → clear → sdd-plan → clear → sdd-code → clear → sdd-ship

ship动作内置了最终验证和规范同步能力，不需要额外执行冗余命令。

8.3. 智能下一步引导

所有SDD动作执行完成后，系统会自动根据开发进度推送最优的下一步操作，不用人工记忆流程，新手也能零失误落地全流程开发。

9. 团队渐进式落地策略

不需要一次性落地全部能力，分三阶段渐进接入，每个阶段都能独立产生落地价值，适配个人开发者和不同规模团队：

1. 第一阶段：基础规范落地：启用核心流程（sdd-propose → sdd-ff → sdd-plan → sdd-code → sdd-ship），建立规范先行、TDD编码、变更归档的基础习惯，解决AI乱改代码这个核心痛点。

2. 第二阶段：质量审查落地：新增sdd-review-spec、sdd-review-code审查能力，在编码前后增设质量关卡，规避规范缺陷和代码质量问题。

3. 第三阶段：全工程体系落地：补齐需求探索、全量验证能力，实现从需求探索、规划、编码、审查、验证、归档的全链路工程闭环，适配企业级复杂大型项目。

10. 高频问题排查方案

• 编辑器不显示 /opsx 命令：执行openspec update刷新配置 → 重启AI编辑器 → 检查项目根目录openspec核心文件夹是否存在 → 确认AI工具支持斜杠命令能力。

• /opsx:ff 与 /opsx:continue 选型：需求清晰、改动简单、紧急迭代优先用/opsx:ff，一键生成工件提速开发；需求模糊、复杂重构、高风险变更优先用/opsx:continue，逐一审控、精准把控质量。

• sync与archive/ship规范同步区别：sdd-sync只同步规范到全局库，变更保持活跃可以继续迭代；sdd-archive、sdd-ship会自动执行sync同步，同时归档冻结变更、更新项目日志，标记迭代完成。

• 新旧变更复用判定标准：需求核心不变、仅细节调整、小幅优化，复用现有变更；核心需求变更、业务领域不同、功能大幅扩张、旧变更已归档，需要新建变更迭代。

11. 总结：AI时代标准化开发新范式

OpenSpec+SDD规范驱动开发，不是单纯的工具命令集合，而是AI原生开发的标准化工程范式。传统AI开发依赖人工兜底、迁就AI的随机性，质量和效率很难兼得；而SDD开发模式实现了人定规则、AI守规则、流程保质量、文档沉资产的全新开发逻辑。

通过规范前置、纪律约束、全链路追溯、分层审查、永久沉淀这套完整体系，从根源解决了AI乱改代码、需求跑偏、质量不可控、协作没标准的行业痛点。搭配Superpowers工程执行纪律之后，这套工作流能全面适配个人开发、团队协作、大型项目迭代等所有场景——可以说是当前AI开发领域高效、规范、可落地的企业级实战方案。