技术文档

主题

OpenSpec ​

OpenSpec 通过规范驱动开发（Spec-driven Development）让人类和 AI 编码助手在编写代码之前就达成共识。无需 API 密钥。

为什么选择 OpenSpec？ ​

AI 编码助手功能强大，但当需求只存在于聊天记录中时，输出往往不可预测。OpenSpec 添加了一个轻量级的规范工作流，在实现之前锁定意图，为你提供确定性、可审查的输出。

核心价值：

  • 人类和 AI 在工作开始前就规范达成一致
  • 结构化的变更文件夹（提案、任务和规范更新）使范围明确且可审计
  • 共享可见性：了解哪些是提议的、活跃的或已归档的
  • 与你已经使用的 AI 工具配合：支持自定义斜杠命令的工具可直接使用，其他工具通过上下文规则使用

OpenSpec 特点概览 ​

  • 轻量级：简单的工作流，无需 API 密钥，最小化设置
  • 存量项目优先：不仅适用于从 0 到 1 的新项目。OpenSpec 将真实来源与提案分离：openspec/specs/（当前真实状态）和 openspec/changes/（提议的更新）。这使得跨功能的差异明确且可管理
  • 变更追踪：提案、任务和规范增量放在一起；归档时将批准的更新合并回规范
  • 与 spec-kit 和 Kiro 对比：它们在全新功能（0→1）方面表现出色。OpenSpec 在修改现有行为（1→n）时同样出色，特别是当更新跨越多个规范时

工作原理 ​

┌────────────────────┐
│ 起草变更           │
│ 提案               │
└────────┬───────────┘
         │ 与 AI 分享意图
         ▼
┌────────────────────┐
│ 审核与对齐         │
│ (编辑规范/任务)    │◀──── 反馈循环 ──────┐
└────────┬───────────┘                     │
         │ 批准的计划                       │
         ▼                                 │
┌────────────────────┐                     │
│ 实现任务           │─────────────────────┘
│ (AI 编写代码)      │
└────────┬───────────┘
         │ 交付变更
         ▼
┌────────────────────┐
│ 归档并更新         │
│ 规范（源）         │
└────────────────────┘

1. 起草一个变更提案，捕获你想要的规范更新
2. 与 AI 助手一起审核提案，直到达成一致
3. 实现引用已商定规范的任务
4. 归档变更，将批准的更新合并回真实来源规范

快速开始 ​

支持的 AI 工具 ​

原生斜杠命令支持 ​

以下工具内置了 OpenSpec 命令。在提示时选择 OpenSpec 集成即可。

工具命令
Amazon Q Developer@openspec-proposal, @openspec-apply, @openspec-archive (.amazonq/prompts/)
Antigravity/openspec-proposal, /openspec-apply, /openspec-archive (.agent/workflows/)
Auggie (Augment CLI)/openspec-proposal, /openspec-apply, /openspec-archive (.augment/commands/)
Claude Code/openspec:proposal, /openspec:apply, /openspec:archive
Cline工作流位于 .clinerules/workflows/ 目录 (.clinerules/workflows/openspec-*.md)
CodeBuddy Code (CLI)/openspec:proposal, /openspec:apply, /openspec:archive (.codebuddy/commands/)
Codex/openspec-proposal, /openspec-apply, /openspec-archive (全局: ~/.codex/prompts)
CoStrict/openspec-proposal, /openspec-apply, /openspec-archive (.cospec/openspec/commands/)
Crush/openspec-proposal, /openspec-apply, /openspec-archive (.crush/commands/openspec/)
Cursor/openspec-proposal, /openspec-apply, /openspec-archive
Factory Droid/openspec-proposal, /openspec-apply, /openspec-archive (.factory/commands/)
Gemini CLI/openspec:proposal, /openspec:apply, /openspec:archive (.gemini/commands/openspec/)
GitHub Copilot/openspec-proposal, /openspec-apply, /openspec-archive (.github/prompts/)
iFlow (iflow-cli)/openspec-proposal, /openspec-apply, /openspec-archive (.iflow/commands/)
Kilo Code/openspec-proposal.md, /openspec-apply.md, /openspec-archive.md (.kilocode/workflows/)
OpenCode/openspec-proposal, /openspec-apply, /openspec-archive
Qoder (CLI)/openspec:proposal, /openspec:apply, /openspec:archive (.qoder/commands/openspec/)
Qwen Code/openspec-proposal, /openspec-apply, /openspec-archive (.qwen/commands/)
RooCode/openspec-proposal, /openspec-apply, /openspec-archive (.roo/commands/)
Windsurf/openspec-proposal, /openspec-apply, /openspec-archive (.windsurf/workflows/)

AGENTS.md 兼容工具 ​

以下工具会自动从 openspec/AGENTS.md 读取工作流指令。如果需要提醒，可以让它们遵循 OpenSpec 工作流。

工具
Amp • Jules • 其他

安装与初始化 ​

前置条件 ​

  • Node.js >= 20.19.0 - 使用 node --version 检查版本

步骤 1：全局安装 CLI ​

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

验证安装：

bash
openspec --version

步骤 2：在项目中初始化 OpenSpec ​

进入项目目录：

bash
cd my-project

运行初始化：

bash
openspec init

初始化过程中会发生什么：

  • 系统会提示你选择原生支持的 AI 工具（Claude Code、CodeBuddy、Cursor、OpenCode、Qoder 等）；其他助手始终依赖共享的 AGENTS.md 存根
  • OpenSpec 会自动为你选择的工具配置斜杠命令，并始终在项目根目录写入一个托管的 AGENTS.md 交接文件
  • 在项目中创建新的 openspec/ 目录结构

设置完成后：

  • 主要 AI 工具可以无需额外配置即可触发 /openspec 工作流
  • 运行 openspec list 验证设置并查看任何活跃的变更
  • 如果你的编码助手没有立即显示新的斜杠命令，请重启它。斜杠命令在启动时加载，因此需要重新启动才能显示

可选：填充项目上下文 ​

openspec init 完成后，你会收到一个建议的提示来帮助填充项目上下文：

text
填充项目上下文：
"请阅读 openspec/project.md 并帮我填写项目详情、技术栈和约定"

使用 openspec/project.md 定义项目级别的约定、标准、架构模式和其他应在所有变更中遵循的指南。

命令参考 ​

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

文件结构说明 ​

当你让 AI 助手"添加双因素认证"时，它会创建以下结构：

openspec/
├── specs/
│   └── auth/
│       └── spec.md           # 当前认证规范（如果存在）
└── changes/
    └── add-2fa/              # AI 创建整个结构
        ├── proposal.md       # 为什么以及变更什么
        ├── tasks.md          # 实现清单
        ├── design.md         # 技术决策（可选）
        └── specs/
            └── auth/
                └── spec.md   # 显示新增内容的增量

AI 生成的规范示例 ​

在 openspec/specs/auth/spec.md 中创建：

markdown
# Auth Specification

## Purpose
Authentication and session management.

## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT on successful login.

#### Scenario: Valid credentials
- WHEN a user submits valid credentials
- THEN a JWT is returned

AI 生成的变更增量示例 ​

在 openspec/changes/add-2fa/specs/auth/spec.md 中创建：

markdown
# Delta for Auth

## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- WHEN a user submits valid credentials
- THEN an OTP challenge is required

AI 生成的任务示例 ​

在 openspec/changes/add-2fa/tasks.md 中创建：

markdown
## 1. Database Setup
- [ ] 1.1 Add OTP secret column to users table
- [ ] 1.2 Create OTP verification logs table

## 2. Backend Implementation  
- [ ] 2.1 Add OTP generation endpoint
- [ ] 2.2 Modify login flow to require OTP
- [ ] 2.3 Add OTP verification endpoint

## 3. Frontend Updates
- [ ] 3.1 Create OTP input component
- [ ] 3.2 Update login flow UI

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

理解 OpenSpec 文件 ​

增量格式（Delta Format） ​

增量是显示规范如何变化的"补丁"：

  • ## ADDED Requirements - 新增功能
  • ## MODIFIED Requirements - 变更的行为（包含完整的更新文本）
  • ## REMOVED Requirements - 废弃的功能

格式要求：

  • 使用 ### Requirement: <name> 作为标题
  • 每个需求至少需要一个 #### Scenario: 块
  • 在需求文本中使用 SHALL/MUST

与其他工具对比 ​

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、CodeBuddy、Cursor 或任何 AGENTS.md 兼容工具，同时共享相同的规范

当有人切换工具时，运行 openspec update 以便代理获取最新的指令和斜杠命令绑定。

更新 OpenSpec ​

  1. 升级包
    bash
    npm install -g @fission-ai/openspec@latest
  2. 刷新代理指令
    • 在每个项目中运行 openspec update 以重新生成 AI 指导并确保最新的斜杠命令处于活跃状态

许可证 ​

MIT

aicodex 文档网站

Copyright © 2025