把能跑但没测试的 AI 原型代码加固为可上线产品：先建安全网…

当你想给一个能运行但不敢改的 vibe-coded 原型补测试、重构并做生产加固时，用这套九阶段可恢复流程按序推进。

适用场景

解决思路

1. 先恢复进度：动手前先读 docs/IMPROVE-CODE-QUALITY-PLAN.md 和 Journey Map 中列出的所有产物；若 tracker 已存在，用 3-5 行总结当前进度并询问用户从哪个阶段进入，确认入口后才继续——有 tracker 的旅程只恢复不重启。
2. 仅在首次运行时做 Intake：无 tracker 时先问 7 个问题（应用做什么、最坏后果；下一个要改的模块及 git log 高 churn 或核心域；现有自动化测试与测试命令是否绿；技术栈框架/ORM/数据库；是否已上生产及活跃用户量；调用了哪些外部依赖；现在想做多少阶段），然后创建 docs/IMPROVE-CODE-QUALITY-PLAN.md，把每个阶段标为 pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason，并让用户确认阶段计划。
3. 阶段进入：宣布该阶段做什么、强制做什么决策、产出什么产物、大致工作量，提供 proceed / skip / defer 三个选项；标为 GATE 的阶段可 defer 但不可 skip；用户选择后把该阶段标为 in-progress。
4. 技能调用与降级：加载该阶段对应的 skill 并用它来跑这个阶段（Invoke 行给出 slug）；若不可用，提供 npx skills add wondelai/skills/<slug> --global；用户拒绝则按该阶段的 Brief（最小可行方法）执行，并说明当前处于哪种模式。
5. 阶段内决策：对每个 'Decide with the user' 下的问题都提问，给出具体选项和你的推荐，并把选择记入 tracker 的 Key Decisions——静默做出的决策视为缺陷。
6. 阶段退出：写入前先把产物草稿内容给用户签字确认；批准后写入或扩展 docs/ 文件，更新 tracker（状态、Key Decisions、Next Actions）；文件写完且该阶段行显示 done 才算完成。
7. 产物纪律：写前先读；文件缺失才创建，否则只扩展——新增或更新你的章节，保留他人内容；docs/ 下文件名用大写；每条建议都落成复选框或带 owner 和 priority 的表格行；首次创建 docs/ 文件时参考 references/artifact-templates.md，用完整骨架（所有章节标题）创建后再填本阶段指定的章节。
8. Phase 1 是门禁，提交保持单一目的：任何阶段都不得触碰 Safety Net Map 之外的代码（未列出即未固定，Gaps 列中的条目同样禁止）；结构性变更与行为变更绝不放在同一个 commit——先在结构-only commit 中保持测试全绿地重构，再在独立 commit 中改行为；重构中测试变红要回滚并以更小步骤重试，而不是调试；补安全网测试和更新 docs/ 各自是独立的单一目的 commit。
9. Phase 1（working-with-legacy-code，GATE）：用三轴启发式（即将修改、高 churn、核心域）确认起始模块；从入口方法画 effect sketch、找 seam、用最小侵入的接缝（Parameterize Constructor 带生产默认值；对单个埋藏调用用 Extract and Override）打破内联依赖；写 characterization test 拍下实际行为——先断言一个错的值，读失败信息，再固定真实值；时间不够全覆盖时用 Sprout/Wrap 包住新代码并把未测试宿主记为债务；characterize 时发现的 bug 只固定错误行为并记入 Debt Ledger，绝不静默修复（调用方可能依赖该怪癖），并让用户确认接受。产物：创建 docs/TESTING.md（含 ## Test Strategy、## Safety Net Map（module | pinned behaviors | test files | gaps）、## Characterization Backlog）和 docs/TECH-DEBT.md（含 ## Debt Ledger（item | location | type | risk | effort | priority | status）、## Sprout / Wrap Register）。完成条件：目标模块行为已固定、测试套件全绿、两个文件存在、Phase 1 显示 done——之后才解锁后续阶段。
10. Phase 2（clean-code）：用 clean-code skill 对目标模块打分，要求给出六大纪律的 0-10 分、按优先级排序的 top ten 修复，以及错误处理审计（裸 catch、返回 null、无上下文错误）；命名揭示意图（elapsedTimeInDays 而非 d），布尔读作谓词，函数只做一件事、处于同一抽象层级、参数 0-2 个（flag 参数等于两个函数）；命令查询分离（改状态或返回值，不可兼得）；错误处理优先异常而非返回码、捕获具体类型、绝不返回或传入 null（用空集合、Optional 或 Null Object），每个抛出的错误都带操作与状态上下文。与用户决定：哪些修复现在做、哪些记为债务，团队今后采用的命名/错误处理约定，以及 clean-code 分数是否成为 CI 门禁。产物：扩展 docs/TECH-DEBT.md，在 ## Smell Inventory（smell | location | refactoring | status）加行，并在 ## Adopted Conventions 记录约定。完成条件：模块得分 8+ 或所有低于 8 的缺口都是 Smell Inventory 行且有修复方案、约定已记录、Phase 1 测试仍通过。
11. Phase 3（refactoring-patterns）：用 refactoring-patterns skill 处理有坏味道的函数并配合 Phase 1 测试，要求它命名每个坏味道、引用对应重构手法、一次只应用一个并在每次之间跑测试；每个坏味道映射到具名重构，Extract Method 是主力——想写注释解释某块就把它提取出来并以注释命名；还包括 Replace Magic Number with Symbolic Constant、Replace Nested Conditional with Guard Clauses、Replace Conditional with Polymorphism、Introduce Parameter Object；流程为测试绿→一次变换→测试绿→提交，测试红则回滚而非调试；用 Preparatory Refactoring（先让改动变容易，再做容易的改动）和 Rule of Three 防止过早抽象。与用户决定：本轮处理哪些坏味道、即将到来的功能是否值得先在其插入点做 Preparatory Refactoring、重构后的模块是否加入 TESTING.md 的 CI 门禁列表。产物：扩展 docs/TECH-DEBT.md 的 ## Smell Inventory，记录每个坏味道所用的具名重构及状态。完成条件：目标坏味道都有具名重构和 done / ticketed 状态、测试全绿、结构变更落在结构-only commit 中。
12. Phase 4（software-design-philosophy）：用 software-design-philosophy skill 处理已触及的模块集合，问哪些类是浅的、信息在哪里跨边界泄漏、如何合并为接口更简单的深模块；模块深度 = 功能 ÷ 接口复杂度，深模块用小接口隐藏机器，浅模块则相反（classitis）；合并总是一起出现且共享状态的浅类；警惕信息泄漏（一个决策反映在多个模块）和按执行顺序而非知识划分的 temporal decomposition；这是战术到战略的翻转，投入 10-20% 保持设计干净。与用户决定：现在做哪些合并、哪些延后，防止过度合并无关关注点。产物：扩展 docs/TECH-DEBT.md 的 ## Smell Inventory，加入 classitis / 浅模块 / 信息泄漏条目及所做的合并。完成条件：每个浅模块簇已合并或记为带修复方案的行、接口数量没有为“模块化”而增长、测试全绿。
13. Phase 5（clean-architecture）：用 clean-architecture skill 配合当前模块图和 Intake 得到的技术栈，要求它画出依赖图、列出所有业务逻辑 import ORM 或框架的违规、并展示如何抽取为框架无关、位于自有接口之后的 Use Case；依赖规则：源码依赖指向内层——Entities → Use Cases → Interface Adapters → Frameworks/Drivers，内层不得命名外层；数据库和 Web 是细节，是你规则的插件；用依赖倒置强制：Use Case 拥有 repository 接口，Postgres/Stripe 实现放在外层适配器；SOLID 是中观工具；共享同一数据模型的微服务是分布式单体——先在服务内部应用该规则。与用户决定：本轮把边界推到多远、先包装哪些供应商（支付、存储）、计划中的服务拆分是否要等到服务内边界成立（避免分布式单体）。产物：扩展 docs/ARCHITECTURE.md，在 ## Layer Map & Dependency Rule（violation | location | fix | status）记录分层与当前违规，在 ## Decision Log 记录边界选择。完成条件：每条依赖规则违规都是带修复方案的跟踪行、至少最高风险供应商已包装、业务规则测试无需框架即可运行、测试全绿。
14. Phase 6（pragmatic-programmer）：用 pragmatic-programmer skill 扫描整个代码库，要求它标出重复的知识（忽略巧合性重复）以及需要封堵的破窗和未跟踪 TODO；DRY 针对知识而非文本——去重同一规则出现在两处（如客户端与服务端校验），放过巧合的相似；正交性：改一个组件不应影响另一个；破窗理论：立即修复 hack 或用带跟踪的 ticket 封堵，绝不留未跟踪的 // TODO；可逆性：把第三方供应商包在自己的接口后；曳光弹：下一个功能做成一条真实端到端的薄切片，而不是逐层搭建。与用户决定：每轮迭代的债务预算和破窗政策——什么现在修、什么开 ticket。产物：扩展 docs/TECH-DEBT.md，把重复知识和破窗项记入 ## Debt Ledger，把约定政策记入 ## Debt Budget & Broken-Windows Policy 和 ## Adopted Conventions。完成条件：重复知识命中已入账或修复、无未跟踪 hack 残留、债务预算政策已写下。
15. Phase 7（release-it）：用 release-it skill 配合 Intake 得到的外部依赖，要求审计无超时的调用、给出熔断器与舱壁的放置位置、以及深度健康检查 + RED 指标 + 告警设计；通过 QA 的软件不等于能在生产存活，集成点是一号杀手——慢响应比没有响应更糟；不可妥协项：每个出站调用都要有 connect + read 超时；失败依赖上要有熔断器（跳闸、快速失败、半开恢复）；用舱壁隔离资源池；重试要指数退避 + 抖动；对累积杂物做稳态清理；用 feature flag 和 expand-contract 迁移把部署与发布解耦；加深度健康检查、RED 指标、基于症状的告警。与用户决定：熔断阈值、哪些依赖配专属资源池、告警症状与阈值（错误率、延迟）。产物：创建 docs/RELIABILITY.md，含 ## Integration-Point Audit（dependency | timeout | circuit breaker | bulkhead | retry policy | status）、## Health Checks & Metrics、## Deploy vs Release。完成条件：每个出站调用都有超时、关键依赖有熔断器和舱壁、存在深度健康检查 + RED 指标 + 症状告警、已安排对累积杂物的稳态清理、发布无需重新部署即可回滚、审计表中关键路径无未决行。
16. Phase 8（system-design）：用 system-design skill 配合 Intake 得到的负载现实，要求给出平均与峰值 QPS、年度存储量、最先成为瓶颈的组件，以及按优先级排序的缓存/队列/副本动作且不过度设计；从需求而非方案出发；粗略估算：QPS = 日活用户 × 每日操作数 ÷ 86,400，峰值取平均的 2-5 倍；存储 = 每日记录数 × 大小 × 保留期；按顺序扩展：先垂直扩展，再对读密集路径用缓存（cache-aside 带 TTL 和显式失效），然后读副本，最后才分片；用消息队列把慢工作从请求路径解耦；套用已知设计（限流器 → token bucket 返回 429 Retry-After）。与用户决定：现在做哪些扩展动作、哪些延后，并与真实数字挂钩（别在 50 用户时为 5 万用户设计），以及第一个移到消息队列后的慢工作负载（如有）。产物：扩展 docs/ARCHITECTURE.md 的 ## System Context 记录负载现实与粗略估算数字；扩展 docs/RELIABILITY.md 的 ## Query & Resource Findings 记录无界查询与瓶颈。完成条件：QPS 与存储数字已记录、第一个瓶颈已命名、每个扩展动作要么已应用要么延后并写下触发数字。
17. Phase 9（ddia-systems）：用 ddia-systems skill 配合 Intake 得到的数据库和 Phase 8 的副本计划，要求它找出易发生 write skew 的 read-then-write 路径、说明实际默认隔离级别及其异常、并修复高风险路径；数据比代码活得久；多数数据库默认 read-committed 或 snapshot 而非 serializable——朴素的先读后写会触发 write skew（两个请求都卖掉最后一件商品）；用 SELECT ... FOR UPDATE 或 serializable 事务显式修复，并弄清真实默认值；一旦有副本，复制延迟意味着 read-your-writes 和 monotonic reads 必须刻意设计；数据模型匹配访问模式；polyglot persistence 常常是对的；把 system-of-record 与派生数据分开（CDC / 事件溯源），而不是双写。与用户决定：哪些路径需要加锁、哪些用 serializable 事务，以及新工作负载（搜索、feed）是否值得用 CDC 同步的第二个数据存储。产物：扩展 docs/ARCHITECTURE.md 的 ## Data & Storage Decisions 记录隔离级别、加锁路径、polyglot / 派生数据选择；在 ## Decision Log 记录理由。完成条件：默认隔离级别已记录、每条易 write skew 路径已加锁或改为 serializable、任何新数据存储都有明确的同步机制。
18. 可选阶段：当业务逻辑因代码不讲领域语言而纠缠时，插入 domain-driven-design（在 Phase 5 边界建立后立即插入），产物为扩展 docs/ARCHITECTURE.md 的 ## Bounded Contexts & Context Map 和 ## Domain Glossary (Ubiquitous Language)；可选阶段遵循同样的操作规则，像核心阶段一样加载并使用对应 skill。
19. 避免常见错误：不要在写第一个测试前清理代码（先用 Phase 1 的 characterization test 固定行为，安全网门禁所有后续阶段）；不要让 agent 把代码“模块化”成一堆小类（用深模块规则合并总是一起出现的浅类，减少接口而非增加）；不要调用无超时的外部 API（Phase 7 给每个出站调用加 connect + read 超时，关键依赖加熔断器）；不要在没做容量估算前扩展（先做粗略估算，数字# 通常说明缓存和读副本有数年余量）；不要把微服务当成架构（先在服务内应用依赖规则，共享一个数据模型的服务是分布式单体）；不要假设数据库是 serializable（查实际默认隔离级别并给 read-then-write 路径加锁，write skew 能通过所有单用户测试）。
20. 按顺序交付而非一次全做：Phase 1-3（安全网、可读性、重构）在真实用户到来前完成；Phase 5 边界在代码库再翻倍前收益最大；上线前加固 Phase 7（即使低流量，超时和熔断器也不是可选项）；Phase 8-9 跟随实际增长数字。
21. 退出清单（每项都绑定产物）：业务规则有无需数据库或框架即可运行的测试（TESTING.md Safety Net Map 对已改模块完整）；每个出站调用有超时、关键依赖有熔断器、深度健康检查 + RED 指标接入基于症状的告警（RELIABILITY.md Integration-Point Audit 清空、Health Checks & Metrics 填好）；依赖规则成立——业务逻辑不 import 框架或 ORM（ARCHITECTURE.md Layer Map 违规已关闭）；数据库隔离级别已知且 read-then-write 路径已加锁（ARCHITECTURE.md Data & Storage Decisions）；无未跟踪 hack 残留，每个延后项都是带优先级的 Debt Ledger 行（TECH-DEBT.md）。
22. 关闭 tracker：每个阶段为 done 或 skipped: reason，剩余 Next Actions 转入 TECH-DEBT.md 的 Debt Ledger 以免丢失；然后路由后续：代码库是老旧庞大而非年轻混乱时继续用 remove-technical-debt skill；下一个系统需要从第一天就有意设计结构时继续用 design-code-architecture skill。

适用边界 · 注意事项

• 代码库是老旧庞大而非年轻混乱时，应改用 remove-technical-debt skill。
• 需要从零设计新项目结构时，应改用 design-code-architecture skill。
• 只针对单一框架做隔离优化时，直接调用对应 skill，不必走这套九阶段流程。