AI 写代码越来越快，但有个老问题始终在：需求只活在聊天记录里。你说一句"加个暗黑模式"，它哗哗吐出 400 行，你才发现它用的是新依赖、没接系统偏好、也没持久化。改起来比写还累。OpenSpec 干的事就一句话——在写代码之前，先把"要做什么"对齐成一份人能看懂、能改的文档。
它是 Fission-AI 开源的 spec-driven development（规范驱动开发）工具，MIT 协议，纯 Markdown 落盘，跟着 git 走，不锁任何 IDE，支持 30+ 种 AI 助手（Claude Code、Cursor、Copilot、Codex 等）。
核心模型：两个文件夹
整个 OpenSpec 只有两个目录，理解这两个就理解了全部：
openspec/specs/—— 真相。记录系统"现在"的行为，用 requirement（系统 SHALL 怎样）加 scenario（WHEN/THEN 具体例子）描述，按业务域分目录（auth/、ui/、payments/）。openspec/changes/—— 提案。你想改点什么，就在这里建一个文件夹，把这次改动相关的东西全塞进去。
关键点在于：你不重写整个 spec，只写"这次改了哪几条"。新增一条写 ADDED，改动一条写 MODIFIED，删掉一条写 REMOVED。这正是它能塞进你 5 万行老项目的原因——你描述 diff，而不是描述目的地。
## ADDED Requirements ### Requirement: 主题切换 系统 SHALL 允许用户在浅色和深色主题之间切换，默认跟随系统偏好。 #### Scenario: 用户开启暗黑模式 - **WHEN** 用户点击主题切换按钮 - **THEN** 应用切换到暗黑模式并持久化该选择
这段就是 AI 写的、你审阅的计划，代码一行没动。
日常循环：四个命令
默认配置下你每天就跑这四个（斜杠命令打在 AI 聊天框里）：
/opsx:explore → （可选）还拿不准，先跟 AI 聊清楚方案
/opsx:propose add-dark-mode → AI 起草 proposal / specs / design / tasks
（你读一遍计划，不对就改）
/opsx:apply → AI 按 tasks.md 逐条实现
/opsx:archive → 规格更新，改动归档
explore 是个零风险的思考搭档：它读你的代码、摆出选项、把模糊想法落成具体方案，再决定要不要进 propose。已经想清楚了就直接 propose，跳过它。
这四个产物层层递进：proposal（为什么）→ specs（改什么）→ design（怎么做）→ tasks（步骤清单）→ implement。但顺序只是"给 AI 提供上下文"，不是强制关卡。实现时发现设计错了？改 design.md 继续。范围该缩小？改 proposal。什么都不会锁死。
archive 干一件事：把 change 里的 delta 合并进主 specs，文件夹挪到 changes/archive/2026-09-08-xxx/。真相更新，进入下一个循环。
装好之后怎么跑
要求 Node.js 20.19.0 以上。全局装：
npm install -g @fission-ai/openspec@latest
进你的项目初始化：
cd your-project openspec init
init 会按你选的 AI 工具，生成对应的 /opsx 命令写法并打印出来。命令前缀因工具而异：/opsx:propose（Claude Code）、/opsx-propose（Cursor、Copilot）、$openspec-propose（Codex）。
升级和刷新：
npm install -g @fission-ai/openspec@latest # 升 CLI openspec update # 进项目刷 AI 指令和命令 openspec config set telemetry.enabled false # 关遥测（可选）
一个完整例子
README 里的暗黑模式流程，完整跑一遍是这样的：
You: /opsx:explore
AI: What would you like to explore?
You: 我想加暗黑模式，但不确定怎么做得干净。
AI: 看了一下你的样式方案……最干净的路子：
CSS 变量 + 一个轻量主题 context，再做系统偏好检测，
不引入新依赖。要我按这个范围出计划吗？
You: 可以，就这么做。
You: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
✓ proposal.md — 为什么做、改什么
✓ specs/ — 需求与场景
✓ design.md — 技术方案
✓ tasks.md — 实现清单
Ready for implementation!
You: /opsx:apply
AI: Implementing tasks...
✓ 1.1 加主题 context provider
✓ 1.2 做切换组件
✓ 2.1 加 CSS 变量
✓ 2.2 接 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.
做完之后，仓库里多了一份"为什么这么做"的记录。半年后你或下一个 AI session 翻 spec，就知道这套主题系统当时的设计意图，不用考古聊天记录。
什么时候该用，什么时候不值
OpenSpec 多一道工序——写代码前先写段计划。它换来的东西很实在：
- 在提案阶段改方向的代价趋近于零，在 400 行代码之后改方向代价很高。
- 计划和代码在同一仓库，需求文档不再漂移到 wiki。
- 改动可审阅：一个 change 文件夹就是个整齐的包裹，读 proposal、扫 delta、查 tasks，一眼看全。
- 适配已有代码库：delta 机制让你能直接给老系统提改动，不用先把整个系统文档化。
诚实的代价：一行 trivial 的小修复，这套仪式不划算。它设计得轻，但毕竟不是零成本。原则就一句——在"对齐有价值"的地方用它，而一旦你开始跟一个会自信地按模糊指令乱写的 AI 协作，大多数时候都值得。
和同类工具的区别
- vs Spec Kit（GitHub）：更重、有刚性阶段门、文档多、要 Python。OpenSpec 更轻，能自由迭代。
- vs Kiro（AWS）：能力强，但锁在它自家 IDE、且只能用 Claude 模型。OpenSpec 用你已有的工具。
- vs 什么都不用：没有 spec 的 AI 编码 = 模糊提示 + 不可预测的结果。OpenSpec 把可预测性拿回来，且不增加太多仪式感。
团队场景还有 Stores（beta）：把规格单独放一个仓库，通过 git push 共享，跨多个代码仓保持一致的事实源——一个改动、一份计划，即便代码落在三个仓库里。个人项目暂时用不到，可先不管。
一句话记住：先对齐规格、再写代码；explore 想清楚 → propose 出计划 → apply 去实现 → archive 归档。