OpenSpec+SDD规范驱动AI Agent开发项目实战指南

1. 前言

当前，Cursor、Claude Code、Copilot等AI编码助手已成为开发者核心提效工具，但行业普遍存在共性痛点：AI自由发挥、随意修改代码、遗忘需求约束、对话上下文丢失，最终导致开发偏离需求、返工率居高不下。

传统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. 多方式安装与项目初始化

工具提供全局安装、本地安装、临时运行三种模式，优先推荐全局安装，适配本地所有项目使用，各包管理器完整安装命令如下：

bash 复制代码

# 方式1：全局安装（推荐，所有项目可直接调用）
npm install -g @fission-ai/openspec@latest

# 方式2：项目本地安装（仅当前项目生效）
npm install --save-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

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

bash 复制代码

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

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

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

plain 复制代码

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

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

bash 复制代码

# 1. 切换工作流为完整模式
openspec config profile

# 选择：Expanded Profile（完整工作流，启用全部命令）
# 可选：Workflows only（自定义勾选部分命令）

# 2. 刷新配置生效
openspec update

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

4. 项目核心配置

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

4.1. 完整可复用配置模板

yaml 复制代码

# 工作流模式（固定必填，规范驱动模式）
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. 核心命令与核心工件说明

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

斜杠命令	所属阶段	核心功能
/opsx:explore	探索阶段	只读模式，完成需求调研、方案 brainstorm、技术选型，不生成任何文件
/opsx:new	规划阶段	创建全新变更目录，初始化功能开发框架
/opsx:continue	规划阶段	逐一生成缺失工件、逐一审阅修改，适配复杂需求开发
/opsx:ff	规划阶段	快进模式，一次性生成提案、规范、设计、任务全量规划工件
/opsx:apply	执行阶段	依据任务清单、规范文档自动编码，落地功能开发
/opsx:verify	验证阶段	从完备性、正确性、连贯性三维度校验代码，生成验证报告
/opsx:sync	同步阶段	将新增规范合并至项目全局规范库
/opsx:archive	归档阶段	归档单个已完成变更，固化规范、更新日志
/opsx:bulk-archive	归档阶段	批量归档多组变更，自动检测并处理规范冲突

四类核心结构化工件是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三层闭环架构

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

编排层（SDD Action Skills）：统一操作入口，提供全部sdd-*命令，负责流程调度、前置校验、循环审查、产物全流程管控。
纪律层（Superpowers）：提供工程执行纪律，落地TDD开发、系统化调试、代码审查、分支管理、方案探索等核心能力，规范AI编码行为。
规范层（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. 大型复杂特性标准流程

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

bash 复制代码

# 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. 团队渐进式落地策略

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

第一阶段：基础规范落地：启用核心流程（sdd-propose → sdd-ff → sdd-plan → sdd-code → sdd-ship），建立规范先行、TDD编码、变更归档的基础习惯，解决AI乱改代码核心痛点。
第二阶段：质量审查落地：新增sdd-review-spec、sdd-review-code审查能力，在编码前后增设质量关卡，规避规范缺陷与代码质量问题。
第三阶段：全工程体系落地：补齐需求探索、全量验证能力，实现从需求探索、规划、编码、审查、验证、归档的全链路工程闭环，适配企业级复杂大型项目。

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开发领域高效、规范、可落地的企业级实战方案。

本次分享就到这儿啦，我是鹏多多，深耕前端的技术创作者，如果您看了觉得有帮助，欢迎评论，关注，点赞，转发，我们下次见~

PS：在本页按F12，在console中输入document.getElementsByClassName('panel-btn') $0$ .click();有惊喜哦~

往期文章