OpenSpec 从入门到精通：AI 时代的最佳 SDD 范式

一、背景与痛点：为什么需要 OpenSpec？

AICoding 领域，模型的逻辑推理能力在短小上下文中表现卓越，但在大型工程环境中，模型面临两大挑战：

• 上下文中毒：无关信息污染上下文，模型误将噪声当作重要信息
• 注意力漂移：长对话中逐渐偏离原始需求，产生幻觉或偏离预期

单纯依靠增加大语言模型的参数规模已无法解决复杂业务逻辑中的幻觉与失控问题。

OpenSpec 倡导的是一种「规格驱动开发」（Spec-Driven Development）范式。其核心理念是：在写任何一行代码之前，先由人类与 AI 共同协商并锁定一份机器可读、人可评审的规格文档。需求是什么、技术方案怎么设计、实现步骤有哪些——全部以 Markdown 文件持久化在项目里。AI 每次开工，不是从你的口头描述出发，而是从这份规格文档出发。

同样都是「先写规范再写代码」的开源 SDD 框架，OpenSpec(https://github.com/fission-ai/openspec) 展现出了极高的工程性价比，无论是使用 Claude Code、Cursor 还是 Aider，都可以无缝接入 OpenSpec 的规格管理层。OpenSpec 对存量代码库的需求场景，相当友好，相比 Spec Kit 擅长的新项目场景，对于很多公司的开发更为适合。

二、安装与初始化

2.1 安装

# 前置条件：Node.js 20.19.0+
npm install -g @fission-ai/openspec@latest

2.2 初始化

# 命令行方式进入到你的项目
cd your-project
# 初始化
openspec init

初始化时 CLI 会问你使用哪些 AI 工具（Claude Code、Cursor、Copilot 等），然后自动往对应目录写入 Skill 和斜杠命令文件。

注意：初始化完成后，需要重启 ide 才能生效。

完成后项目里多出一个 openspec/ 目录：

openspec/
├── specs/
├── changes/
└── config.yaml   # 项目配置

2.3 配置项目上下文（可选，建议配置）

这一步经常被跳过，但它对工件质量影响巨大。在 openspec/config.yaml 里告诉 AI 你的项目是什么样的：

schema: spec-driven

# Project context (项目上下文)
# 此信息将在创建各种 artifacts 时提供给 AI 参考
context: |
  ## 项目概述
  XXX 系统（Engine）是 xxx。

  核心功能：  

  ## 技术栈

  ## 模块结构

  ## 代码规范

  ## 测试规范

  ## Git提交规范

context 会注入到所有工件的生成过程中——相当于一次配置，以后再也不用在对话开头反复交代技术栈了。

可以让 AI 先生成，然后自己修改：

请阅读 openspec/config.yaml 并帮我填写项目详情、技术栈和约定等

强烈建议该规范文件在组内按照项目维度持续迭代，如果需要更新规范也尽量让 Claude 自己生成，AI 最能理解 AI 生成的规范。

三、项目结构与关键产物

openspec 结构如下：

openspec/
├── specs/        # 系统当前行为的「源真相」（Source of Truth） ← 「系统现在是什么样的」
├── changes/      # 每个变更的独立工作目录 ← 「我们打算改什么」
├── archive/      # 已完成变更的归档目录 ← 「历史记录」
└── config.yaml   # 项目配置

目录说明：

Specs（主规格） 是系统当前行为的权威描述——「源真相」。它回答的是「系统现在是怎么运作的」。

Changes（变更） 是你正在进行的修改——每个功能、每个 Bug 修复独立一个文件夹，互不干扰。它回答的是「我们打算怎么改」。

每个变更（Change）都被组织在独立的文件夹中，包含 4 个工件，它们之间有明确的依赖关系，但不是说你必须按这个顺序来。你完全可以先写 design 再补 specs，或者直接跳到 tasks，流程是灵活的。

proposal.md  →  specs/  →  design.md  →  tasks.md
 为什么做？     做什么？     怎么做？       具体步骤

• proposal.md：描述变更的初衷和范围。
• specs/：具体的逻辑规格，通常包含 “Scenario（场景）” 描述，通过具体的输入输出消除模糊性。这里存放的是 Delta Specs（增量规格），仅描述本次变更涉及的行为变化。
• design.md：技术设计方案，包括本次变更涉及的数据库变更、接口调整等。
• tasks.md：原子化的任务清单，作为 AI 的执行路径图。

四、核心命令与使用场景

OpenSpec 分为默认快速模式和扩展全量模式，新安装默认启用快速模式。

整体工作流程图：

4.1 工作流模式选择

快速模式（Core Profile）

适合简单开发场景，仅提供 4 个核心命令，流程极简：/opsx:propose → /opsx:apply → /opsx:archive

核心命令：/opsx:propose（创建变更+规划制品）、/opsx:explore（梳理思路）、/opsx:apply（实现任务）、/opsx:archive（完成变更归档）。

新手可以通过 onboard 命令学习整个工作流程。

扩展模式（Expanded Profile）

适合复杂开发、团队协作场景，包含脚手架、校验、批量操作等专属命令。

开启方式：依次执行 openspec config profile + openspec update

# 选择 workflows only
openspec config profile
# 更新，之后需要重启
openspec update

扩展模式额外支持：/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:sync、/opsx:bulk-archive 等命令。

4.2 核心命令速查