面向 AI 编程助手的规范驱动开发（Spec-driven Development）。

关注 @0xTab（X） 获取更新 · 加入 OpenSpec Discord 获取帮助与答疑。

_{🧪 新增： Experimental Workflow (OPSX) — schema 驱动、可 Hack、可流动。无需改代码即可迭代工作流。}

OpenSpec

OpenSpec 用“规范驱动开发”对齐人类与 AI 编程助手：在写任何代码前先就要构建什么达成一致。无需 API Key。

为什么选择 OpenSpec？

AI 编程助手很强，但当需求散落在聊天记录里时，输出往往不可预测。OpenSpec 增加了一套轻量的规格（spec）工作流：在实现前把意图锁定，让产出更确定、更可审阅。

关键收益：

• 人与 AI 在开工前先对 spec 达成一致。
• 结构化的 change 文件夹（proposal、tasks、spec 更新）让范围清晰、可审计。
• 共享可见性：什么是提议中的、进行中的、已归档的，一目了然。
• 兼容你已使用的 AI 工具：支持的工具用自定义 slash 命令，不支持的工具用通用上下文规则。

OpenSpec 对比一览

• 轻量：流程简单、无需 API Key、最小化配置。
• Brownfield 优先：不仅适合 0→1，也非常适合 1→n 的增量演进。OpenSpec 将“事实来源”与“变更提议”分离：openspec/specs/（当前真相）与 openspec/changes/（提议更新）。这样跨多个功能做 diff 更清晰、更可控。
• 变更追踪：proposal、tasks 与 spec delta 同目录；归档时把已批准的更新合并回 specs。
• 与 spec-kit & Kiro 对比：它们在全新功能（0→1）上非常强；OpenSpec 在修改既有行为（1→n）时同样强，尤其是更新跨多个 spec 的场景。

完整对比见 How OpenSpec Compares。

工作原理

┌────────────────────┐
│ Draft Change       │
│ Proposal           │
└────────┬───────────┘
         │ share intent with your AI
         ▼
┌────────────────────┐
│ Review & Align     │
│ (edit specs/tasks) │◀──── feedback loop ──────┐
└────────┬───────────┘                          │
         │ approved plan                        │
         ▼                                      │
┌────────────────────┐                          │
│ Implement Tasks    │──────────────────────────┘
│ (AI writes code)   │
└────────┬───────────┘
         │ ship the change
         ▼
┌────────────────────┐
│ Archive & Update   │
│ Specs (source)     │
└────────────────────┘

1. Draft a change proposal that captures the spec updates you want.
2. Review the proposal with your AI assistant until everyone agrees.
3. Implement tasks that reference the agreed specs.
4. Archive the change to merge the approved updates back into the source-of-truth specs.

快速开始

支持的 AI 工具

安装与初始化

先决条件

• 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、CodeBuddy、Cursor、OpenCode、Qoder 等）；其他助手始终依赖共享的 AGENTS.md stub
• OpenSpec 会为你选择的工具自动配置 slash commands，并且总会在项目根目录写入由其管理的 AGENTS.md 交接文件
• 在你的项目中创建新的 openspec/ 目录结构

完成后：

• 主力 AI 工具可直接触发 /openspec 工作流，无需额外配置
• 运行 openspec list 验证安装并查看任何活动中的 change
• 如果编程助手暂时没有显示新的 slash commands，请重启；slash commands 在启动时加载，重新启动即可生效

可选：补全项目上下文

openspec init 完成后，你会收到一段建议提示词，用于补全项目上下文：

Populate your project context:
"Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions"

使用 openspec/project.md 定义项目级约定、标准、架构模式以及其他跨变更都应遵守的指南。

创建你的第一个 Change

这里是一个真实示例，展示完整 OpenSpec 工作流。任何 AI 工具都能运行；具有原生 slash commands 的工具会自动识别快捷方式。

1. 起草 Proposal

先让 AI 创建一个 change proposal：

You: Create an OpenSpec change proposal for adding profile search filters by role and team
     (Shortcut for tools with slash commands: /openspec:proposal Add profile search filters)

AI:  I'll create an OpenSpec change proposal for profile filters.
     *Scaffolds openspec/changes/add-profile-filters/ with proposal.md, tasks.md, spec deltas.*

2. 校验与审阅

检查 change 是否创建正确，并审阅 proposal：

$ openspec list                             # Confirm the change folder exists
$ openspec validate add-profile-filters     # Validate spec formatting
$ openspec show add-profile-filters         # Review proposal, tasks, and spec delta

3. 迭代 Specs

持续迭代 spec，直到符合你的需求：

You: Can you add acceptance criteria for the role and team filters?

AI:  I'll update the spec delta with scenarios for role and team filters.
     *Edits openspec/changes/add-profile-filters/specs/profile/spec.md and tasks.md.*

4. 实现 Change

当 specs 没问题后，开始实现：

You: The specs look good. Let's implement this change.
     (Shortcut for tools with slash commands: /openspec:apply add-profile-filters)

AI:  I'll work through the tasks in the add-profile-filters change.
     *Implements tasks from openspec/changes/add-profile-filters/tasks.md*
     *Marks tasks complete: Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...*

5. 归档已完成的 Change

实现完成后归档：

AI:  All tasks are complete. The implementation is ready.

You: Please archive the change
     (Shortcut for tools with slash commands: /openspec:archive add-profile-filters)

AI:  I'll archive the add-profile-filters change.
    *Runs: openspec archive add-profile-filters --yes*
     ✓ Change archived successfully. Specs updated. Ready for the next feature!

或在终端里自己运行：

$ openspec archive add-profile-filters --yes  # Archive the completed change without prompts

Note: 支持原生 slash commands 的工具（Claude Code、CodeBuddy、Cursor、Codex、Qoder、RooCode）可使用上述快捷方式。其他工具也能通过自然语言使用，例如“创建 OpenSpec proposal”“应用 OpenSpec change”“归档 change”等。

命令速查

openspec list               # View active change folders
openspec view               # Interactive dashboard of specs and changes
openspec show <change>      # Display change details (proposal, tasks, spec updates)
openspec validate <change>  # Check spec formatting and structure
openspec archive <change> [--yes|-y]   # Move a completed change into archive/ (non-interactive with --yes)

示例：AI 如何生成 OpenSpec 文件

当你让 AI 助手“添加两步验证（two-factor authentication）”时，它会创建：

openspec/
├── specs/
│   └── auth/
│       └── spec.md           # Current auth spec (if exists)
└── changes/
    └── add-2fa/              # AI creates this entire structure
        ├── proposal.md       # Why and what changes
        ├── tasks.md          # Implementation checklist
        ├── design.md         # Technical decisions (optional)
        └── specs/
            └── auth/
                └── spec.md   # Delta showing additions

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

# 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 生成的 Change Delta（位于 openspec/changes/add-2fa/specs/auth/spec.md）：

# 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 生成的 Tasks（位于 openspec/changes/add-2fa/tasks.md）：

## 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

Important: 你无需手动创建这些文件。AI 助手会根据你的需求与现有代码库生成它们。

理解 OpenSpec 文件

Delta 格式

Delta 是展示 spec 如何变化的“补丁（patch）”：

• ## ADDED Requirements - 新增能力
• ## MODIFIED Requirements - 修改行为（需要包含完整的更新后文本）
• ## REMOVED Requirements - 移除/废弃能力

格式要求：

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

OpenSpec 对比

对比 spec-kit

OpenSpec 的双目录模型（openspec/specs/ 存放当前真相，openspec/changes/ 存放提议更新）把状态与 diff 分离。当你修改既有功能或跨多个 spec 更新时，这种结构更易扩展。spec-kit 更擅长 greenfield/0→1，但对跨 spec 更新与功能演进的结构化支持相对少一些。

对比 Kiro.dev

OpenSpec 将某个功能的一次变更聚合在一个目录里（openspec/changes/feature-name/），便于把相关 spec、tasks、design 放在一起追踪。Kiro 会把更新分散到多个 spec 文件夹，可能让功能级追踪更困难。

对比无 Specs 的方式

没有 specs 时，AI 编程助手会从模糊的提示词生成代码，常常遗漏需求或添加不想要的功能。OpenSpec 通过在写代码前先对齐期望行为，让产出更可预测。

团队落地

1. Initialize OpenSpec – 在仓库中运行 openspec init。
2. Start with new features – 让 AI 把即将做的工作先沉淀成 change proposals。
3. Grow incrementally – 每次 change 归档后，会进入“活的 specs”，持续记录你的系统。
4. Stay flexible – 团队成员可用 Claude Code、CodeBuddy、Cursor 或任何兼容 AGENTS.md 的工具，共享同一套 specs。

当有人切换工具时运行 openspec update，确保 agents 获取最新指引与 slash-command 绑定。

更新 OpenSpec

1. Upgrade the package

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

2. Refresh agent instructions
   • 在每个项目里运行 openspec update 以重新生成 AI 指引，并确保最新 slash commands 生效。

实验特性

You can always go back:

  proposal ──→ specs ──→ design ──→ tasks ──→ implement
     ▲           ▲          ▲                    │
     └───────────┴──────────┴────────────────────┘

贡献指南

• 安装依赖：pnpm install
• 构建：pnpm run build
• 测试：pnpm test
• 本地开发 CLI：pnpm run dev 或 pnpm run dev:cli
• Conventional commits（单行）：type(scope): subject

许可证

MIT