给 AI 加一层「规格书」：OpenSpec 使用体验

AI 写代码能力越来越强，但你一定遇到过这种情况：跟 AI 聊了半天，它噼里啪啦写了一堆代码，结果不是你想要的。问题出在哪？需求只活在聊天记录里，没有被双方确认。

OpenSpec 解决的就是这个问题——在人和 AI 之间加一层轻量的规格书，先对齐要做什么，再动手写代码。

它是什么

OpenSpec 是一个给 AI 编码助手用的规格框架。它不替代你的 AI 工具，而是在外面包一层结构化的工作流。

核心思路很简单：

你：我想要暗色模式
AI：好的，我来写代码   ← 传统方式，直接开干

你：我想要暗色模式
AI：让我先看看你的项目... 我建议用 CSS 变量 + 系统偏好检测，要我出个方案吗？   ← OpenSpec 方式

先探索、再提案、再实现。每一步都有文档记录，人和 AI 都能回溯。

工作流

OpenSpec 的工作流用斜杠命令驱动，分几个阶段：

1. 探索：/opsx:explore

不确定怎么做的时候，先让 AI 帮你分析。它会读你的代码，比较方案，给出建议。没有结构化输出，就是一次对话。

/opsx:explore
→ 我想加评论系统，但不确定用哪个
→ AI 分析了项目结构，对比了 Giscus、Waline、Twikoo
→ 建议用 Giscus，理由是基于 GitHub Discussions，零运维

2. 提案：/opsx:propose

确定要做什么了，让 AI 生成完整的规划文档：

• proposal.md — 为什么做、改什么
• specs/ — 需求规格和场景
• design.md — 技术方案
• tasks.md — 实现清单

这些文件存在 openspec/changes/<变更名>/ 目录下，你可以随时查看和修改。

3. 实现：/opsx:apply

AI 按照 tasks.md 里的清单逐项实现。完成一项勾一项，遇到问题会停下来问你。

这个阶段是「流动」的——你可以随时回去改 specs 或 design，AI 会根据新内容调整实现。没有僵硬的阶段门。

4. 归档：/opsx:archive

全部完成后归档。变更记录保留，specs 合并到主文档。

实际体验

我用 OpenSpec 给博客加了 Giscus 评论系统。整个过程：

探索阶段：AI 读了项目结构，发现是 VitePress + Vue 3 自定义主题，建议在 Layout.vue 的 #doc-after 插槽里加评论组件。

提案阶段：生成了完整的规划文档，包括需求规格（文章页显示评论、非文章页不显示、敏感词过滤）和任务清单（15 项）。

实现阶段：AI 按清单逐项执行——安装依赖、创建组件、填入配置、验证构建。每完成一项就更新 tasks.md。

归档阶段：全部完成后归档，保留完整记录。

整个过程最大的好处是可追溯。每个决策都有记录，每个任务都有状态。如果中途被打断，下次回来一看 tasks.md 就知道做到哪了。

为什么需要它

不用 OpenSpec 的话，AI 编码通常是这样的：

1. 你描述需求
2. AI 直接写代码
3. 不对，改
4. 还不对，再改
5. 改来改去，最后凑合用了

问题在于：需求是模糊的，AI 只能猜。猜错了就返工。

OpenSpec 强制你在动手之前把需求写清楚。不是写给 AI 看的，是写给你自己看的——你真的想清楚了吗？边界在哪？哪些不做？

这个「先想清楚」的过程，比 AI 写的任何代码都有价值。

它适合谁

• 个人开发者：用 AI 辅助编码，但不想每次都在聊天里重新解释上下文
• 小团队：多人协作时，变更记录比口头对齐靠谱
• 复杂功能：涉及多个文件、多个模块的改动，需要先理清思路

不适合的场景：一次性脚本、快速原型、你已经完全想清楚只需要 AI 代打的活。

安装

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

初始化后会在项目里生成 .claude/skills/（或其他 AI 工具对应的目录），AI 助手会自动识别这些斜杠命令。

一点感受

AI 编码工具进化很快，但「人和 AI 如何协作」这个问题还没被好好解决。大多数工具在优化「AI 写代码的速度」，OpenSpec 在优化「人和 AI 对齐需求的效率」。

它不华丽，甚至有点无聊——就是一堆 markdown 文件。但正是这些 markdown 文件，让 AI 从「猜你想什么」变成「确认后执行」。

最好的工具不是让你更快，而是让你更准。