→ 流动而非僵化
→ 迭代而非瀑布
→ 简单而非复杂
→ 面向存量系统而非只为从零开始
→ 可从个人项目扩展到企业规模

[!TIP] 新工作流已上线！ 我们使用新的工件驱动工作流重建了 OpenSpec。

运行 /opsx:onboard 开始使用。→ 了解更多

团队

在团队中使用 OpenSpec？请 邮件联系 获取 Slack 频道访问权限。

实际演示

你: /opsx:new add-dark-mode
AI:  已创建 openspec/changes/add-dark-mode/
     准备创建：proposal

你: /opsx:ff   # "fast-forward" - 生成所有规划文档
AI:  ✓ proposal.md — 为什么做、改什么
     ✓ specs/       — 需求与场景
     ✓ design.md    — 技术方案
     ✓ tasks.md     — 实现清单
     准备开始实现！

你: /opsx:apply
AI:  正在实现任务...
     ✓ 1.1 添加主题上下文 Provider
     ✓ 1.2 创建切换组件
     ✓ 2.1 添加 CSS 变量
     ✓ 2.2 接入 localStorage
     任务全部完成！

你: /opsx:archive
AI:  已归档到 openspec/changes/archive/2025-01-23-add-dark-mode/
     规范已更新。准备开始下一个功能。

OpenSpec

OpenSpec 用规范驱动开发对齐人类与 AI 编码助手，让你在写任何代码之前先达成“要做什么”的一致。无需 API Key。

中文本地化

此分支已对 OpenSpec 生成的规范与指令做完整中文化。所有必需的 OpenSpec 标记（如 Requirement/Scenario/ADDED/MODIFIED/REMOVED/RENAMED、SHALL/MUST）保持不变，以确保解析器兼容性。

为什么选择 OpenSpec？

AI 编码助手很强，但当需求只存在于聊天记录时，输出往往不可控。OpenSpec 提供轻量的规范化流程，在实现前锁定意图，从而得到可预测、可审阅的输出。

关键收益：

• 人与 AI 在动工前对规范达成一致。
• 结构化的变更目录（提案、任务、规范更新）让范围清晰可审计。
• 共享可见性：哪些在提议、哪些在进行、哪些已归档。
• 与你现有的 AI 工具协作：支持自定义命令的就用命令，不支持的就用上下文规则。

OpenSpec 对比概览

• 轻量：流程简单，无需 API Key，最小化配置。
• 面向存量系统：0→1 之外也很强。OpenSpec 将“真实规范”与“变更提案”分离：openspec/specs/（当前真相）与 openspec/changes/（提议更新），使差异清晰且可管理。
• 变更跟踪：提案、任务与规范增量共存；归档时把已批准的更新合并回规范。
• 对比 spec-kit 与 Kiro：它们更适合 0→1，新特性场景。OpenSpec 在修改既有行为（1→n）、尤其涉及多份规范时表现更佳。

完整对比见：OpenSpec 对比。

它如何工作

┌────────────────────┐
│ 变更草案          │
│ 提案              │
└────────┬───────────┘
         │ 与 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/) — 见 docs | | Codex | /openspec-proposal, /openspec-apply, /openspec-archive（全局：~/.codex/prompts，自动安装） | | Continue | /openspec-proposal, /openspec-apply, /openspec-archive (.continue/prompts/) | | CoStrict | /openspec-proposal, /openspec-apply, /openspec-archive (.cospec/openspec/commands/) — 见 docs| | 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 | /openspec:proposal, /openspec:apply, /openspec:archive (.qoder/commands/openspec/) — 见 docs | | 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/) |

Kilo Code 会自动发现团队工作流。将生成文件保存到 .kilocode/workflows/，并通过命令面板触发 /openspec-proposal.md、/openspec-apply.md 或 /openspec-archive.md。

这些工具会自动读取 openspec/AGENTS.md 中的工作流说明。如需提醒，可直接要求它们遵循 OpenSpec 工作流。更多信息见 AGENTS.md 规范。

| 工具 | |-------| | Amp • Jules • Others |

安装与初始化

前置条件

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

第一步：全局安装 CLI

方式 A：使用 npm

npm install -g openspec-cn@latest

验证安装：

openspec --version

方式 B：使用 Nix（NixOS 与 Nix 包管理器）

无需安装，直接运行 OpenSpec：

nix run github:xiangagou163/OpenSpec-cn -- init

或安装到你的 profile：

nix profile install github:xiangagou163/OpenSpec-cn

或在 flake.nix 中加入开发环境：

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    openspec.url = "github:xiangagou163/OpenSpec-cn";
  };

  outputs = { nixpkgs, openspec, ... }: {
    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
      buildInputs = [ openspec.packages.x86_64-linux.default ];
    };
  };
}

验证安装：

openspec --version

第二步：在项目中初始化 OpenSpec

进入你的项目目录并运行初始化：

cd your-project
openspec init

初始化过程中会发生：

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

完成设置后：

• 主要 AI 工具可直接触发 /openspec 工作流，无需额外配置
• 运行 openspec list 验证设置并查看活跃变更
• 如果编码助手没有立刻显示命令，请重启。命令在启动时加载，重新启动即可出现。

告诉你的 AI：/opsx:new <你要构建的内容>

[!NOTE] 不确定工具是否支持？查看 支持工具清单 – 已支持 20+ 工具并持续增加。

也支持 pnpm、yarn、bun 与 nix。详见 安装选项。

可选：补充项目上下文

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

补充你的项目上下文：
"请阅读 openspec/project.md，并帮我填写项目细节、技术栈与约定"

使用 openspec/project.md 定义项目级规范、标准、架构模式以及在所有变更中应遵循的准则。

创建你的第一个变更

下面是一个完整流程示例，适用于任何 AI 工具。支持命令的工具会自动识别快捷方式。

1. 起草提案

先让 AI 创建变更提案：

You: 创建一个 OpenSpec 变更提案，用于新增按角色与团队的个人资料筛选
     （支持命令的工具快捷方式：/openspec:proposal Add profile search filters）

AI:  我将为个人资料筛选创建 OpenSpec 变更提案。
     *创建 openspec/changes/add-profile-filters/，包含 proposal.md、tasks.md、spec 增量。*

2. 验证与评审

确认变更创建正确并审阅提案：

$ openspec list                             # 确认变更目录存在
$ openspec validate add-profile-filters     # 校验规范格式
$ openspec show add-profile-filters         # 查看提案、任务与规范增量

3. 打磨规范

迭代规范直到满足需求：

You: 能否为角色与团队筛选添加验收标准？

AI:  我会在规范增量中加入对应场景。
     *编辑 openspec/changes/add-profile-filters/specs/profile/spec.md 与 tasks.md。*

4. 实现变更

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

You: 规范看起来没问题。开始实现这个变更。
     （支持命令的工具快捷方式：/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. 归档已完成的变更

实现完成后归档变更：

AI:  任务已全部完成，实现就绪。

You: 请归档该变更
     （支持命令的工具快捷方式：/openspec:archive add-profile-filters）

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

或在终端自行运行：

$ openspec archive add-profile-filters --yes  # 无提示归档已完成的变更

注： 支持命令的工具（Claude Code、CodeBuddy、Cursor、Codex、Qoder、RooCode）可使用这些快捷方式。其他工具可使用自然语言请求“创建 OpenSpec 提案”、“应用 OpenSpec 变更”或“归档变更”。

命令参考

openspec list               # 查看活跃变更目录
openspec view               # 交互式仪表盘查看规范与变更
openspec show <change>      # 查看变更详情（提案、任务、规范更新）
openspec validate <change>  # 校验规范格式与结构
openspec archive <change> [--yes|-y]   # 归档已完成变更（--yes 为无交互）

示例：AI 如何生成 OpenSpec 文件

当你让 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）：

# 认证规范

## 目的
认证与会话管理。

## 需求
### Requirement: User Authentication
系统 SHALL 在成功登录后签发 JWT。

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

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

# Auth 变更增量

## ADDED Requirements
### Requirement: Two-Factor Authentication
系统 MUST 在登录时要求第二因素。

#### Scenario: OTP required
- WHEN 用户提交有效凭证
- THEN 需要 OTP 挑战

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

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

增量格式

增量是展示规范如何变化的“补丁”：

• ## ADDED Requirements - 新能力
• ## MODIFIED Requirements - 行为变化（包含完整更新文本）
• ## REMOVED Requirements - 弃用功能

格式要求：

• 使用 ### Requirement: <name> 作为标题
• 每条需求至少包含一个 #### Scenario: 块
• 需求文字使用 SHALL/MUST

OpenSpec 对比

对比 spec-kit

OpenSpec 的双目录模型（openspec/specs/ 表示当前真相，openspec/changes/ 表示提议更新）将状态与差异分离。修改既有功能或涉及多个规范时更易扩展。spec-kit 在 0→1 阶段更强，但对跨规范更新与演进特性支持较弱。

对比 Kiro.dev

OpenSpec 将单个功能的所有变更收拢到一个目录（openspec/changes/feature-name/），便于同时跟踪规范、任务与设计。Kiro 将更新分散在多个规范目录中，跟踪更难。

对比无规范

没有规范时，AI 往往基于模糊提示生成代码，容易漏需求或引入不必要功能。OpenSpec 通过在动工前达成行为共识带来可预期性。

团队落地

1. 初始化 OpenSpec – 在仓库中运行 openspec init。
2. 从新功能开始 – 让 AI 用变更提案记录即将开展的工作。
3. 渐进演进 – 每次变更归档为活的规范，持续记录系统。
4. 保持灵活 – 队友可用 Claude Code、CodeBuddy、Cursor 或任何兼容 AGENTS.md 的工具，规范保持一致。

当有人切换工具时运行 openspec update，让指令与命令绑定保持最新。

更新 OpenSpec

1. 升级包

   npm install -g openspec-cn@latest

2. 刷新代理指令
   • 在每个项目内运行 openspec update，重新生成 AI 指引并确保最新命令生效。

实验性功能

为什么需要它：

• 标准工作流是固定的——你无法调整指令或自定义
• AI 输出不好时，你无法自行优化提示
• 所有人用同一套流程，难以匹配团队习惯

有何不同：

• 可改造 — 直接编辑模板与 schema，即时测试，无需重建
• 更细粒度 — 每个工件都有独立指令，可单独测试与微调
• 可定制 — 自定义工作流、工件与依赖关系
• 流动 — 没有阶段闸口，随时更新任意工件

随时可以回到任一步：

  提案 ──→ 规范 ──→ 设计 ──→ 任务 ──→ 实现
     ▲         ▲        ▲                │
     └─────────┴────────┴────────────────┘

| 命令 | 作用 | |---------|--------------| | /opsx:new | 创建新变更 | | /opsx:continue | 创建下一个工件（根据就绪情况） | | /opsx:ff | 快进（一次性生成全部规划工件） | | /opsx:apply | 实现任务，必要时同步更新工件 | | /opsx:archive | 完成后归档 |

启用： openspec experimental

完整文档 →

使用注意事项

模型选择：OpenSpec 在高推理模型上表现更好。建议 Opus 4.5 与 GPT 5.2 用于规划与实现。

上下文卫生：在开始实现前清理上下文，过程中保持良好上下文卫生。

参与贡献

小改动 — 修复 Bug、改错别字或小改进可直接提交 PR。

大改动 — 新功能、较大重构或架构变更请先提交 OpenSpec 变更提案，先对齐意图与目标再实现。

撰写提案时请牢记 OpenSpec 的理念：服务于不同编码助手、模型与使用场景，改动应对所有人友好。

欢迎 AI 生成代码 — 但需经过测试与验证。PR 中请注明使用的编码助手与模型（例如：“Generated with Claude Code using claude-opus-4-5-20251101”）。

开发

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

其他

OpenSpec 收集匿名使用统计。

我们只收集命令名与版本号用于理解使用模式，不含参数、路径、内容或个人信息。CI 中会自动关闭。

退出： export OPENSPEC_TELEMETRY=0 或 export DO_NOT_TRACK=1

维护者与顾问名单见 MAINTAINERS.md。

许可证

MIT