许愿式编程:Spec-Kit 与 OpenSpec 实战指北

1. 故事的开始:迟到了两个月的"还愿"

故事要从两个月前说起。当时有同事希望能讲解一下 Spec-Kit 和 OpenSpec 这两个在当时看起来非常有潜力的框架。我满口答应,然后……就没有然后了。

这就跟每个程序员 backlog 里那些"待办"的技术债一样,一拖就是一个多月。时至今日,AI 进化速度之快,可能这两个工具在某些激进的极客眼中已经属于"即将淘汰"的产物了。

但正如经典算法永远不会过时,这两款工具背后的思想——Spec-Driven Development (SDD,规格驱动开发),依然是当下 Agentic Workflow 的核心。而且它们真的很简单,几分钟就能上手。

所以,趁着它们还没彻底成为"时代的眼泪",我决定把这段使用体验写下来。这不仅是一篇教程,更是一次关于"我们以后怎么写代码"的思考。

2. 框架全貌:一文看懂两大"许愿池"

在谈使用体验之前,先让我们用最直观的方式理解这两个框架的运作机制。

2.1 Spec-Kit:规范驱动开发·质量内建·AI赋能

Spec-Kit 是 GitHub 官方出品,它的理念是"规范驱动",适合从零到一的大型项目(Epic)。

🎯 核心四步开发流程

1. Specify (许愿): 描述你要做什么,为什么做,就像产品经理提需求。

2. Plan (蓝图): AI 生成详细的技术方案文档,这是最关键的 checkpoint。

3. Tasks (拆解): 将蓝图分解为可执行的任务清单。

4. Implement (实现): AI 基于 Tasks 逐个击破,渐进式编码。

✨ Spec-Kit 核心优势

• 🔧 多AI代理支持: 支持 Claude Code、GitHub Copilot、Gemini、Cursor、Qwen 等主流 AI 辅助工具
• 📋 模版驱动质量: 通过结构化的模版体系(constitution、spec、plan、tasks),确保开发质量内建
• 🎯 全局架构: 不仅仅是做单个功能,而是从架构蓝图出发,让 AI 理解全局设计意图
• ✅ 严格 TDD 工作流: 强制走"规格→计划→任务→实现"的严格流程,避免野路子开发
• 🔄 自动化工作流: 从需求自动生成任务、从任务驱动代码实现、任务完成自动打钩
• 📝 可执行的规范: 规范不是死文档,而是 AI 执行的依据,可以随时追溯和审计

📦 傻瓜式安装

# 安装 uv 包管理器 (Python 3.11+)curl -LsSf https://astral.sh/uv/install.sh | sh# 全局安装 Spec-Kit CLIuv tool install specify-cli --from git+https://github.com/github/spec-kit.git# 初始化项目 (在项目目录下执行)specify init . --ai claude# 验证安装specify check

🎮 使用示例

在 Cursor、Claude Chat 等 AI 工具中输入 Slash 命令:

# 1. 立项目规矩 (Constitution: 编码规范、架构约束、团队约定)/speckit.constitution 使用 TypeScript,禁止 any 类型。组件必须单一职责。# 2. 许愿需求 (Specify: 描述做什么)/speckit.specify 开发一个个人照片墙应用。功能:1.展示本地图片;2.点击图片放大预览;3.支持暗黑模式切换。# 3. AI 生成技术方案 (Plan: 这一步是核心检查点!)/speckit.plan 使用单页应用结构,CSS 使用 Flexbox 布局,图片数据暂时 mock 在 JS 数组中。# 4. AI 拆解任务/speckit.tasks# 5. AI 开始编码实现/speckit.implement

什么是 Constitution (宪法)?

Constitution 是 Spec-Kit 的"项目宪法",定义了整个项目的最高原则。AI 之后生成的所有代码都会遵守这些规则。它可以包含:

• 编码规范: 语言选择、命名约定、代码风格
• 架构约束: 分层结构、设计模式、技术栈限制
• 团队约定: 注释要求、提交规范、测试覆盖率

2.2 OpenSpec:完整执行流程 - 从零到归档的完整实战案例

OpenSpec 是 Fission AI 推出的工具,它的理念是 Change-Driven (变更驱动),每一次修改都是一个独立的"提案"。

🚀 完整工作流进度

流程解读: 

1. 创建提议: 描述要做什么变更,AI 生成 Proposal。

2. 审核规格: 检查 AI 生成的规格说明是否准确,这是关键检查点。

3. AI 实现: AI 基于审核通过的规格自动编码。

4. 测试验证: 确保变更符合预期。

5. 归档文档: 将变更合并到主 Spec,形成项目知识库。

✨ OpenSpec 核心优势

• 📋 变更隔离: 每个 Proposal 独立管理,互不影响
• 🔍 规格审核: 强制人工审核 AI 生成的规格,提前发现问题
• � 工作流可视化
  : 提供清晰的进度追踪,随时掌握实施状态
• 🗂️ 知识沉淀
  : 归档后自动合并到主 Spec,形成项目知识库
• �️ 工具化封装
  : 命令行工具执行,稳定性高于纯 Prompt

📦 傻瓜式安装

# 全局安装 (Node.js 20.19+)npm install -g @fission-ai/openspec@latest# 初始化项目 (在项目目录下执行)openspec init# 验证安装openspec --version

🎮 使用示例

# 1. 创建变更提案/openspec:proposal 增加图片点赞功能,每个图片下方显示心形图标和点赞数。# 2. 查看生成的提案openspec listopenspec show add-like-feature# 3. 如果需要调整规格更新 spec,点赞时需要有一个弹跳动画效果。# 4. 确认后执行实现/openspec:apply add-like-feature# 5. 功能完成后归档/openspec:archive add-like-feature

2.3 一句话总结:选谁?

3. 实战血泪:当"许愿"遇到现实

讲完流程和优势,现在聊聊真实使用体验——这才是这篇文章的核心价值。

3.1 从"翻译官"到"许愿池"的范式转变

传统 VB Coding(Vibe Coding)模式下,我们其实是开发同学做中转站: 

产品需求 → [脑补+转化] → 实现描述 → AI 生成代码

Spec-Kit 和 OpenSpec 试图替代的,就是那个"脑补+转化"的过程:

产品需求 → [Spec 框架] → AI 生成方案 → AI 生成代码

它们的目标是替代 80% 的"转化"工作,剩下 20% 留给你做 HIL(Human-in-the-Loop)的验收与调整。

这带来了什么?

惊喜的一面: 效率爆炸式提升:

• 无需前置认知: 你可以在完全不了解项目的情况下就开始工作
• 工作中建立认知: 通过 AI 生成的 Plan/Proposal,边实施边学习业务逻辑
• 无痛切换项目: 从一个陌生项目跳到另一个陌生项目,只需"许愿"即可启动

硬币的另一面: 风险也在累积:

• 如果你没有足够的认知去做 HIL(Human-in-the-Loop)验收,就像盲审一份天书
• AI 生成的方案可能看起来"很有道理",但隐藏了大量边界情况和逻辑漏洞
• 一旦最终代码 Bug 成堆,你之前节省的时间会全部还回去,甚至翻倍

结论: 这些框架是"杠杆",用得好撬起千斤,用不好砸到自己脚。

3.2 Spec-Kit 的"惊艳"与"裂开"

惊艳时刻:番茄时钟的"外挂加持"

我曾让 Spec-Kit 生成一个完整的番茄时钟 Web 应用(纯前端项目),体验堪称外挂:

• 25分钟工作、5分钟休息的计时逻辑一次到位
• UI 组件(计时器、任务列表、统计图表)结构清晰
• 本地存储、通知提醒、主题切换等功能完整实现
• 代码符合 Constitution 约定,无明显幻觉

这种体验就像有一个资深前端工程师附体,能力仿佛无边。Spec-Kit 最适合做 Epic 级别的单端项目(纯前端或纯后端)。

裂开瞬间:前后端集成的灾难

当我贪心地让它同时生成前后端项目时,它崩了:

• 前端调用 /api/user,期望 { name: string }
• 后端返回 /api/user,给的是 { username: string }
• 集成时:Boom!接口对不上,一堆 404 和类型错误。

核心问题:Task 之间的契约缺失

Spec-Kit 在拆解 Task 时,是"各生成各的":

• 前端 Task:"实现用户信息展示,调用后端接口"
• 后端 Task:"实现用户信息接口"

但它们之间没有共享的接口契约。Task 更多关注"功能性需求怎么做",却忽略了"服务间怎么交互"这类非功能性约束。

3.3 OpenSpec 的"丝滑体验":给 VB Coding 套上标准流程

OpenSpec 和 Spec-Kit 不同,它更接近 VB Coding。

可以理解为:它给传统的 VB Coding 套了一层标准化流程,并且替代了部分"开发同学翻译需求"的工作。

核心特点: 

• 轻量化: 相对 Spec-Kit 更轻量,Proposal 机制更灵活
• 工具化执行: 命令行工具封装核心逻辑,输入输出结构化,稳定性高
• 变更隔离: 每个 Proposal 独立管理,即使换 Host(Cursor → Claude Code)或换模型,执行依然稳定

适合日常使用吗?

可以,一直用这个工具也没啥大问题。

但有个小槽点: 如果你已经很清楚怎么实现,而且就几句话的事儿,非要走一遍 Proposal → Review → Apply → Archive 流程,让 AI 先"设计"再"实现",然后你再调整……多少有点脱裤子放屁了。

这时候直接 VB Coding 敲几行代码更快。

4. 模型竞技场:Claude 4.5 Sonnet vs GLM 4.7

最近我一直尝试用 "Cursor + GLM 4.7" 走 VB Coding 路线,体验非常惊艳,甚至感叹 GLM 4.7 在代码生成上约等于 Claude 4.5 Sonnet 了。

直到我用它跑这两个 Spec 框架。

4.1 GLM 4.7 的"偏科"现象

具体表现

• 做翻译工具(VB Coding): GLM 4.7 很优秀
• 当你已经把需求拆解成具体的代码指令时,GLM 4.7 执行得很好,代码质量高。
• 这就像你是建筑师,它是工人,你说"砌这面墙",它能砌得又快又好。

• 做产品经理(Spec 方案生成): GLM 4.7 力不从心

• 在 Spec-Kit 的 Plan 阶段和 OpenSpec 的 Proposal 阶段,GLM 4.7 表现出明显的逻辑短板。
• 症状:

• 需求理解浮于表面: 只复述需求,不提解决方案。比如"简单权限控制:谁创建就归属谁",生成的方案只说"需要权限控制",但不说前端怎么存用户名、怎么传给后端、按钮如何根据归属隐藏。最后生成代码时直接写死,所有人都看不到按钮。

• 增量设计缺乏上下文: 做新功能时不考虑已有代码,自己另起炉灶。比如在现有项目加"需求池"概念,方案里有需求池管理了,但登录后还是直接跳需求列表,丢失需求池 ID,导致后续操作全乱套。
• 全局影响考虑不足: 新增一个核心维度(如需求池 ID)时,方案里有的资源加了这个字段,有的没加,测试时一堆 Bug。

•     后果: 

• 方案浮于表面,实现时无所适从,只能瞎猜或写死
• 需求越复杂,遗漏的关键设计越多,调试成本指数级增长

根本原因

GLM 4.7 在复杂逻辑推理和方案规划上还有待提升。它像一个优秀的"搬砖工",但还不是一个合格的"架构师"。

结论: 

• 如果你的需求已经拆解得很清楚,直接用 GLM 4.7 做 VB Coding,性价比极高。
• 如果你需要复杂的方案规划(Epic 级需求),Claude 4.5 Sonnet/OPS 依然是目前的 King。

5. 避坑指南与使用小妙招

5.1 别当你不知情的"甲方"

核心原则: 不要指望框架能弥补你对业务认知的缺失。

如果你不了解业务,盲目"许愿",会陷入这样的恶性循环:

1. 生成的 Plan 你看不懂,但觉得"看起来挺专业",直接让 AI 实现

2. 代码生成完了,跑起来发现各种 Bug

3. 因为你不知道 AI 是怎么设计的,调试时完全摸不着头脑

4. 原本想节省的时间,全部还回去,甚至翻倍

正确姿势: 

• 把生成的 Plan 或 Proposal 文档当成学习资料
• 从 AI 的方案中反向学习业务逻辑和技术实现
• 不要做甩手掌柜,至少要理解核心流程

5.2 人为补充接口契约:Constitution 的不稳定性

针对前面提到的"Task 契约缺失"问题,理论上的解决方案是:

在 Constitution 中约定: 

/speckit.constitution 对于前后端分离项目,必须在 Plan 中生成 OpenAPI 3.0 格式的接口契约。前后端 Task 必须基于同一份契约实现。

现实很骨感: 

这样做的效果并不稳定,时有时无:

• 有时 AI 会乖乖生成接口契约
• 有时完全忽略这条规则,直接跳过
• 即使生成了,格式和完整性也参差不齐

为什么会这样?

因为这种约束纯靠提示词,依赖 AI 的"自觉性":

• 模型有时候会遵守
• 模型理解能力弱,或者上下文太长,就会"选择性失明"

你必须做的: 

• Review Plan 文档时,手动检查是否生成了接口契约
• 如果没有,通过 HIL(Human-in-the-Loop)与 AI 沟通补充
• 这增加了人工介入成本,但目前别无他法

展望:Skill 机制的价值

这种本该定制化增强的地方,我们很难去对现有框架做修改。纯靠提示词约定又不稳定。

但如果我们用 Skill 机制,就可以快速对已有工作流做增强:

• 把"生成接口契约"固化成脚本
• 在 Plan 阶段强制执行,而不是"建议" AI 执行
• 这才是真正可靠的解决方案

(关于 Skill 机制的深入探讨,留待后续文章中展开)

5.3 OpenSpec 的粒度控制:一次别许愿太多功能

OpenSpec 虽然丝滑,但也有个坑:一次 Proposal 不要塞太多功能。

症状: 

• 功能遗漏: 你许愿了 5 个功能,最后生成的可能只包含 3 个,另外 2 个凭空消失
• 逻辑混乱: 多个功能之间的依赖关系没理清,生成的代码前后矛盾
• 幻觉增多: 功能越多,AI 越容易"脑补"一些你没说过的东西

建议粒度: 

• ✅ 单功能 Proposal: "增加用户头像上传功能"
• ✅ 紧密相关的 2-3 个功能: "增加用户头像上传、裁剪、预览功能"
• ❌ 一次塞太多: "增加用户管理、权限系统、日志审计、通知中心"(这种就炸了)

如果需求确实很大怎么办?

• 拆成多个 Proposal,按依赖顺序逐个实现
• 每个 Proposal 完成后 Archive,再开启下一个
• 这样既保证质量,又能清晰追溯每次变更

5.4 测试兜底:SDD 的生命线

这是一个容易被忽视但至关重要的洞见:VB Coding 可以不写测试,但 SDD 必须有测试做兜底。

VB Coding 为什么可以不写测试?

在传统 VB Coding 中:

• 你直接描述"怎么做"(实现细节)
• 所有的测试 AC(验收标准)其实都已经在你的功能描述中了
• AI 只是把你的描述翻译成代码
• 即使不生成测试,功能也不会偏移,还节省 token 和时间

SDD 为什么必须有测试?

在 Spec-Kit/OpenSpec 中:

• 你只描述"做什么"(需求层面)
• AI 需要自己把需求转化为方案,再转化为代码
• 这个转化过程只能保下限,难保上限

没有测试兜底的风险: 

1. 功能遗漏: 你许愿了 5 个功能,最后只实现了 3 个

2. 功能偏离: 实现了,但和你想的不一样

3. 非功能性问题: 性能差、安全漏洞、边界情况未处理

4. 回归问题: 新功能把老功能改崩溃了

测试的三重价值: 

• 自动验证: 每次生成后自动跑测试,快速发现问题
• 规格锁定: 测试用例其实是可执行的规格说明
• 自修复能力: 测试失败时,AI 可以根据失败信息自动修复

建议: 

• VB Coding 场景:测试可选,看个人喜好
• SDD 场景(Spec-Kit/OpenSpec):测试必选,否则根本不可用

5.5 提示词的艺术:借助已有知识提升规范质量

在设置 Constitution 或 Proposal 时,不要傻傻地一条一条列规范,AI 懂的知识比你想象的多。

高效提示技巧: 

• ❌ 低效做法: "代码要简洁、变量名要有意义、函数不要太长……"(啰嗦且不深刻)
• ✅ 高效做法: "遵循《重构》中的坏味道定位,避免代码坏味道"(一句话激活 AI 的知识库)

更多例子: 

• "遵循《设计模式》中的 SOLID 原则"
• "参考《代码整洁之道》的命名和函数设计规范"
• "按照《领域驱动设计》的分层架构组织代码"

本土化改造：中文交互更友好

如果觉得英文交互不友好,可以直接把这些命令的提示词翻译成中文: 

• skills、命令、rule、工作流……这些本质上都是 Markdown 文档
• 找到对应的 .md 文件,把英文翻译成中文即可
• 后续所有交互就都是中文了

我把翻译好的中文版本整理在了这里:中文版 Spec-Kit/OpenSpec 提示词配置

记住: 提示词的重心是提示,而不是教学。AI 懂的比你想象的多,你只需要"点到为止"。

5.6 工具封装 vs 纯 Prompt:一个有意思的发现

在实际使用中,我发现了一个值得思考的现象:

OpenSpec 在某些场景下表现更稳定,可能的原因:

• OpenSpec: 核心逻辑封装在命令行工具中(
  openspec init, openspec list),工具直接操作文件系统,输入输出结构化
• Spec-Kit: 生成方案文件的逻辑

实际案例:Spec-Kit + Cursor + GLM 的混乱

当我在 Cursor 中使用 GLM 4.7 运行 Spec-Kit 时,明显出现了混乱:

• 文件写飞: Plan 文档被写到了项目空间外面(因为 Git 根目录在外层,模型理解出现偏差)
• 路径错乱: Tasks 生成的代码路径不一致,有的在
  src/,有的在 ./
• 上下文丢失: 换一次 Chat 窗口,AI 就找不到之前生成的方案目录

为什么会这样?

猜测 Spec-Kit 的很多操作是通过 Prompt 引导 AI,让 AI 自己调用 Host 提供的文件操作工具。

• 模型理解能力强(Claude):能准确理解上下文,找对路径
• 模型理解能力弱(GLM):容易理解偏差,路径乱飞
• 当然还有host对特定模型的适配有关

实际对比: 

启发: 

这也在教我们如何做平台无关和密闭性更好的 AI 工具:

• 沉淀工具来执行逻辑,而不是完全依赖 Prompt 引导模型调用 Host 工具
• 工具封装可以屏蔽环境差异和模型能力差异,提供一致的执行保障
• 这也是 Skill 机制的实践推荐: 把核心逻辑封装成脚本,Prompt 只负责调用

建议: 

• 如果团队会频繁切换工具或模型,优先 OpenSpec
• 如果追求最高质量方案生成,Spec-Kit + Claude 4.5 是黄金组合
• 如果要用 GLM 4.7,建议只用于 VB Coding,避免用于 Spec 框架

5.7 工时估算参考:3 小时 MVP 的"翻车"实录

我用 Spec-Kit 和 OpenSpec 完成了一个 敏捷实践-开卡-估点平台 项目，这是一次"惊喜"与"惊吓"并存的实战。

第一阶段:顺风顺水的 MVP (Claude 4.5)

• 用时: 1 小时
• 工具: Cursor + Claude 4.5 Sonnet
• 方案review: 0 (完全信任 AI)
• 代码量: 0 行(全部 AI 生成)
• 质量: 非常高，几个小 Bug 提示一下就修好了，功能完整可用

第二阶段:"闭眼"迭代的灾难 (GLM 4.7)

看到 Claude 4.5 生成的质量这么好，我飘了。心想:"既然这么稳，不如让 AI 晚上自己慢慢跑，我明早起来就是一个完整的产品！"

于是我:

1. 一口气提了 4-5 个新需求(有的还是需要大重构的)

2. 用 CC Ralph Wiggum 让 AI 自己"挂机"逐个实现

3. 满怀期待地睡觉去了

第二天早上醒来，傻眼了: 

• 我忘记 CC 绑定的是 GLM 4.7，不是 Claude 4.5
• 生成的代码一塌糊涂: 
• 新功能和老功能逻辑冲突
• 有的需求只实现了一半
• 有的直接把原来能跑的功能改崩了
• 更要命的是:项目没做 Git 管理
• 没有版本历史，没法回滚
• 只能挨个修 Bug，像在救火

修 Bug 用时: 3 小时(这还是前后端技术栈我都熟悉的情况)

血泪教训

教训 : "闭眼生成"必须有回退保障

如果你要让 AI "挂机生成"，必须做好这些保障: 

• ✅ Git 版本管理: 每次 Proposal 实现前都提交一个 commit
• ✅ 分支隔离: 新功能在独立分支上做，验证通过再合并
• ✅ 测试兜底: 每次生成后自动跑测试，失败就中断

如果没有这些保障: 

• 大面积重构可能直接救不回来
• 你会花比生成代码更多的时间去修 Bug
• 最后可能只能推倒重来

6. 总结回顾

这两个工具能加入团队开发吗?

答案:可以,但有门槛。

最大的风险在于认知差: 

• 如果团队成员不了解业务和项目,盲目"许愿",出了 Bug 调试成本会很高
• 建议使用姿势:把生成的文档当成"技术导师",而不是"黑盒工厂"

适用场景: 

• ✅ Epic 级新项目(冷启动): Spec-Kit + Claude 4.5
• ✅ 不熟悉的项目,快速迭代增量需求: OpenSpec + Claude 4.5
• ✅ 熟悉的项目,无论需求大小: VB Coding(最稳妥的选择)

如果今天你只记得一句话

不要指望框架能弥补你对业务认知的缺失,但它们能成为你将"愿望"转化为"现实"的加速器。

延伸阅读

• GitHub: Spec-Kit
• 敏捷实践-开卡-估点平台