企业官网建设流程全解析

OpenSpec 规范驱动开发指南：3 步跑起来 + 4 个必看的坑

【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec

OpenSpec 是一个面向 AI 编码助手的规范驱动开发（SDD）工具：你先和 AI 把"要做什么、怎么做"谈拢，写成可检查的规范文档，它再动手改代码，完成后把结果归档回主规范。

AI 改代码前，先对齐需求

用过 AI 编码助手的人大概都遇到过这种情况：你一句话提了个想法，它直接开写，方向偏了，推倒重来。问题不在模型能力，在于需求从没落成可检查的东西。

OpenSpec 把流程反过来：AI 先产出改动计划，你看完点头，它才执行，结束后还会把"这次到底改了什么行为"合并回主规范。整个闭环只有四个斜杠命令：

• /opsx:propose <改动名>—— AI 生成 proposal.md（为什么做、范围）、增量规范、design.md（怎么做）、tasks.md（任务清单）
• /opsx:apply—— 按任务清单逐项实现
• /opsx:archive—— 把增量规范合并回主规范，改动文件夹归档

如果还没想清楚做什么，先用/opsx:explore让 AI 读代码、帮你把模糊想法收敛成具体方案，再进入 propose。

最短上手路径：10 分钟内跑通第一个改动

这一节给你从零到归档的最短路径，存量项目直接适用，不用提前准备任何东西。

终端里两步：

npm install -g @fission-ai/openspec@latest cd your-project && openspec init

要求 Node.js 20.19 以上。init会生成openspec/目录，并为你选的 AI 助手写好命令入口。

之后全程在 AI 聊天框里：

1. /opsx:explore（可选）——让它先摸清你要动的那块代码
2. /opsx:propose add-dark-mode——生成计划，你审查
3. /opsx:apply—— 开始实现
4. /opsx:archive—— 合并规范、归档改动

默认画像只含 explore / propose / apply / update / sync / archive 六个命令，够用；想解锁verify、bulk-archive、onboard等扩展命令，用openspec config profile选画像再跑openspec update。

核心机制：增量差异，而不是全量文档

看完这节你就明白，为什么它不要求你先给整个系统写文档。

• openspec/specs/—— 系统当前行为的记录，按领域分目录（如auth/、ui/）
• openspec/changes/<改动名>/—— 每次改动一个独立文件夹，互不干扰，天然支持并行

每个改动文件夹里的四类工件互相依赖：

增量规范长什么样

它不描述整个系统，只描述"和现在比变了什么"，用 ADDED / MODIFIED / REMOVED 三段标注，每条需求配具体场景：

ADDED：用户登录时系统必须要求二次验证。 场景：前提（2FA 已开启）→ 动作（提交正确账号密码）→ 结果（弹出验证码）。

归档时自动合并：新增的追加、修改的替换、删除的移除，改动文件夹移入changes/archive/留作审计。规范就是这样一次改动、一层一层长起来的。跑openspec view可以看全局视图：

跨 AI 工具命令写法差异与存量项目落地

四个高频坑，全是新手真实会踩的。

• 命令写法因工具而异。同一个/opsx:propose，在 Cursor、GitHub Copilot 里写成/opsx-propose，Amazon Q 是@opsx-propose，Codex 是$openspec-propose。init结束会在终端打印你所用工具的正确写法，照着敲即可，详见 supported-tools 文档。
• 两个地方别混。openspec开头的命令在终端执行，/opsx:开头的在 AI 聊天框执行。新手卡住大多因为找错了地方。
• 存量项目不用补全量规范。8 万行老代码不必先写文档。挑一个本周本来就要做的小改动，走一遍完整流程，归档后你就有了这块的第一份规范，其余等以后碰到再补。
• 团队约束写进配置。在openspec/config.yaml里放一段 context（技术栈、测试方式、约定）和 rules（比如"提案必须附回滚方案"），之后每次生成工件时自动注入给 AI，不用口头反复交代。

适用边界：什么时候值得上，什么时候别硬套

帮你判断该不该上这套流程。

适合：项目里有 AI 编码助手参与；想给 AI 加"先计划后动手"的约束；存量代码想慢慢补上可追溯的行为记录；多人协作但需求文档总是漂移。

不适合：没有 AI 编码助手参与的传统流程，多一层工具只有成本；已经跑得很成熟的形式化需求流程，硬套会多出一堆没人维护的文档。

快速参考

新手第一天建议：装好 → 挑一个本周真实要做的小需求 → 完整走一遍四个命令。规范驱动开发这套流程的价值，会在第二个改动上明显显现出来。

【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec