项目介绍

OpenSpec 是由 Fission AI 开发的一个规格驱动开发工具，专为 AI 编码助手设计。它通过在编写代码前建立规格（specs）来协调人类和 AI，确保双方对要构建的内容达成一致。该工具无需 API 密钥，轻量级且易于集成，支持现有代码库的修改（brownfield-first подход）。核心目标包括：提前锁定意图、提供确定性和可审查的输出、结构化变更管理（如提案、任务和规格更新），并与各种 AI 工具兼容（如 Claude Code、Cursor 等）。

OpenSpec 的工作流程简单：起草变更提案 → 审查与对齐（反馈循环） → 实施任务（AI 编写代码） → 归档更新规格。通过 openspec/specs/ 存储当前规格源真相，openspec/changes/ 存储提案，使变更显式且易管理。

安装指南

前置要求

• Node.js 版本 ≥ 20.19.0（运行 node --version 检查）。

步骤 1: 全局安装 CLI

npm install -g @fission-ai/openspec@latest

验证安装：

openspec --version

步骤 2: 在项目中初始化 OpenSpec

进入项目目录：

cd my-project

运行：

openspec init

• 初始化过程中，会提示选择原生支持的 AI 工具（如 Claude Code、Cursor、OpenCode）；其他工具使用共享的 AGENTS.md 存根。
• 自动配置所选工具的斜杠命令，并生成项目根目录下的 AGENTS.md。
• 创建 openspec/ 目录结构。
  初始化后：
• 支持的 AI 工具可直接触发 /openspec 工作流。
• 运行 openspec list 查看设置和活跃变更。
• 如果斜杠命令未立即出现，重启 AI 工具（命令在启动时加载）。

更新 OpenSpec

1. 升级包：

   npm install -g @fission-ai/openspec@latest

2. 刷新代理指令：在每个项目运行 openspec update，重新生成 AI 指导并激活最新斜杠命令。

初级教程：快速上手

这个教程基于 README 的快速启动指南和视频演示，帮助你创建第一个变更。假设你使用一个简单的 React + Vite 项目（如构建一个 LLM 基准测试工具）。

支持的 AI 工具

OpenSpec 支持多种工具的原生斜杠命令，例如：

工具	命令示例
Claude Code	/openspec:proposal, /openspec:apply, /openspec:archive
Cursor	/openspec-proposal, /openspec-apply, /openspec-archive
OpenCode	/openspec-proposal, /openspec-apply, /openspec-archive

其他工具（如 Amp、Gemini CLI）通过 AGENTS.md 兼容。

步骤 1: 初始化并填写项目规格

• 运行 openspec init，选择你的 AI 工具（如 OpenCode）。
• 使用 AI 填写 openspec/project.md：包括项目目的、技术栈和约定。例如：

  # Project Specification

  ## Purpose
  Benchmark LLM performance with interactive charts.

  ## Tech Stack
  React, Vite, Chart.js

步骤 2: 创建第一个变更提案

向 AI 提问（或使用快捷命令）：

You: Create an OpenSpec change proposal for adding a bar chart tool with editable legends, bar colors, and light/dark mode toggle.
(Shortcut: /openspec:proposal Add bar chart tool)

AI 将生成 openspec/changes/add-bar-chart/ 文件夹，包括：

• proposal.md：变更原因和描述。
• tasks.md：实施检查列表，例如：

  ## 1. Backend Setup
  - [ ] 1.1 Add data endpoint for benchmarks

  ## 2. Frontend Implementation
  - [ ] 2.1 Create BarChart component
  - [ ] 2.2 Add color picker for bars

• specs/：规格增量（delta），如新增需求：

  # Delta for UI

  ## ADDED Requirements
  ### Requirement: Interactive Charts
  The system SHALL support editable bar colors.
  #### Scenario: Color Change
  - WHEN user selects color
  - THEN bars update immediately

步骤 3: 审查与验证

openspec list  # 查看变更文件夹
openspec validate add-bar-chart  # 检查规格格式
openspec show add-bar-chart  # 显示提案、任务和规格更新

迭代精炼：向 AI 提问“Add acceptance criteria for dark mode”，AI 更新 tasks.md 和规格。

步骤 4: 实施变更

规格批准后：

You: Implement this change.
(Shortcut: /openspec:apply add-bar-chart)

AI 按顺序处理任务，标记完成（如 Task 1.1 ✓）。监控进度：

openspec view  # 显示活跃/完成任务

步骤 5: 归档变更

实施完成后：

You: Archive the change.
(Shortcut: /openspec:archive add-bar-chart)

或手动：

openspec archive add-bar-chart --yes

这将合并更新到 openspec/specs/ 并移动文件夹到 archive/。

提示：规格格式要求使用 ### Requirement: <name> 标题、#### Scenario: 场景块，并用 SHALL/MUST 表示需求。AI 根据代码库生成文件，不要手动创建。

进阶教程：团队采用与复杂场景

进阶使用聚焦于团队协作、现有代码修改和多变更管理。OpenSpec 特别适合 brownfield 开发（修改现有功能），通过分离规格源真相和提案实现可扩展变更跟踪。

团队采用

1. 运行 openspec init 初始化项目，选择多个工具（如 Cursor 和 Claude Code）。
2. 从新功能开始：使用 AI 提案创建规格，变更归档后形成“活规格”。
3. 切换工具时运行 openspec update 刷新指令。
4. 共享可见性：所有提案、任务和 delta 保存在一个文件夹中，便于审计。

处理多个提案

• 创建独立提案（如“Fix legend position”和“Improve export resolution”）。
• 每个生成自己的任务列表。
• 应用时指定：/openspec:apply fix-legend 或批量应用。
• 测试后迭代：发现问题（如低分辨率导出）时创建新提案。

Brownfield 支持

• 修改现有规格：提案 delta 使用 ## ADDED/MODIFIED/REMOVED Requirements 格式。
• 跨规格更新：如同时修改 auth 和 UI 规格，保持变更显式。
• 与其他工具比较：优于 spec-kit（更适合 0→1 新功能）和 Kiro（变更跟踪更集中）。

命令参考

命令	描述
openspec list	查看活跃变更
openspec view	交互式仪表盘（规格与变更）
openspec show <change>	显示变更详情
openspec validate <change>	检查格式
openspec archive <change> --yes	非交互归档

与 Cursor 的结合教程

Cursor 是 OpenSpec 的原生支持工具，集成简单，通过斜杠命令无缝工作。Cursor 作为 AI 驱动的代码编辑器，能理解代码库并加速编码，与 OpenSpec 的规格驱动完美结合。

集成步骤

1. 初始化时选择 Cursor：运行 openspec init，选 Cursor 配置斜杠命令。
2. 重启 Cursor 以加载命令。
3. 在 Cursor 中使用：

• /openspec-proposal <description>：创建提案（如添加 2FA 认证）。
• /openspec-apply <change>：实施任务，Cursor 会逐一生成代码。
• /openspec-archive <change>：归档更新。

1. 迭代：Cursor 可直接编辑 tasks.md 或规格文件，结合其自然语言编辑功能精炼需求。

示例：在 Cursor 中构建功能

• 打开 Cursor 项目，运行 /openspec-proposal Add profile search filters by role and team。
• Cursor 生成文件夹，审查后用 /openspec-apply add-profile-filters 让 AI 编写代码（包括后端端点和前端 UI）。
• 测试后归档，确保规格更新合并。

Cursor 基础提示：如果新手，先熟悉 Cursor 的聊天界面和代码补全。参考 Cursor 官方文档学习自然语言提示。

其他资源

• 视频教程：
• OpenSpec: NEW Toolkit Ends Vibe Coding! Full Tutorial：完整演示，结束“氛围编码”时代，聚焦提案到实施。
• I Found the Simplest AI Dev Tool Ever：使用 OpenCode 演示 React 项目构建，覆盖多提案和迭代。
• Cursor 初学者教程：Cursor AI Tutorial for Beginners [2025 Edition]：结合 OpenSpec 使用，提升 AI 编码效率。
• GitHub 仓库：Fission-AI/OpenSpec：完整 README 和示例。