OpenSpec

什么是openSpec

OpenSpec是一种规范驱动（Spec-driven development，简称SDD）的开源开发框架，OpenSpec让需求驱动告别AI自由发挥。

它的精髓就是给AI加了一套“需求先行”的工作流。 再也不用在对话框里长篇大论解释需求，盼着AI能听懂。

为什么选择OpenSpec

核心理念

• 规范先行，减少歧义

  OpenSpec将需求、验收标准和技术细节明确化（包括功能描述、输入/输出、边界条件、测试用例等），帮你和AI助手建立一套规范驱动的开发流程，确保在写代码前，人和AI就”要做什么”达成一致。

• 原生集成，无缝协作

  它是一个命令行工具，轻量级设计，不需要复杂配置，同时支持主流AI编程工具。

• 闭环追溯，责任清晰

  每一次变更都以规范提案的形式发起，并自动归档，形成完整的审计踪迹，便于团队审查和项目管理。

  每个功能变更都有：

  • 提案文档（为什么做、做什么）
  • 设计决策（技术选型的理由）
  • 任务清单（分步骤实现）
  • 规范文档（系统应该如何工作）

• 团队友好，易于推广

  • OpenSpec不是只能用在新项目上。恰恰相反，它专门为改进现有代码（1→n）设计，而不仅仅是从零开始（0→1）。
  • 统一的md文档定义了与AI的交互指令，确保团队成员都能以一致的方式协作。

优势与对比

1. 对比Spec Kit（GitHub）——功能全面但体积庞大。它有严格的阶段门控、大量的 Markdown 代码以及 Python 配置。OpenSpec 更轻量级，允许你自由迭代。
2. 与Kiro（AWS）相比——功能强大，但你只能使用他们的 IDE，而且仅限于 Claude 模型。OpenSpec 可以与你已使用的工具兼容。
3. 与没有规范的情况相比——没有规范的AI编码意味着模糊的提示和不可预测的结果。OpenSpec无需繁琐的流程即可实现可预测性。

适用场景

• 新功能开发：从需求定义到代码实现的全流程管理。
• Bug 修复：将 Bug 描述和修复方案规范化，确保修复的完整性和可验证性。
• 遗留系统重构：为旧代码的改造提供清晰的规范和安全的实施路径（棕地开发）。
• ✅ 团队协作开发

不适用场景

• 原型快速验证：如果你只是想快速试试一个想法，直接让AI写可能更快。OpenSpec的流程会增加一些前期时间。
• 一次性脚本：写个几十行的小工具脚本，不需要OpenSpec的完整流程。
• 需求极度不明确：如果你连大概想要什么都不知道，OpenSpec帮不了你。它的价值在于帮你把想法变成清晰的规范，而不是帮你想出想法。

工作流程

┌────────┐
│ 1. 起草提案 │ 明确要做什么 /opsx:new
└────────┘
│
▼
┌────────┐
│ 2. 审查对齐 │ 人和AI达成一致（proposal，specs，design，tasks） /opsx:ff or /opsx:continue
└────────┘
│
▼
┌────────┐
│ 3. 实现任务 │ AI按规范写代码 /opsx:apply
└────────┘
│
▼
┌────────┐
│ 4. 归档更新 │ 更新项目文档 /opsx:archive
└────────┘

第1步：起草提案

你告诉AI想要什么功能，AI会：

• 询问关键细节（避免误解）
• 生成完整提案文档
• 列出实现任务清单
• 创建规范增量（spec delta）

重点：这一步不写代码，只是把需求说清楚。

第2步：审查对齐

你和AI一起审查提案：

• 需求对不对？
• 技术方案合理吗？
• 有没有遗漏的地方？

可以反复修改，直到完全满意。

第3步：实现任务

提案批准后，AI开始写代码：

• 严格按照规范实现
• 逐个完成任务清单
• 标记完成进度

如果发现问题，可以随时修复，重新测试。

第4步：归档更新

功能完成并测试通过后：

• 变更归档保存
• 规范合并到项目文档
• 系统状态更新

整个项目有了清晰的”演进历史”。

快速入门

安装Node.js

1. 进入https://nodejs.org/en/download/下载对应系统的Node.js版本，需要 Node.js 20.19.0 或更高版本。
2. 选安装目录进行安装。
3. 环境配置及测试，输入node -v 能输出正确版本号即可。

全局安装 OpenSpec

npm install -g @fission-ai/openspec@latest
# 验证安装
openspec --version

然后导航到您的项目目录并进行初始化

cd your-project
openspec init

运行后openspec init会提示要默认选择一个AI工具（OpenSpec 不是单独运行，而是挂载在 AI 编程工具之上）

此处演示选择了CodeBuddy Code (CLI)，之后按tab键确认后开始执行初始化。

初始化后，您的项目结构如下：

openspec/
├── specs/              # 规范（描述了您的系统当前的行为方式）
│   └── <domain>/
│       └── spec.md     # 功能需求和场景
├── changes/            # 变更提案（一次性，每项修改都会生成一个单独的文件夹）
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # 版本差异
│           └── <domain>/
│               └── spec.md
└── config.yaml         # 项目配置（可选）

在.codebuddy目录中会生成（如果是claude code cli的话会在.claude目录中生成）

``````sqlite
.codebuddy/
  ├── commands/
  │   └── opsx/
  │       ├── explore.md
  │       ├── new.md
  │       ├── archive.md
  │       ├── bulk-archive.md
  │       ├── continue.md
  │       ├── apply.md
  │       ├── verify.md
  │       ├── onboard.md
  │       ├── sync.md
  └──     └── ff.md
   skills/
      ├── openspec-apply-change/
      │   └── SKILL.md
      ├── openspec-explore/
      │   └── SKILL.md
      ├── openspec-verify-change/
      │   └── SKILL.md
      ├── openspec-new-change/
      │   └── SKILL.md
      ├── openspec-archive-change/
      │   └── SKILL.md
      ├── openspec-onboard/
      │   └── SKILL.md
      ├── openspec-bulk-archive-change/
      │   └── SKILL.md
      ├── openspec-continue-change/
      │   └── SKILL.md
      ├── openspec-sync-specs/
      │   └── SKILL.md
      └── openspec-ff-change/
          └── SKILL.md

---

快速功能：当你清楚自己想要构建什么，只需要执行时：

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

---

命令快速参考

命令	目的	何时使用
/opsx:explore	仔细思考各种想法	要求不明确，需调查
/opsx:new	开始改变	开始任何新的工作
/opsx:continue	创建下一个工件	逐步创建制品
/opsx:ff	创建所有规划文档	范围明确，准备开工
/opsx:apply	执行任务	准备编写代码
/opsx:verify	验证实施	归档前，找出不匹配项
/opsx:sync	合并增量规格	可选——根据需要添加存档提示
/opsx:archive	完成更改	所有工作已完成
/opsx:bulk-archive	归档多个更改	并行工作，批量完成

CodeBuddy

集成OpenSpec

1. 在CodeBuddy中初始化项目，执行/init命令，生成CODEBUDDY.md
2. 在CodeBuddy中增加Skills和rules（该步骤可选）

实战场景

省赛名单

提案（propose）

1. 使用/opsx:new命令，并输入提示词，示例如下

/opsx:new 需要实现一个竞赛名单管理功能，支持对导入考生进行管理，每批导入的考生认为是同一组。注意：该名单中支持学生和老师共同竞赛，其中学生使用学号，老师使用手机号。
需要完成的具体功能项如下：
- 分页列表查询：
1. 查询竞赛名单分组，树形结构展示分组名称，支持对分组的新增/修改/删除。
2. 筛选条件包括：学校名称、考生姓名、考生学号/手机号、状态。
3. 展示字段包括：学校名称、考生姓名、考生学号/手机号、状态，需要根据分组查询本组内的考生列表。
4. 支持重置密码，支持导入、导出。其中导入之前需要先设定分组名称，之后选择该分组进行导入。
- 新增：先点击左侧分组名称，再选择学校名称，输入姓名和学号/手机号，确认后完成新增。
- 修改：根据竞赛名单ID查询详情，对其中学生姓名、学号/手机号进行编辑。
- 启用/禁用：支持对考生的状态进行启用/禁用，规定1启用、0禁用。
- 删除：支持批量删除，该删除为逻辑删除。
最终需要输出的文档有api.md以及可在Postgresql数据库中直接执行的脚本sql，该脚本需要对每一个字段进行comment，举例：
- `COMMENT ON TABLE "public"."base_user" IS '用户表';`
最后使用技能 /openapi3-gen 将任务列表中的所有接口生成OpenAPIv3.json格式，并保存到doc目录中。

2. IDE深度思考并创建计划。
   
   与AI对话将提案需要改的地方进行变更。确认提案内容后，进入design和spec阶段：
   
   可以对design.md、tasks.md及子任务的spec.md修改进而确认后完成相应md生成。

实施（implement）

执行/opsx:apply 命令开始执行任务。

验证（validate）

归档（archive）