Vibe Coding - Fission-AI OpenSpec 面向 AI 编程助手的规范驱动开发

小小工匠2025-12-10 11:27

文章目录

    • Pre
    • [什么是 OpenSpec？](#什么是 OpenSpec？)
    • [OpenSpec 与其他方案的对比（概览）](#OpenSpec 与其他方案的对比（概览）)
    • 工作流程
    • 快速上手
      • [支持的 AI 工具](#支持的 AI 工具)
        • [原生斜杠命令（Slash Commands）](#原生斜杠命令（Slash Commands）)
        • [兼容 `AGENTS.md` 的工具](#兼容 AGENTS.md 的工具)
      • 安装与初始化
        • 前提条件
        • [第一步：全局安装 CLI](#第一步：全局安装 CLI)
        • [第二步：在项目中初始化 OpenSpec](#第二步：在项目中初始化 OpenSpec)
      • 创建你的第一个变更
        • [1. 起草提案](#1. 起草提案)
        • [2. 验证与评审](#2. 验证与评审)
        • [3. 优化规范](#3. 优化规范)
        • [4. 实现变更](#4. 实现变更)
        • [5. 归档已完成的变更](#5. 归档已完成的变更)
    • 命令参考
    • [示例：AI 如何生成 OpenSpec 文件](#示例：AI 如何生成 OpenSpec 文件)
      • [AI 生成的规范（位于 `openspec/specs/auth/spec.md`）：](#AI 生成的规范（位于 openspec/specs/auth/spec.md）：)
      • [AI 生成的变更增量（位于 `openspec/changes/add-2fa/specs/auth/spec.md`）：](#AI 生成的变更增量（位于 openspec/changes/add-2fa/specs/auth/spec.md）：)
      • [AI 生成的任务清单（位于 `openspec/changes/add-2fa/tasks.md`）：](#AI 生成的任务清单（位于 openspec/changes/add-2fa/tasks.md）：)
    • [理解 OpenSpec 文件格式](#理解 OpenSpec 文件格式)
    • [OpenSpec 详细对比](#OpenSpec 详细对比)
      • [vs. spec-kit](#vs. spec-kit)
      • [vs. Kiro.dev](#vs. Kiro.dev)
      • [vs. 无规范开发](#vs. 无规范开发)
    • 团队采用建议
    • [更新 OpenSpec](#更新 OpenSpec)
    • 贡献指南
    • 许可证

Pre

Vibe Coding - GitHub官方开源项目spec-kit_spec规范驱动开发

Vibe Coding - Spec Workflow MCP：打造结构化、AI 驱动的软件开发新范式

什么是 OpenSpec？

OpenSpec 是一种规范驱动开发 （Spec-Driven Development）方法，专为 AI 编程助手设计。它让你和 AI 在编写任何代码之前就对"要构建什么"达成一致，无需 API 密钥。

AI 编程助手虽然强大，但当需求仅存在于聊天历史中时，其输出往往不可预测。OpenSpec 引入了一套轻量级的规范工作流，在实现前锁定意图，从而获得确定性、可审查的输出。

核心价值

  • 人类与 AI 利益相关者在开发开始前就规范达成一致
  • 结构化的变更文件夹（提案、任务、规范更新）使范围明确且可审计
  • 共享可见性：清晰了解哪些变更处于"提案"、"活跃"或"已归档"状态
  • 兼容你已在使用的 AI 工具：支持原生斜杠命令（slash commands）的工具可直接使用；其他工具则通过上下文规则集成

OpenSpec 与其他方案的对比（概览）

  • 轻量级：流程简单、无需 API 密钥、设置极少
  • 面向存量项目 （Brownfield-first）：不仅适用于从零到一（0→1）的新功能，更擅长处理对已有行为的修改（1→n）。OpenSpec 将"事实源"与"提案"分离：
    • openspec/specs/：当前的事实源（已批准的规范）
    • openspec/changes/：提议的更新（待评审的变更）
      这种设计使跨多个规范的变更差异清晰、易于管理。
  • 变更追踪：提案、任务和规范增量（delta）集中存放；归档操作会将已批准的更新合并回规范源。
  • vs. spec-kit 与 Kiro ：
    • spec-kit 和 Kiro 在全新功能（0→1）场景下表现优异；
    • OpenSpec 在修改现有行为 （1→n）和跨多个规范的更新场景中更具优势。

详见 [OpenSpec 详细对比](#OpenSpec 详细对比)。

工作流程

text 复制代码 
┌────────────────────┐
│ 起草变更提案       │
└────────┬───────────┘
         │ 与 AI 共享意图
         ▼
┌────────────────────┐
│ 评审与对齐         │
│（编辑规范/任务）   │◀──── 反馈循环 ──────┐
└────────┬───────────┘                    │
         │ 批准的计划                      │
         ▼                                │
┌────────────────────┐                    │
│ 执行任务           │────────────────────┘
│（AI 编写代码）     │
└────────┬───────────┘
         │ 发布变更
         ▼
┌────────────────────┐
│ 归档并更新规范     │
│（更新事实源）      │
└────────────────────┘
  1. 起草变更提案：描述你希望更新的规范内容。
  2. 与 AI 评审对齐：反复迭代，直到人类与 AI 对规范达成一致。
  3. 执行任务：基于已批准的规范，由 AI 实现具体任务。
  4. 归档变更 ：将已批准的更新合并回 openspec/specs/，成为新的事实源。

快速上手

支持的 AI 工具

原生斜杠命令（Slash Commands）

以下工具内置 OpenSpec 命令，使用时请选择 OpenSpec 集成：

工具 命令
Claude Code /openspec:proposal, /openspec:apply, /openspec:archive
Cursor /openspec-proposal, /openspec-apply, /openspec-archive
Factory Droid /openspec-proposal, /openspec-apply, /openspec-archive（配置路径：.factory/commands/）
OpenCode /openspec-proposal, /openspec-apply, /openspec-archive
Kilo Code /openspec-proposal.md, /openspec-apply.md, /openspec-archive.md（配置路径：.kilocode/workflows/）
Windsurf /openspec-proposal, /openspec-apply, /openspec-archive（配置路径：.windsurf/workflows/）
Codex /openspec-proposal, /openspec-apply, /openspec-archive（全局路径：~/.codex/prompts，自动安装）
GitHub Copilot /openspec-proposal, /openspec-apply, /openspec-archive（配置路径：.github/prompts/）
Amazon Q Developer @openspec-proposal, @openspec-apply, @openspec-archive（配置路径：.amazonq/prompts/）
Auggie (Augment CLI) /openspec-proposal, /openspec-apply, /openspec-archive（配置路径：.augment/commands/）

提示 ：Kilo Code 会自动发现团队工作流。将生成的文件保存在 .kilocode/workflows/ 下，并通过命令面板触发 /openspec-proposal.md 等命令。

兼容 AGENTS.md 的工具

以下工具会自动读取项目根目录下的 openspec/AGENTS.md 文件中的工作流说明。如需提醒 AI 遵循 OpenSpec 流程，可直接告知。

工具
Amp • Jules • Gemini CLI • 其他

了解更多关于 AGENTS.md 约定。

安装与初始化

前提条件
  • Node.js >= 20.19.0
    通过 node --version 检查版本
第一步：全局安装 CLI
bash 复制代码 
npm install -g @fission-ai/openspec@latest

验证安装：

bash 复制代码 
openspec --version
第二步：在项目中初始化 OpenSpec

进入项目目录：

bash 复制代码 
cd my-project

运行初始化命令：

bash 复制代码 
openspec init

初始化过程会：

  • 提示你选择支持的 AI 工具（如 Claude Code、Cursor 等）；未列出的工具将统一使用 AGENTS.md
  • 自动为所选工具配置斜杠命令，并在项目根目录生成受管理的 AGENTS.md 文件
  • 创建 openspec/ 目录结构

初始化完成后：

  • 主要 AI 工具可直接使用 /openspec 工作流，无需额外配置
  • 运行 openspec list 验证设置并查看活跃变更
  • 若 AI 助手未立即显示新命令，请重启它（斜杠命令通常在启动时加载）

创建你的第一个变更

以下是一个完整的 OpenSpec 工作流示例，适用于任何 AI 工具（支持斜杠命令的工具会自动识别快捷方式）。

1. 起草提案

向 AI 请求创建变更提案：

text 复制代码 
你：请为"按角色和团队添加个人资料搜索过滤器"创建一个 OpenSpec 变更提案
     （支持斜杠命令的工具快捷方式：/openspec:proposal Add profile search filters）

AI：我将为个人资料过滤器创建一个 OpenSpec 变更提案。
     *在 openspec/changes/add-profile-filters/ 下生成 proposal.md、tasks.md 和规范增量文件*
2. 验证与评审

检查变更是否正确创建并审阅提案：

bash 复制代码 
$ openspec list                             # 确认变更文件夹存在
$ openspec validate add-profile-filters     # 验证规范格式
$ openspec show add-profile-filters         # 查看提案、任务和规范增量
3. 优化规范

迭代规范直至满足需求：

text 复制代码 
你：能否为角色和团队过滤器添加验收标准？

AI：我将更新规范增量，加入角色和团队过滤器的场景。
     *编辑 openspec/changes/add-profile-filters/specs/profile/spec.md 和 tasks.md*
4. 实现变更

规范确认无误后，开始实现：

text 复制代码 
你：规范看起来不错，开始实现这个变更吧。
     （快捷方式：/openspec:apply add-profile-filters）

AI：我将执行 add-profile-filters 变更中的任务。
     *根据 openspec/changes/add-profile-filters/tasks.md 实现任务*
     *标记任务完成：Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...*
5. 归档已完成的变更

实现完成后，归档变更：

text 复制代码 
AI：所有任务已完成，实现就绪。

你：请归档此变更
     （快捷方式：/openspec:archive add-profile-filters）

AI：我将归档 add-profile-filters 变更。
    *执行：openspec archive add-profile-filters --yes*
     ✓ 变更已成功归档。规范已更新。准备开始下一个功能！

或手动在终端执行：

bash 复制代码 
$ openspec archive add-profile-filters --yes  # 无交互式归档已完成的变更

注意：Claude Code、Cursor、Codex 等支持原生斜杠命令的工具可直接使用快捷方式；其他工具则可通过自然语言请求"创建 OpenSpec 提案"、"应用 OpenSpec 变更"或"归档变更"。

命令参考

bash 复制代码 
openspec list               # 查看活跃的变更文件夹
openspec view               # 交互式仪表盘，展示规范与变更
openspec show <change>      # 显示变更详情（提案、任务、规范更新）
openspec validate <change>  # 检查规范格式与结构
openspec archive <change> [--yes|-y]   # 将已完成的变更移入归档（使用 --yes 跳过确认）

示例：AI 如何生成 OpenSpec 文件

当你要求 AI 助手"添加双因素认证（2FA）"时，它会自动生成以下结构：

复制代码 
openspec/
├── specs/
│   └── auth/
│       └── spec.md           # 当前认证规范（若存在）
└── changes/
    └── add-2fa/              # AI 自动生成整个结构
        ├── proposal.md       # 变更原因与内容
        ├── tasks.md          # 实现清单
        ├── design.md         # 技术决策（可选）
        └── specs/
            └── auth/
                └── spec.md   # 规范增量（delta）

AI 生成的规范（位于 openspec/specs/auth/spec.md）：

markdown 复制代码 
# 认证规范

## 目的
身份验证与会话管理。

## 需求
### Requirement: 用户认证
系统在用户成功登录后 SHALL 发放 JWT。

#### Scenario: 有效凭证
- WHEN 用户提交有效凭证
- THEN 返回 JWT

AI 生成的变更增量（位于 openspec/changes/add-2fa/specs/auth/spec.md）：

markdown 复制代码 
# 认证规范增量

## ADDED Requirements
### Requirement: 双因素认证
系统在登录过程中 MUST 要求第二重验证因子。

#### Scenario: 需要 OTP
- WHEN 用户提交有效凭证
- THEN 必须进行 OTP 挑战

AI 生成的任务清单（位于 openspec/changes/add-2fa/tasks.md）：

markdown 复制代码 
## 1. 数据库设置
- [ ] 1.1 在 users 表中添加 OTP 密钥列
- [ ] 1.2 创建 OTP 验证日志表

## 2. 后端实现  
- [ ] 2.1 添加 OTP 生成端点
- [ ] 2.2 修改登录流程以要求 OTP
- [ ] 2.3 添加 OTP 验证端点

## 3. 前端更新
- [ ] 3.1 创建 OTP 输入组件
- [ ] 3.2 更新登录流程 UI

重要提示 ：这些文件无需手动创建，AI 助手会根据你的需求和现有代码库自动生成。

理解 OpenSpec 文件格式

增量（Delta）格式

增量文件是"补丁"，用于展示规范如何变化：

  • ## ADDED Requirements：新增功能
  • ## MODIFIED Requirements：行为变更（需包含完整更新后的文本）
  • ## REMOVED Requirements：已弃用的功能

格式要求：

  • 使用 ### Requirement: <名称> 作为标题
  • 每个需求必须至少包含一个 #### Scenario: 块
  • 需求文本中使用 SHALL 或 MUST

OpenSpec 详细对比

vs. spec-kit

OpenSpec 的双文件夹模型（openspec/specs/ 存放当前事实，openspec/changes/ 存放提议更新）将状态与差异分离。这在修改现有功能或跨多个规范更新时更具扩展性。spec-kit 在全新项目（0→1）中表现优秀，但在跨规范更新和功能演进方面结构较弱。

vs. Kiro.dev

OpenSpec 将每个功能的所有变更（规范、任务、设计）集中在一个文件夹中（如 openspec/changes/feature-name/），便于追踪。而 Kiro 将更新分散在多个规范文件夹中，可能导致功能追踪困难。

vs. 无规范开发

没有规范时，AI 编程助手仅凭模糊提示生成代码，常遗漏需求或引入不必要功能。OpenSpec 通过在编码前对行为达成一致，带来可预测性。

团队采用建议

  1. 初始化 OpenSpec ：在仓库中运行 openspec init
  2. 从新功能开始：要求 AI 将新工作以变更提案形式捕获
  3. 渐进式演进：每次变更归档后，都会更新为"活文档"，持续记录系统规范
  4. 保持灵活性 ：不同成员可使用 Claude Code、Cursor 或任何兼容 AGENTS.md 的工具，同时共享同一套规范

当团队成员切换工具时，运行 openspec update 以确保 AI 获取最新的指令和斜杠命令绑定。

更新 OpenSpec

  1. 升级包

    bash 复制代码 
    npm install -g @fission-ai/openspec@latest

  2. 刷新 AI 指令

    • 在每个项目中运行 openspec update，重新生成 AI 指导文件，确保使用最新斜杠命令

贡献指南

  • 安装依赖：pnpm install
  • 构建：pnpm run build
  • 测试：pnpm test
  • 本地开发 CLI：pnpm run dev 或 pnpm run dev:cli
  • 提交规范：使用 Conventional Commits，格式为 type(scope): subject（单行）

许可证

MIT License

相关推荐
爱勤海之旅2 年前
iOS 搭建组件化私有库
ios·cocoapods·spec·本地私有库
热门推荐
01GitHub 镜像站点02【超详细教程】手把手教你从微软官网免费下载Windows 10官方原版ISO镜像（2025最新版）03安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）04UV安装并设置国内源05Linux下V2Ray安装配置指南06BongoCat - 跨平台键盘猫动画工具07React CVE-2025-55182漏洞排查与修复指南08本地部署阿里最新开源的Z-Image09从入门到实战：Gemini 3 使用指南速览10在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）