Framework OpenSpec 面向AI编程助手的需求驱动开发规范工具

AI 编程助手很强，但有个常见尴尬：需求只活在聊天记录里。模型生成一堆代码，你改两版之后，谁也说不清最初要做什么、现在做到了哪一步。需求一旦进不了代码库，就变成了会漂移的口头约定，到上线才发现理解有偏差。

OpenSpec 给这类工作流补了一层轻量的「规范层」：在写任何代码之前，先和 AI 就 specs（需求与场景）、proposal（为什么做、改什么）、design（技术方案）、tasks（实现清单）达成一致，并把这些文件提交进仓库。它把自己定位为「spec-driven development（SDD）框架」，目标是让人类和 AI 在编码前先对齐。

项目基本信息

一、项目介绍

OpenSpec 是一个单文件分发的规范驱动开发框架，官方强调它「不需要 Node.js 也能跑」（Alpine Linux 首次运行需 apk add libstdc++ libgcc）。它通过一套 openspec/ 目录形状管理需求：每个变更拥有独立的文件夹，内含 proposal、specs、design、tasks 四类文档，规划与实现都在仓库里可追溯。

它最直观的入口是斜杠命令：/opsx:explore 做无负担的构思伙伴，/opsx:propose <想做什么> 直接生成变更提案，/opsx:apply 落地实现，/opsx:archive 归档并更新 specs。不同 AI 助手的命令写法略有差异（Cursor / Copilot 用 /opsx-propose，Amazon Q 用 @opsx-propose，Codex 用 $openspec-propose），openspec init 会按你选择的工具打印正确形式，官方称支持 30+ 工具。

二、核心优势

• 先对齐再动手：人类与 AI 在 specs 阶段就需求与场景达成共识，减少「做偏了」的返工。
• 变更可追溯：每个变更一个文件夹，proposal / specs / design / tasks 齐全，随时回看。
• fluid 而非瀑布：任何文档都能随时更新，没有僵化的阶段门禁。
• 跨仓库 Stores（测试版）：把规划放进独立仓库，通过 git push 共享，让团队和多个编码智能体共用同一份事实来源，解决「一个功能横跨三个仓库」的协作难题。
• 工具无关：通过斜杠命令适配 30+ AI 助手，不绑定单一 IDE 或模型。

三、适用场景

• 个人项目：用 OpenSpec 约束 AI，避免需求在对话里丢失。
• 团队协作：平台团队拥有 specs，产品团队只读引用，wiki 不再漂移。
• 多仓库功能：一个变更、一份计划，代码落在多个仓库也能对齐。
• 代码评审前置：先把技术方案写清楚，再让 AI 或同事评审。

四、安装教程

macOS / Linux 一键安装（无需 Node.js）：

curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh

Windows（PowerShell）：

irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex

偏好包管理器（需 Node.js 20.19.0+）：

npm install -g @fission-ai/openspec@latest
# 或
brew install openspec

进入项目初始化：

cd your-project
openspec init

常见报错与处理：

error while loading shared libraries: libstdc++.so.6

Alpine 等精简系统缺少运行库，执行 apk add libstdc++ libgcc 后重试。

command not found: openspec

安装成功但不在 PATH，确认 npm 全局 bin 目录已加入环境变量，或改用 npx @fission-ai/openspec。

五、使用示例

探索式构思（适合还不确定要做什么）：

/opsx:explore
AI: 想探索什么？
你: 我想做暗色模式，但不确定怎么做得干净。
AI: 看过你的样式设置……最干净的路径是 CSS 变量加主题上下文，无需新依赖。要细化吗？

直接提案并实现：

/opsx:propose add-dark-mode
# 生成 openspec/changes/add-dark-mode/ 下的 proposal.md、specs/、design.md、tasks.md
/opsx:apply
# 逐项实现：✓ 1.1 添加主题上下文 ✓ 2.1 接入 CSS 变量 ……
/opsx:archive
# 归档到 changes/archive/2025-01-23-add-dark-mode/，specs 更新

真实输出：AI 返回清晰的提案结构与逐条任务清单，实现完成后把 specs 更新为最新事实，下一次功能直接基于它继续。

六、常见问题

• 需要联网吗？ CLI 本体可离线运行；首次安装脚本需联网下载二进制。
• 和 GitHub Spec Kit 有什么区别？ 官方对比称 Spec Kit 更重量级、阶段门禁更 rigid；OpenSpec 更轻、可自由迭代。
• Stores 稳定吗？ 官方标注为 beta，适合试点，生产大规模协作建议先小范围验证。
• 支持我的 AI 工具吗？ 已支持 30+ 助手，运行 openspec init 会输出对应命令格式。

七、总结

OpenSpec 解决的是 AI 编程里最容易被忽视的一环：需求管理。它用一套简单的 Markdown 规范，把「要做什么」固定进仓库，让 AI 和人类始终对同一份事实工作。对希望把 AI 编程从「聊出来」升级到「管起来」的团队和个人，这是一个低门槛、强约束的实用框架。