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

作者：袖梨 2026-06-03

AI编码助手虽大幅提升开发效率，但常因随意修改代码与上下文丢失而导致需求偏离。规范AI行为已成为开发者核心诉求。

1. 前言

当前，Cursor、Claude Code、Copilot等AI编码工具显著提升开发效率，然而行业普遍面临AI自由发挥、代码被随意修改、需求约束被遗忘以及对话上下文丢失等问题，最终致使开发偏离预期、返工率居高不下。

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

传统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开发流程，适用于个人开发与团队协作，其核心价值如下：

  1. 开发全程可控：所有代码生成与修改均严格遵循前置规范，杜绝了AI自由发挥、无效修改及逻辑幻觉问题。

  2. 全链路可追溯：每一次功能变更均留存提案、规范、设计、任务及验证报告，完整记录所有开发决策过程。

  3. 团队协作标准化：统一的工件文档体系消除了沟通歧义，新成员可依据项目规范快速上手，无需通读大量代码。

  4. 工程质量有保障：搭配Superpowers执行纪律，落地TDD开发、系统化调试及双阶段代码审查，有效规避各类低级bug与逻辑隐患。

  5. 项目资产可沉淀：每轮迭代中持续更新全局规范库，形成项目专属的动态活文档，实现长期迭代优化。

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

3.1. 前置环境要求

使用OpenSpec需要满足基础环境条件，否则会出现命令执行失败或功能异常等问题：

  1. Node.js 版本 ≥ 20.19.0

  2. 支持npm、pnpm、yarn、bun主流包管理器

  3. 适配Cursor、Claude Code、Trae、VS Code Copilot等20余款AI编辑器

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

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

# 方式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

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

# 项目根目录执行初始化
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. 核心参数释义

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

  2. context：项目全局信息配置，包含技术栈、编码规范及业务场景。AI生成文档和代码时将全程遵循该上下文约束。

  3. 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标准化开发的核心载体，它们完全替代了模糊的对话需求，全程可编辑、可校验、可追溯：

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

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

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

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

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

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

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

  2. 探索迭代模式（复杂需求/架构优化）：需求模糊、需进行技术调研，通过逐步探索和逐一审控实现。流程为：/opsx:explore → /opsx:new → /opsx:continue（多次） → /opsx:apply → /opsx:verify → /opsx:archive

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

单独使用OpenSpec仅能解决规范沉淀和变更追溯问题，无法约束AI执行行为；单纯采用Superpowers纪律开发则缺少持久化的设计共识与规范文档，这正是传统AI开发频繁出错的核心原因。二者整合能够形成完美互补：OpenSpec管控“写什么”（规范与范围），Superpowers管控“怎么做”（执行与纪律），构建出完整可控的企业级AI开发体系。

6.1. 整合核心设计理念

  1. 动作优先，灵活编排：摒弃固定强制阶段，所有sdd-*命令均为独立可调用的能力，无强制关卡。大特性走全流程，小迭代精简流程，按需灵活组合。

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

  3. 薄编排无侵入：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审查机制

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

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

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

  3. 双阶段代码审查：第一阶段进行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. 高频问题排查方案

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

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

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

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

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

OpenSpec+SDD通过规范前置与全链路追溯，从根本上解决了AI开发中的乱改代码与质量失控问题，是当前企业级AI开发的标准化范式。

相关文章

精彩推荐