面向 AI 编码助手的规范驱动开发。

最受欢迎的规范框架。


我们的理念：

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

> [!TIP]
> 新工作流已上线！ 我们使用新的工件驱动工作流重建了 OpenSpec。
>
> 运行 /opsx:onboard 开始使用。→ 了解更多


关注 @0xTab 获取更新 · 进入 OpenSpec Discord 获取帮助与答疑。


$3

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

实际演示

`text
你: /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 Dashboard


🧪 新功能： OPSX 工作流 — 以 schema 驱动、可定制、可流动。无需改代码即可迭代工作流。


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. 归档变更，将已批准的更新合并回“真实规范”。
`

快速开始

$3

原生命令（Slash Commands）（点击展开）

这些工具内置 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。

AGENTS.md 兼容（点击展开）

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

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

$3

#### 前置条件
- Node.js >= 20.19.0 - 使用 node --version 检查版本

#### 第一步：全局安装 CLI

方式 A：使用 npm

`bash
npm install -g openspec-cn@latest
`

验证安装：
`bash
openspec --version
`

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

无需安装，直接运行 OpenSpec：
`bash
nix run github:xiangagou163/OpenSpec-cn -- init
`

或安装到你的 profile：
`bash
nix profile install github:xiangagou163/OpenSpec-cn
`

或在 flake.nix 中加入开发环境：
`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 ];
};
};
}
`

验证安装：
`bash
openspec --version
`

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

进入你的项目目录并运行初始化：
`bash
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。详见 安装选项。

$3

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

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

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

$3

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

#### 1. 起草提案
先让 AI 创建变更提案：

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

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

#### 2. 验证与评审
确认变更创建正确并审阅提案：

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

#### 3. 打磨规范
迭代规范直到满足需求：

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

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

#### 4. 实现变更
规范确认无误后开始实现：

`text
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. 归档已完成的变更
实现完成后归档变更：

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

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

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

或在终端自行运行：
`bash
$ openspec archive add-profile-filters --yes # 无提示归档已完成的变更
`

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

命令参考

`bash
openspec list # 查看活跃变更目录
openspec view # 交互式仪表盘查看规范与变更
openspec show # 查看变更详情（提案、任务、规范更新）
openspec validate # 校验规范格式与结构
openspec archive [--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 # 增量内容
`

$3

`markdown


认证规范

目的

认证与会话管理。

需求

$3

系统 SHALL 在成功登录后签发 JWT。

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

$3

`markdown


Auth 变更增量

ADDED Requirements

$3

系统 MUST 在登录时要求第二因素。

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

$3

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

$3

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

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

格式要求：
- 使用 ### Requirement: 作为标题
- 每条需求至少包含一个 #### Scenario: 块
- 需求文字使用 SHALL/MUST




OpenSpec 对比

$3


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

$3

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

$3

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

团队落地

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

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

更新 OpenSpec

1. 升级包
`bash
npm install -g openspec-cn@latest
`
2. 刷新代理指令
- 在每个项目内运行 openspec update，重新生成 AI 指引并确保最新命令生效。

实验性功能

🧪 OPSX：流动、可迭代的工作流（仅 Claude Code）

为什么需要它：
- 标准工作流是固定的——你无法调整指令或自定义
- 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”）。

$3

- 安装依赖：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