Claude Superpowers+子代理流水线把HTML 单页迁移到 Vue 3 工程复盘

Nitro Hsu

• 7 min read

前情提要

最近在将一个H5单页Demo项目迁移到生产环境的Vue工程上，尝试使用CC的subAgent能力从规划、任务拆分、代码编写到测试验证全流程跑一下，看看CC的真实输出能力。
起点：单文件 amap.html（高德地图 + weixin JS-SDK）
终点：基于 Vite 8 + Vue 3 + TS 的组件化工程，13 次主线提交全部落入 main

1. 起点与目标

amap.html 是一份典型的"先能跑再说"产物：

  • 一个 HTML，内联 <script> 把高德 SDK、weixin JS-SDK、URL 参数读取全都塞在一起。
  • 通过 wx-miniprogram web-view 嵌入到小程序内使用，也允许直接浏览器访问。
  • 没有类型、没有测试、AMap key 和 securityCode 硬编码在源码里。

目标：在保留全部运行时行为的前提下，把这份 HTML 拆进 h5/（Vite + Vue 3 + TS 模板），让它从此跟随工程化体系演进——组件、composables、lib、api、env、单元测试一应俱全。

约束：

  • 不重构、不增功能：行为对齐为最高优先级。
  • 直接提交 main（用户授权）。
  • .env.development 不入库；只追踪 .env.example 占位。

2. Superpowers 工作流：三个串联的 skill

整次会话主线只走了一条 skill 链：

brainstorming  →  writing-plans  →  subagent-driven-development
阶段 产物
brainstorming 4 个澄清问题 → 设计 spec 落盘
writing-plans 13 个任务的详尽实施计划（含逐字代码）
subagent-driven-development 13 个 implementer + 多轮 review + 1 次 whole-branch review + 1 次 fix

skill 的价值不在"我给你写代码"，而在强制结构化：先收敛问题，再写下设计与计划，最后让一组专一的子代理去执行——主代理只负责调度、监督、收尾。整次会话的主代理几乎没有自己写过业务代码。

3. 任务拆分：13 个 commit 一一对应

设计文档落地后，写 plan 时把工作切成 13 个自包含、可单独验收的任务。每个任务都有：明确的输入文件、产出文件、验证命令（vue-tsc -b、vitest run）、commit 命令（包含 Co-Authored-By 脚注）。

每个 commit 都是 review 通过后才落，diff 都很小、可独立回滚。

4. 架构设计

数据流（迁移前 = 一个 <script> 块；迁移后）：

URL 参数 ─► query.ts ──► MapPage.vue (lat/lng/title)
                              │
env (.env.*) ─► loadFilters() ─► MapPage.vue (filters)
                                          │
                                          ▼
                                useAmap({ container, center, onComplete, onMarkerClick })
                                          │
                       ┌──────────────────┼──────────────────┐
                       ▼                  ▼                  ▼
                  AMap 实例          MarkerCluster        marker click
                                                              │
                                                              ▼
                                                          lib/wx.ts ─► 小程序 navigateTo

为什么这样切？

  • lib/：纯函数无副作用（除了 wx.ts 对 window 的访问），最容易单测。
  • api/：未来接后端时只需改这一层；当前 fetch 失败、env 缺失、items 空都回落到 DEFAULT_FILTERS。
  • composables/：把"地图实例的生命周期"封装成 hook，组件只关心容器和回调。
  • components/：纯展示组件，全部 v-model / emit 驱动，无业务依赖。
  • views/：唯一可以读 env、读 URL、跨组件协调的层。

5. 子代理执行流水线

每个任务都按这个模式跑：

                     ┌─► spec reviewer ─┐
implementer  ───────┤                   ├──► 验收通过 → commit
                     └─► code reviewer ─┘
                              │
                              ▼
                       发现问题 → 回到 implementer 修复

特例：

  • Task 1（npm 依赖判断有歧义）的 spec/code review 拆开跑了两个子代理。
  • Task 3–13 的 spec + code review 合并到一个子代理里跑（依据 plan 中 "OK to merge" 标记）。
  • 13 个任务全部落库后追加一次 whole-branch review——这是关键一步。

模型选择

角色 模型 理由
主代理（调度 + 监督） Opus 4.7 全局判断、风险评估
Task 1 implementer Sonnet 4.6 涉及 npm 版本兼容性判断
Task 2–13 implementer Haiku 4.5 任务高度机械化（plan 给了逐字代码）
所有 review 子代理 Sonnet 4.6 需要交叉对照需求与代码
Whole-branch review Sonnet 4.6 一次性看全部 14 个文件，需要更长 context
FIX implementer Haiku 4.5 单点修复

结论：当 plan 写到足够细的程度，Haiku 4.5 完全能做执行端；review 则必须放回 Sonnet——它在"代码读得懂 vs 代码真的对"之间能持出更稳的判断。

6. Token 消耗与 Tool 调用统计

数字按子代理累计估算，主代理自身不计；调度成本约占 20% 上下。

子代理 数量 估算 token 估算 tool 调用
Implementer（含 1 个 FIX） 14 ~326K ~137
Spec / Code review（含合并者） 14 ~329K ~140
Whole-branch review 1 ~92K ~19
合计 29 ~747K ~296

工具分布大致：

  • Read ≈ 45%（review 占大头，反复对照 plan 与实现）
  • Write / Edit ≈ 25%（implementer 写文件）
  • Bash ≈ 22%（npm install、vitest run、vue-tsc、git diff/commit/log）
  • Grep / Glob ≈ 8%（少量定位）

值得注意：whole-branch review 的 92K token 是整次会话单笔最值的开销——它是唯一抓到 useAmap 时序 bug 的环节（详见 §8）。

7. 代码编辑情况

类型 数量
新增文件 14
修改文件 6
删除文件 4
不入库 1

13 commit 的实际 diff 体积都很小：

  • 最大单笔：Task 11 *.vue 约 110 行新增
  • 最小单笔：Task 4 *.ts 8 行 + 测试 30 行

8. 反思：这条流水线的得与失

得

  1. plan 写到足够细 → Haiku 可以做执行端。13 个任务里 12 个用 Haiku 跑下来零返工。
  2. fresh implementer per task：每个子代理 context 极小，"忘记之前任务"反而是优点——它只能按 plan 写，写不出多余的耦合。
  3. review 用 Sonnet 是稳妥选择。多次抓到 implementer 的命名漂移、scope 越界、import 路径不一致。
  4. whole-branch review 不可省。这是单文件 review 永远抓不到的层级。
  5. Co-Authored-By 脚注让 commit 历史可溯源，未来 git blame 时一眼能看出是哪个模型写的。

失

  1. Token 总消耗 ~747K——单论交付一份不到 1000 行的代码，这是高成本路径。手写应该是 50K 量级。当任务规模小、确定性高时，这条流水线性价比并不划算；它真正赚回成本的场景是中等复杂度、多文件、行为对齐有风险的迁移／重构。
  2. Task 2 commit scope drift：implementer 把 8 个未追踪的模板基线文件一并 add 进了 commit。事后选择"接受 + 注释"而非 amend——因为 amend 是有风险的不可逆操作。教训：plan 里应当显式要求 git add 仅指定文件，不要用 -A。
  3. plan 里的 bug 会被忠实复刻。useAmap 的时序问题在 plan 阶段写错，13 个 implementer + 13 次 review 都没拦下来。最终靠 whole-branch review 兜住——但如果连这一步也没做，bug 就会被首次浏览器测试发现，迭代成本更高。
  4. .env.development 真实值进入了开发者本地磁盘但未入库——这是正确做法，但 plan 里应该更明确地说明"切换分支时需要重新放置 env 文件"。

一句话总结

Superpowers 不会让代码自动正确。它让流程正确，剩下的可靠性靠 review 里的好模型 + 一次 whole-branch view 兜底。当任务规模超过单人单次会话能稳定握住的体量时，它的边际收益开始显现。
标准的软件开发流程能一步拥有，主动权从人的经验论主动让位到流程定义。
就当前这个任务量看，Token消耗还是很高，主要集中在Read/Review阶段。

京ICP备16014945号-1