OpenSpec：AI编程时代的规格驱动开发框架

→ fluid not rigid
→ iterative not waterfall
→ easy not complex
→ built for brownfield not just greenfield
→ scalable from personal projects to enterprises

全新工作流现已发布！我们用全新的 artifact 引导工作流重建了 OpenSpec。

运行 /opsx:propose "your idea" 开始使用 → 了解更多

关注 X 上的 @0xTab 获取更新 · 加入 OpenSpec Discord 寻求帮助和问题解答。

You: /opsx:explore
AI:  What would you like to explore?
You: I want dark mode but I'm not sure how to do it cleanly.
AI:  Let me look at your styling setup...
     Cleanest path here: CSS variables + a small theme context,
     with system-preference detection. No new dependencies. Scope it?
You: Yes, let's do it.

You: /opsx:propose add-dark-mode
AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

You: /opsx:apply
AI:  Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     ✓ 2.2 Wire up localStorage
     All tasks complete!

You: /opsx:archive
AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

纯 Markdown 编写——需求配合具体场景，无需学习特殊语法。以下是上述 specs/ 文件夹中的内容：

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

这些由你的 AI 编写；你在代码写入之前审查计划。

OpenSpec 本身就是用 OpenSpec 构建的——浏览该仓库的实时 specs 和进行中的变更，获取真实的大规模示例。

团队采用 OpenSpec 的原因

对于个人项目，OpenSpec 让你和你的 AI 在单一仓库上保持诚实。对于团队来说，难点转移了：一个特性跨越 API 服务器、Web 应用和共享库；需求由一个团队拥有，却被其他团队消费；规划在任何代码存在之前就已经开始。

Stores 是解决方案——在独立的仓库中进行规划。你已经熟悉的 openspec/ 结构（specs 和 changes），像其他任何东西一样通过 git push 共享。整个团队和每个 coding agent 都能读取的单一事实来源，跨所有仓库。

跨仓库特性——一次变更，一个计划，即使代码分布在三个仓库中。

共享需求——平台团队拥有 specs；产品团队以只读方式引用，就在他们的 coding agent 可以读取的位置。没有漂移的 wiki。

先规划后编码——现在就把计划捕获到 store 中；代码仓库稍后跟进。

Stores 处于 beta 阶段。从 Stores 用户指南开始。

需要 Node.js 20.19.0 或更高版本。

全局安装 OpenSpec：

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

然后导航到你的项目目录并初始化：

cd your-project
openspec init

想让你的 AI 来做？将设置提示粘贴到你的 coding assistant 中——它会安装 CLI、运行 openspec init 并验证结果。

不知道要构建什么？从 /opsx:explore 开始，这是一个零风险的思维伙伴，它会读取你的代码、权衡选项，在任何代码写出之前形成计划。（探索指南）

已经知道要构建什么？直接使用 /opsx:propose <what-you-want-to-build>。

两者都在默认配置文件中。如果想要扩展工作流（/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:bulk-archive、/opsx:onboard），使用 openspec config profile 选择并通过 openspec update 应用。

/opsx:propose 是规范名称；你的工具可能写作 /opsx-propose（Cursor、GitHub Copilot）、@opsx-propose（Amazon Q）或 $openspec-propose（Codex）。openspec init 会打印你选择的工具对应的正确形式——参见如何调用。

不确定你的工具是否支持？查看完整列表——我们支持 30+ 工具且在不断增长。

也支持 pnpm、yarn、bun 和 nix。参见安装选项。

从这里开始：文档首页映射所有内容。刚接触 OpenSpec？先阅读入门指南，然后阅读命令如何工作（在这里你实际输入 /opsx:propose）。

→ 入门指南：第一步 → 先探索：用 /opsx:explore 先思考清楚再付诸行动 → 命令如何工作：斜杠命令在哪里运行 vs CLI → 核心概念一览：整个心智模型，一页纸 → 示例与食谱：真实变更，从头到尾 → 工作流：组合和模式 → 现有项目：在 brownfield 代码库上采用 OpenSpec → 编辑变更：更新制品、返回、协调手动编辑 → 命令：斜杠命令和技能 → CLI：终端参考 → Stores：在独立仓库中规划，团队共享（beta）→ 支持的工具：工具集成和安装路径 → 概念：这一切如何配合 → 多语言：多语言支持 → 自定义：让它成为你的 → 社区展示：用和为 OpenSpec 构建的项目和资源 → 常见问题 · 故障排除 · 词汇表：快速帮助

第三方 schema 包通过独立仓库分发——这些提供了集成 OpenSpec 与其他工具的固执己见的工作流，类似于 github/spec-kit 的社区扩展目录处理工具集成的方式。

→ 在自定义文档中浏览目录。

AI coding assistants 功能强大，但当需求只存在于聊天历史中时却不可预测。OpenSpec 添加了一个轻量级的 spec 层，让你在任何代码写出之前就达成共识。

先达成共识再构建——在代码写出之前，人类和 AI 在 specs 上对齐

保持有序——每个变更都有自己的文件夹，包含 proposal、specs、design 和 tasks

流畅工作——随时更新任何 artifact，没有僵硬的阶段门

使用你的工具——通过斜杠命令与 30+ AI assistants 配合工作

对比 Spec Kit（GitHub）——详尽但重量级。僵硬的阶段门、大量 Markdown、Python 设置。OpenSpec 更轻量，让你自由迭代。

对比 Kiro（AWS）——功能强大，但你被锁定在他们的 IDE 中，且仅限于 Claude 模型。OpenSpec 使用你已经拥有的工具。

对比什么都不做——没有 specs 的 AI coding 意味着模糊的提示和不可预测的结果。OpenSpec 带来可预测性，而无需繁文缛节。

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

刷新 agent 指令

在每个项目内运行此命令，以重新生成 AI 指导并确保最新的斜杠命令处于激活状态：

openspec update

模型选择：OpenSpec 在高推理模型上效果最佳。我们推荐 Codex 5.5 和 Opus 4.7 用于规划和实现。

上下文卫生：OpenSpec 从干净的上下文窗口中受益。在开始实现之前清除上下文，并在整个会话中保持良好的上下文卫生。

在打开 PR 之前先开一个讨论（用于核心设计变更）或 issue，并从 PR 中链接 issue 或讨论。新功能、重大重构和架构变更需要先有一个 OpenSpec 变更提案。

→ CONTRIBUTING.md：完整流程，从第一个 issue 到合并的 PR

OpenSpec 收集匿名使用统计。

我们只收集命令名和版本以了解使用模式。不收集参数、路径、内容或个人信息。在 CI 中自动禁用。

退出方式（任选其一即可）：

openspec config set telemetry.enabled false（全局配置；未设置表示开启）

export OPENSPEC_TELEMETRY=0 或 export DO_NOT_TRACK=1（环境变量覆盖配置）

参见 MAINTAINERS.md 了解核心维护者和顾问的名单，他们帮助指导该项目。