OpenSpec：AI 编程先对齐需求，再写代码
用 Cursor 写功能，聊着聊着、代码也出了，合并才发现理解偏了——需求只活在聊天里，关窗口就没了。
OpenSpec 是 规格驱动开发（SDD，先写清"系统应做什么"再写代码） 的轻量框架：写代码前先在仓库对齐「系统应做什么」，规格跟代码一起进 Git。GitHub 6.5 万+ Star，支持 30+ 助手，无需 API Key、无需 MCP（Model Context Protocol，AI 连接外部工具/数据源的标准协议）。
本文讲清楚 OpenSpec 是什么、和 Superpowers / Spec Kit 等怎么选，以及 用 OpenSpec 高保真复刻官网 的实战。
一、OpenSpec 是什么？
OpenSpec 英·美 /ˈoʊpən spɛk/（Open + Spec specification 缩写）。
仓库里的 轻量规格层，不是 AI 客户端：
| 概念 | 路径 | 作用 |
|---|---|---|
| Specs | openspec/specs/ |
系统当前行为真相源 |
| Changes | openspec/changes/<name>/ |
proposal、design、tasks、Delta Spec（本次变更相对现有规格的增删改 diff） |
| Archive | changes/archive/ |
完成后 Delta 合并进 specs，变更存档 |
三条哲学：Lightweight（轻量）、Brownfield-first（棕地优先——"棕地"指已有老代码库，不是从零开始的新项目，不必一开始就把全库文档化）、Specs live in code（规格是活文档，跟代码一起进 Git）。
默认循环（OPSX 是 OpenSpec 新一代工作流的名字，所有命令都以 /opsx: 开头）：/opsx:explore（可选，先和 AI 理清思路不产生文件）→ /opsx:propose（AI 起草计划）→ /opsx:apply（AI 写代码）→ /opsx:archive（归档合并规格）。
npm install -g @fission-ai/openspec@latest
cd your-project && openspec init
需要大模型吗？命令在哪敲？
OpenSpec 本身是个 Node.js CLI 工具，不内置、不直接调用任何大模型。它分两类入口，别混：
| 入口 | 在哪敲 | 需要 AI 吗 | 举例 |
|---|---|---|---|
| 终端 CLI | 系统终端 / iTerm | ❌ 不需要 | openspec init、openspec list、openspec archive |
| AI 聊天斜杠命令 | Cursor / Claude Code / Codex 等助手的聊天框 | ✅ 需要 | /opsx:propose、/opsx:apply、/opsx:explore |
openspec init 会自动给你选的 AI 助手配置好斜杠命令和 skills，之后在聊天框里直接敲 /opsx:propose 加个暗黑模式就行，AI 会读取 OpenSpec 的配置和模板，帮你生成 proposal、design、tasks 等文件。
也可以完全不用 AI，手动写这些规格文件——但那样就失去了大部分价值。OpenSpec 的设计初衷就是给 AI 一个结构化的「对齐层」，减少理解偏差。
官网文档入口提醒：
openspec.dev首页是纯 landing page，只有安装命令和功能展示，没有 Docs 导航栏，首页的「Get Started」按钮是个href="#"空锚点，点了不跳转（截至 2026-08）。完整文档站需直接访问 openspec.dev/docs，或从 GitHub README 里的 docs 目录进入。看英文费劲可搜社区中文文档站openspec.radebit.com。
二、和 Superpowers、Spec Kit 等有啥区别？
SDD 工具近两年集中涌现，名字容易混。核心不是「哪个 Star 多」，而是 它管哪一层问题。
1）一张表看懂
| 维度 | OpenSpec | Superpowers | GitHub Spec Kit | Agent Plan 模式 |
|---|---|---|---|---|
| 管什么 | 改什么（what changed） | 怎么做（how to work） | 按什么规则做（governance） | 这次聊什么 |
| 核心机制 | Delta Spec + propose/apply/archive | 可组合 Skills（TDD 测试驱动开发、brainstorm、review…） | Constitution（宪法，项目级规则总纲）+ 七阶段流水线 | 单次对话内计划 |
| 规格持久化 | ✅ 合并进 openspec/specs/ |
❌ 无独立 spec 层 | ✅ 按 feature 存 .specify/ |
❌ 关窗即没 |
| 最适合 | 棕地、快速迭代、PR 审需求 | 强制流程纪律、TDD 优先 | 绿地（全新项目）、企业治理、完整 artifact | 小改动、单次任务 |
| CLI | Node.js | Shell/JS（skills 包） | Python（specify-cli） |
内置，无仓库结构 |
| 官方背景 | Fission AI 社区 | obra（Jesse Vincent） | GitHub 官方 | 各 Agent 自带 |
2）三句话定位
- OpenSpec：「这次变更相对现状，ADDED/MODIFIED/REMOVED 了什么？」——棕地改功能最为顺手。
- Superpowers（obra/superpowers）：「Agent 必须按 Skill 流程走——先 brainstorm、再 TDD、再 review。」管的是执行纪律，不是规格库。
- Spec Kit（github/spec-kit）：「项目先立 Constitution（宪法），再 specify → plan → tasks → implement。」流程完整、artifact（工作流产物文件，如 proposal、design、tasks）多，小需求可能过重。
3）和 Agent 自带 Plan 比呢？
Plan 适合单次对话；OpenSpec / Spec Kit 的规格 跨会话、可 PR、可版本化。很多团队的真实痛点是：Plan 里对齐的需求，换了一个 Agent 或新开 thread 就丢了——OpenSpec 把对齐层写进 Git。
4）怎么选？（Java 后端视角）
| 你的场景 | 倾向 |
|---|---|
| 老项目加功能、要留需求变更痕迹 | OpenSpec |
| 全新微服务、要统一架构宪法 + 完整 spec 套件 | Spec Kit |
| Agent 总是跳过测试、爱一口气写完 | Superpowers 补纪律 |
| 改一行配置、临时脚本 | 都不用，直接写 |
| 三者都要 | 不冲突：OpenSpec 管 spec 变更，Superpowers 管 TDD skill，Spec Kit 的 constitution 可当 openspec/config.yaml 的 context 来源 |
工具差异小于「你有没有真的在审 spec」。选轻的上手，比反复纠结选型更重要。
三、实战：高保真复刻 openspec.dev
这次按 OpenSpec 流程，对齐 openspec.dev 再实现——像素风 Logo、四格 badge、安装命令复制、Tools 网格、Features 三 Tab 终端、Workspaces（团队协作功能，官网标注 Coming Soon）、FAQ 手风琴，结构跟官网一致。
Step 1 — propose 对齐官网
/opsx:propose 高保真复刻 openspec.dev 首页：JetBrains Mono 黑底、
Hero 四 badge、npm 安装复制、Supported Tools、Features 三 Tab diff/树/agent、
Coming Soon Workspaces、FAQ；顶部 Demo 横幅注明非官方
proposal.md 明确 Non-goals（这次明确不做什么，防止需求越做越大）：不接 PostHog、不提交真实表单。
Step 2 — apply
产出 site/index.html + styles.css + app.js + assets/logo.svg（官方像素 Logo）。
交互对齐官网：
- 安装命令 一键复制
- Tools Show 16 more 展开
- Features 侧边 1/2/3 Tab 切换（移动端横滑）
- FAQ 手风琴
- GitHub Star 数 实时拉取
Step 3 — 预览
cd openspec-site
open site/index.html # 或 npm run preview
顶部灰条：Community Demo · 非官方网站——其余视觉尽量贴近 openspec.dev。
归档目录
openspec-site/site/ ← 高保真页面
openspec/specs/landing-page/spec.md ← 页面行为规格（SHALL 表示"必须做到"的强制要求）
openspec/changes/archive/2026-08-23-build-pseudo-site/
四、什么时候值得用 OpenSpec？
| 场景 | 建议 |
|---|---|
| 棕地功能、多人协作、PR 要审需求 | ✅ |
| 跨 Agent 切换、规格要跟着走 | ✅ |
| 一次性脚本、10 行改动 | ❌ 过重 |
| 跨仓库规格共享 | 关注 Stores（beta，把规格放独立仓库统一管理） |
OpenSpec 不是魔法——规格要你读、改、archive。换的是少返工、少「聊天说过但代码没体现」。
五、写在最后
三个词：对齐、Delta、选对层。
今天可试：① openspec init；② /opsx:propose 做一个真实小需求；③ 打开 openspec-site/site/index.html 对比官网；④ 根据第二节表格选 Superpowers / Spec Kit 是否叠加。
AI 编程缺的不总是模型，常是跨会话还在的对齐层。 OpenSpec 管「改什么」，Superpowers 管「怎么做」，Spec Kit 管「守什么规矩」——分清层，比站队重要。