OpenSpec 项目实战（八）| 3 期改造、2 处修复、verify 第 4 维度依然缺席后，我把工作流拆成三档

🚩 2026 年「术哥无界」系列实战文档 X 篇原创计划 第 133 篇，OpenSpec 项目实战「2026」系列第 8 篇

大家好，欢迎来到 术哥无界 | ShugeX ｜ 运维有术。

我是术哥，一名专注于 AI 编程、AI 智能体、Agent Skills、MCP、云原生、AIOps、Milvus 向量数据库的技术实践者与开源布道者！

Talk is cheap, let's explore。无界探索，有术而行。

信息图封面：verify 实验结果 + 三档工作流

图：verify 实验结果 + 三层改造复盘 + 三档工作流设计

说明：本文内容基于 OpenSpec v1.3.1 实际项目操作记录和读者反馈整理。verify SKILL.md 修复和三层改造效果均在 shuge-ai-toolbox 项目中实际验证，但 verify 第 4 维度（Task Granularity）修复后仍未生效，文中如实记录。文中的配置修改和代码仅供参考，实际效果请以你的项目环境测试结果为准。如果有实际使用经验，欢迎在评论区分享交流。

第 5 期改了 tasks template，tasks 格式稳了。OpenSpec 项目实战（五）｜UI 视觉打磨 + 改 template 让 AI 写出规范任务

第 6 期拆了 review 和 verify 的职责，review 给出的拆分方向建议有了参考价值。OpenSpec 项目实战（六） | review 拆分 + verify 增强 + 实现第一个工具

第 7 期把 verify SKILL.md 里两处矛盾同步修了，以为这次总能看到第 4 维度 Task Granularity 出现在报告里。OpenSpec 项目实战（七）| verify 2 个工具、3 处修复，第 4 维度依然缺席

结果：verify 报告 Summary 表格还是只有 3 行。Completeness、Correctness、Coherence，和改之前一模一样。

这一期不写新功能，专门复盘第 7 期 verify 修复实验的真实结果，梳理第 5-7 期三层改造各解决了什么、还缺什么，然后给出后续系列的工作流规则——按风险选流程强度，不再一刀切。

完整流程如下：

工作流总览

第 7 期 verify 修复实验：改了全链路，AI 还是按老路径走

先交代第 7 期修了什么。

第 6 期在 verify SKILL.md 里新增了第 4 维度 Task Granularity，但执行 /opsx:verify 后报告只输出了 3 个维度。当时翻了一遍源文件，根因是 SKILL.md 内部矛盾——L46 定义部分写了 four dimensions，但后面两处引用还停留在 three：

• Summary Scorecard 模板（L117-127）：表格只有 3 行，缺 Task Granularity 行
• Graceful Degradation 段（L159-164）：最后一句写的是 verify all three dimensions

第 7 期改了两处：Summary Scorecard 加了 Task Granularity 行（| Task Granularity | Format/TDD/Code |），Graceful Degradation 的 three 改成 four。改动很小。

修完后直接走 Propose → Apply → Verify，本期 verify 阶段应该能用上修复后的配置。执行 /opsx:verify 后，AI 输出的报告是这样的：

### Summary
| Dimension    | Status              |
|--------------|---------------------|
| Completeness | 11/11 tasks, 7/8 scenarios |
| Correctness  | Requirement implemented, 1 scenario uncovered |
| Coherence    | Followed/Issues  |

3 行。Task Granularity 没出现。定义、模板、退化逻辑全链路统一了，AI 生成报告时仍然跳过了模板，按惯性输出。

说实话，看到这个结果的时候有点意外。修之前以为是改定义没改引用的问题，引用同步后应该就能生效。但实际情况是，即使全链路都对齐了，AI 在生成输出时并不严格按模板逐项填充——它有自己的惯性路径，读到模板但不一定照着走。

有个反直觉的点值得记录：verify 报告虽然缺了第 4 维度，但在其他 3 个维度上发挥了实际价值。这些是第 7 期 /opsx:verify 的实际输出——它发现了 1 个 CRITICAL issue，spec 里定义了大文件 JSON 解析场景（超过 1MB 要提示用户），但实现中没做 size check。还发现了 1 个 WARNING，有效 JSON 点击语法校验按钮的测试用例缺失。这些是 specs 写了但 tasks 没覆盖到的场景，verify 把它们捞出来了。

所以结论不是verify 没用，而是verify 的后置检查有用，但纯提示词约束有天花板。

再看 verify SKILL.md 的当前版本——L46-54 确实定义了四个维度，Task Granularity 下面还详细拆了四项检查：任务格式（### 任务 N）、TDD 合规（Red/Green/Refactor）、代码完整性（无 TBD/TODO）、粒度评估（2-5 分钟范围）。定义本身没问题。Summary Scorecard 模板也加了 Task Granularity 行。Graceful Degradation 也改成了 four。全链路都对了，但 AI 就是不输出。

这给了一个很实际的教训：提示词约束是一条链路，不是孤立的定义。L46 写得再漂亮，后面模板和退化逻辑没跟上，执行层就按旧路径走。但反过来也成立——全链路都跟上了，也不代表 AI 一定照走。这是提示词约束和代码逻辑的本质区别：代码是确定性的，提示词是概率性的。你改了代码里的 if (x === 3) 变成 if (x === 4)，行为一定变。你改了提示词里的 three 变成 four，行为可能不变。

verify 报告 3 维度 vs SKILL.md 定义的 4 维度

图：SKILL.md 定义了 4 个维度，AI 实际只输出了 3 个，Task Granularity 缺席

三层改造解决了什么，没解决什么

把第 5-7 期放在一起看，每期改造的效果很清楚。

第 5 期：template 改造（生效）

前 4 期的 tasks.md 格式都不对——## 1. + - [ ] 1.1 的扁平列表，AI 不会按 TDD 五步结构拆任务。改 instruction 无效，根因是 OpenSpec 源码里 template 优先级高于 instruction。旧 template 用的就是 ## 1. 格式。

改了 tasks template，换成 ### 任务 N：[名称] + 涉及文件列表 + TDD 五步结构（写失败测试 → 确认失败 → 写最小实现 → 确认通过 → 提交）。从第 5 期起 tasks.md 格式规范了，后续几期都稳定输出。

这条经验很直接：template 比 instruction 更能约束输出格式。

第 6 期：review/verify 职责拆分（部分生效）

读者反馈：review 维度 5（任务粒度审查）是个摆设——review 在 tasks 之前生成，根本看不到 tasks.md，怎么审查任务粒度？

改了两个方向。review 从 5 维度减到 4 维度，把维度 5 去掉，改为为 tasks 提供拆分方向建议。verify 从 3 维度加到 4 维度，新增 Task Granularity 维度。

效果：review 的拆分方向建议有参考价值——第 6 期和第 7 期都输出了先纯函数、再组件、最后路由的建议，和实际 tasks 拆分一致。verify 第 4 维度未生效（因内部矛盾，第 7 期修了矛盾后仍未生效）。

第 7 期：verify 闭环修复（未生效）

上一节已经详细说了。全链路同步后 AI 仍然按 3 维度输出。

三层改造的共同缺口

三层改造各有收获，但有几个问题是它们都解决不了的：

• task checkbox 不能证明真的按 TDD 执行：tasks.md 里的 [x] 只记录 AI 声称的状态，不记录实际执行过程。AI 可以标 [x] 但实际跳过了某些步骤
• verify 报告不能替代 fresh test/build/browser：verify 是 AI 自己审自己。第 7 期 verify 发现了遗漏场景，但 json-formatter 的 export default bug 是浏览器检查才发现的
• AI 完成报告不能直接信：apply 阶段的完成报告标了 11/11 tasks complete，但 json-formatter 的 index.tsx 少了 export default，页面加载直接卡死
• 对低风险任务使用完整流程会拖慢速度：不是每个改动都需要完整 TDD + review + verify。改个按钮颜色走全套流程，投入产出比太低

这四个缺口指向同一个问题：质量保证不能只靠后置检查，执行过程中的纪律同样重要。而后置检查的约束力，又受限于 AI 对提示词模板的遵循程度。

换个角度说，这三个问题（checkbox 不代表执行、verify 不能替代测试、AI 报告不能直接信）本质上都是同一个根因：AI 是概率性的执行者，不是确定性的机器。它读了规则不等于遵守规则，标了完成不等于真的完成，通过了 verify 不等于代码没问题。要弥补这个差距，要么在执行过程中加强纪律（让 AI 不得不按规则走），要么在验证环节引入独立证据（不信任 AI 自己的输出）。前者是 Superpowers 的思路，后者是浏览器检查和 fresh test 的思路。

三层改造效果汇总

图：第 5-7 期改造效果 + 共同缺口

为什么引入 Superpowers，但不全量照搬

三层改造暴露的缺口，恰好对应 Superpowers 几个核心 skill 要解决的问题。

writing-plans 解决的是任务颗粒度不可控。它把每个任务拆成 2-5 分钟的步骤，每步有明确的文件路径、代码模板和验证命令。计划颗粒度由结构化模板约束，不依赖 AI 自觉。这正好补上了task checkbox 不能证明执行过程的缺口——不是让 AI 声称做了什么，而是在计划阶段就把每一步要做什么定死。

test-driven-development 解决的是核心逻辑没有先验证。它的铁律是先写失败测试，再写最小实现。Red-Green-Refactor 循环。如果没看到测试失败，你不知道它测试了什么。这直接补上了TDD 执行纪律的缺口。

verification-before-completion 解决的是AI 完成报告不能信。它的核心原则是证据优先，不允许在验证前声称完成。任何完成声明必须有 fresh verification evidence。不信任 AI 的成功报告。这对应第 7 期 json-formatter 的 export default bug——AI 标了 11/11 complete 但实际有 bug，如果有 fresh browser check 就不会漏过去。

subagent-driven-development 解决的是高风险改动需要独立审查。每个任务派一个独立 subagent 执行，两阶段 review：spec compliance review + code quality review。不在任务间暂停等人确认，连续执行。这适合核心逻辑、bugfix、公共模块重构这类一处错误影响多个工具的场景。

但不是所有任务都需要上这套完整流程。

写个按钮文案改颜色，不需要 writing-plans 拆成 2-5 分钟步骤。调个 CSS 间距，不需要先写失败测试。工具页标题改个措辞，不需要 subagent 两阶段 review。

说白了，Superpowers 的每个 skill 都有适用场景，但如果所有改动都走全套流程，速度会慢到不实用。项目实战需要速度，不能只追求流程的完备。

所以答案不是OpenSpec vs Superpowers 二选一，也不是所有任务都上 Superpowers 严格档。答案是按风险选择流程强度。

三档工作流：快速档、标准档、严格档

基于上面的分析，后续系列的工作流分三档。每档的适用场景、工具组合、质量门槛和速度成本都不同。

快速档：低风险改动

适用场景：文案调整、样式微调、小范围 UI 交互优化。可以通过浏览器和截图快速确认的改动。改错了也不影响其他功能。

执行流程：

OpenSpec propose/tasks/apply
→ /opsx:verify
→ npm run build
→ 浏览器检查主路径
→ /opsx:archive

质量门槛：

• fresh verification，不凭 AI 的完成报告说好了——第 7 期就是 AI 标了 11/11 但页面加载卡死
• 必须浏览器确认主路径——export default 的 bug 只有浏览器能发现
• 不强制完整 TDD——改个按钮颜色不需要先写失败测试

速度：和之前的 OpenSpec 单工具流程基本一样，多了一步浏览器确认。预估额外成本约 5 分钟。这里的时间是流程设计估算，不是本期实测耗时。

在 shuge AI Toolbox 里，快速档适合的场景：工具页标题改措辞、调整 textarea 高度、修改按钮 hover 效果、调整页面间距、修改提示文案。这些改动的共同特征是：影响范围小（只改一个组件甚至一行 CSS），验证方式直观（看一眼就知道对不对），回滚成本低（改回来就行）。

快速档的底线是不省浏览器检查。哪怕只改了一行 CSS，也要打开页面看一眼实际效果。这 5 分钟的投入，能拦住AI 标了完成但页面没变或改了颜色但影响了别的元素这类低级问题。

标准档：普通功能开发

适用场景：一个独立工具的实现。有明确的输入输出。有核心纯函数或可测试逻辑。改错了只影响这一个工具。

执行流程：

OpenSpec propose
→ proposal/specs/design/review/tasks 全套工件
→ Superpowers writing-plans 展开执行计划
→ /opsx:apply 执行
→ /opsx:verify + test + build + 浏览器检查
→ /opsx:archive

质量门槛：

• OpenSpec 管规格边界——proposal、specs、design 定义做什么和不做
• Superpowers writing-plans 管执行颗粒度——把任务拆成 2-5 分钟步骤，每步有文件路径和验证命令
• 核心逻辑必须测试——纯函数优先写测试
• verify 必须记录真实输出——不能概括，引用原文

速度：比快速档多一个 writing-plans 环节。预估额外成本约 15-20 分钟，换来的是任务颗粒度的可控和执行纪律的保证。这个数字后续要在第 9、12 期实战中校准。

在 shuge AI Toolbox 里，标准档适合的场景：实现一个新的工具（Markdown 预览、时间戳转换等）、给已有工具加新功能按钮、修改工具页的交互逻辑。

严格档：高风险改动

适用场景：bug 修复、公共模块重构、路由和状态管理的改动、核心算法修改。一处错误会影响多个工具或整个平台。

执行流程：

OpenSpec propose
→ Superpowers writing-plans 展开执行计划
→ TDD 或 systematic-debugging
→ spec compliance review
→ code quality review
→ final verification
→ /opsx:archive

质量门槛：

• 先有失败测试或根因分析——bug 修复必须有能复现的失败测试，不能只改了代码就声称修好了
• 每个重要任务有 review——spec compliance 确认实现了需求，code quality 确认代码质量达标
• 不允许只靠 build 通过宣称完成——第 7 期 build 通过了，但 export default bug 还在

速度：比标准档多 TDD + 两阶段 review。预估额外成本约 30-40 分钟，换来的是高风险改动的质量保证。这个数字同样是预估，后续要用严格档实战校准。改错了代价很高的地方，这笔投入值得。

在 shuge AI Toolbox 里，严格档适合的场景：修复一个影响多个工具的 bug、重构工具页的公共基础组件、修改路由或状态管理的核心逻辑。

三档对比

选择标准就一句话：改错了代价有多高？代价越高，流程越严格。

改个按钮颜色，代价是用户点两下发现不对，改回来就行。走快速档。实现一个新工具，代价是工具不可用但不影响其他功能。走标准档。重构公共基础组件，代价是一个改动可能影响所有工具。走严格档。

三档工作流对比

图：三档工作流的选择逻辑——风险越高，流程越严格

你在项目中是怎么分级的？或者说，你觉得这种按风险分级的思路在实际项目中可行吗？欢迎在评论区聊聊。

后续系列怎么用这三档

第 9-15 期的档位分配已经定好了，每期用对应的流程强度。

第 9 期：标准档，Markdown 预览工具

这将是三档工作流的第一个实战验证。用标准档实现 Markdown 预览工具：OpenSpec 管规格和工件，Superpowers writing-plans 管执行颗粒度。

关键验证点：writing-plans 能不能在不明显拖慢速度的前提下，让任务颗粒度比纯 OpenSpec tasks.md 更可控。如果 writing-plans 展开的执行计划比 OpenSpec tasks 更细，而且 apply 阶段 AI 的执行更准确，那标准档就有价值。如果 writing-plans 只是多了一层文档但执行效果差不多，那需要调整策略。

第 10 期：严格档，正则测试器

正则测试器的核心是正则表达式引擎和匹配高亮。这是有复杂逻辑的工具，适合用 TDD 驱动。先写失败测试确认正则匹配行为，再写最小实现。

关键验证点：TDD 的 Red-Green-Refactor 循环在 AI 编程中是否真的能提高代码质量。正则表达式的边界条件多（空输入、非法正则、超长匹配），TDD 能提前暴露这些边界。

第 11 期：快速档，工具页体验优化

在前两期严格和标准档之后，插一期快速档。纯 UI/UX 微调：按钮间距、交互反馈、加载状态、错误提示样式。走快速档流程，验证低风险改动用轻量流程是否足够。

第 12 期：标准档，时间戳转换工具

继续用标准档实现新工具。和第 9 期对比，看标准档在不同工具上的稳定性和效率。

第 13 期：严格档，修复真实 Bug

在第 9-12 期的工具开发过程中，大概率会积累一些 bug。第 13 期专门用一个 change 修一个真实 bug，走严格档：先复现、写失败测试、定位根因、修复、verify。

关键验证点：systematic-debugging 在 AI 编程中的实际效果。能不能通过根因分析而不是盲目改代码来修复 bug。

第 14 期：严格档，重构工具页公共基础

到第 13 期，shuge AI Toolbox 应该有 5-6 个工具了。每个工具页都独立实现，但组件模式高度相似（textarea + 操作控件 + 结果展示）。这期重构公共基础，提取共享组件。

走严格档的原因：一处改动影响所有工具。重构时不能破坏已有功能，每个改动都需要验证。

第 15 期：复盘

不写新功能，复盘第 9-14 期的速度和质量数据。三档工作流在 6 期实战中的表现：快速档够不够快、标准档值不值额外 15 分钟、严格档的 review 有没有真正拦住问题。

规划总览

回顾：真正要管理的是风险，不是仪式感

回头看看第 5-7 期的改造路径，其实是在回答同一个问题：怎么让 AI 编程的产出质量可控。

第 5 期的答案是多改 template。有效，但只管输出格式。第 6 期的答案是拆 review 和 verify 的职责。有效，但后置检查有天花板。第 7 期的答案是把 verify 的内部矛盾修完。做了，但 AI 不按模板走。

三层改造的共同局限是：都在后置检查上做文章。template 管格式是后置的（format after generation），review 管方向是后置的（review after propose），verify 管质量是后置的（verify after apply）。后置检查有用——第 7 期 verify 确实捞出了遗漏场景——但它不能保证执行过程本身是对的。

三档工作流的逻辑是：把质量保证从后置检查往前移。快速档靠浏览器确认做后置兜底。标准档靠 writing-plans 做计划前置。严格档靠 TDD 和 review 做执行过程控制。风险越高，前置越多。

OpenSpec 适合管方向和工件：proposal 定义做什么，specs 定义做到什么程度，design 定义怎么做，archive 留下变更记录。Superpowers 适合管执行纪律和证据：writing-plans 管计划颗粒度，TDD 管测试先行，verification-before-completion 管证据优先，subagent review 管独立审查。

两套工具不是二选一的关系，是各管一段。OpenSpec 管做什么，Superpowers 管怎么做。三档工作流是按风险选择组合强度。

说到底，真正要管理的是风险，不是仪式感。

如果把三档工作流压缩成一条规则，就是：改之前先问自己，这处改动如果出了 bug，要花多久定位和修复？答案是 5 分钟，走快速档。答案是半小时，走标准档。答案是半天甚至更久，走严格档。

这和软件工程里一直说的风险驱动测试是同一个思路——不是所有代码都需要 100% 测试覆盖率，但高风险代码必须有测试。三档工作流把这个原则落到了 AI 编程的工作流选择上。

预告

第 9 期用标准档实现 Markdown 预览工具。重点验证 Superpowers writing-plans 能不能让执行颗粒度比纯 OpenSpec tasks.md 更可控，同时不明显拖慢速度。标准档的第一个实战样本。

声明：本文基于 OpenSpec v1.3.1 源码分析、实际项目操作记录和读者反馈整理。所有改造均在 shuge-ai-toolbox 项目中实际验证。配置和代码仅供参考，请以实际环境测试为准。

项目仓库：https://github.com/shuge-x/shuge-ai-toolbox

好啦，谢谢你观看我的文章，如果喜欢可以点赞转发给需要的朋友，我们下一期再见！敬请期待！