devlab-tech-debt-ops

用途

技术债全生命周期运维：从审计发现、分级建议，到确认后的安全重构（微观/宏观），再到回归验证。不只是"怎么拆"，还回答"该不该拆、先拆哪里、拆到什么程度"。

边界：只处理技术债（可维护性/结构/复杂度），不改变业务语义；业务需求变更走外层 SDD 框架（trellis/comet/mattpocock，见 devlab-harness-ops Step 7）。

适用场景

• 审计场景：项目需要盘点技术债分布、严重度、优先级，产出审计报告供决策。
• 微观重构：单文件/单类内部整理（提取方法、消除重复、简化条件分支）。
• 宏观重构：跨模块/架构级拆分（god-class 拆解、引擎解耦、分层重构）。
• 引用清零：大范围重命名/搬迁/删除旧实现，需安全地"引用清零"。

不适用场景

• 加新功能（走外层 SDD 框架，见 devlab-harness-ops Step 7）。
• 业务逻辑本身要变（那是业务债，不是技术债）。
• 一次性小改动（直接改即可，不必起编排）。

输入

• 目标代码单元（类/模块/引擎/整个项目）与痛点描述。
• 现有测试覆盖情况。
• 约束：是否允许破坏性变更、时间盒、微观/宏观/混合。

输出

• 审计报告（债务分布图 + P0-P3 分级 + 建议优先序 + ROI 评估）。
• 现状固化文档（架构/流程/组件职责/问题分层）。
• 拆分设计（目标模块划分 + 职责边界 + 迁移映射）。
• 分步重构任务清单（小步、每步可回退、可验证）。
• 回归结果（行为不变的证据）。

工作流

Phase 0: 审计（Audit）
  [微观] 扫描代码坏味道（长方法/重复/复杂条件/过深嵌套）
  [宏观] 扫描架构债（循环依赖/god-class/分层违规/耦合度）+ 深化机会（浅模块/抽象泄漏，见 references/REFERENCE-DEEP-MODULE-DESIGN.md）
  -> 产出审计报告：债务清单 + P0-P3 分级 + 建议优先序 + ROI 估算
  -> ⛔ Gate G0：审计报告确认，用户决定处理范围

Phase 1: 现状梳理与固化（不改代码）
  [微观] 记录当前方法/类内部结构与职责
  [宏观] 梳理目标单元的架构/执行流程/模块间依赖
  -> 形成固化 md 作为重构依据
  -> ⛔ Gate G1：现状与问题清单确认

Phase 2: 建立安全网
  [微观] 补齐单元测试/行为快照测试
  [宏观] 补齐集成测试/端到端表征测试（characterization tests）
  -> 无测试的高风险路径先补测试再动
  -> ⛔ Gate G2：安全网是否覆盖将要改动的行为

Phase 3: 拆分设计
  [微观] 提取方法/变量/参数对象/Guard Clause 设计
  [宏观] 目标模块划分 + 职责边界 + 从旧到新的迁移映射
  -> 按需选用设计模式（见 references/REFERENCE-DESIGN-PATTERNS.md），切勿过度设计
  -> ⛔ Gate G3：拆分方案确认

Phase 4: 小步重构 + 引用清零安全移除
  [微观] 逐个提取/重命名/简化 -> 单元测试通过 -> 提交
  [宏观] 抽取/搬迁模块 -> 更新调用侧 -> 集成测试通过 -> 提交
  -> 删除旧实现前，先把旧引用"清零"（搜索确认零引用）再删
  -> 破坏性变更必须同步所有调用侧

Phase 5: 回归验证
  [微观] 单元测试全量通过 + 行为快照对比
  [宏观] 集成/端到端回归 + 行为对比，证明"行为不变、结构变好"

关键原则

• 行为不变：技术债重构不改可观察行为；用测试锁住行为再动结构。
• 小步可回退：每一步都是一次可独立提交/回滚的最小变更，避免大爆炸式重构。
• 引用清零再删除：删旧代码前先搜索确认零引用（含 tests/tools），清零->删除->跑测试三步走。
• 按需用模式，不过度：设计模式是手段不是目的；具体选型让 AI 结合场景给选项。
• 审计先行：不确定该不该拆时，先跑 Phase 0 审计，用数据说话。
• 深模块优先：拆分不只“把大的拆小”，更要“把浅的做深”——大量行为藏在小接口之后、落在可测接缝（见 references/REFERENCE-DEEP-MODULE-DESIGN.md）。

reference

• references/REFERENCE-DESIGN-PATTERNS.md -- 设计模式清单 + 典型模式示意性伪代码（点到即止；何时用/不用）。
• references/REFERENCE-DEEP-MODULE-DESIGN.md -- 深模块设计与架构深化审计（取精华自 mattpocock/skills codebase-design/improve-codebase-architecture + Ousterhout APOSD）。

与其他 devlab-* Skill 的关系

Skill	关系	说明
外层 SDD 框架（trellis/comet/mattpocock，见 devlab-harness-ops Step 7）	上游	重构以 spec 三件套承载（现状=requirements，拆分=design，步骤=tasks）
devlab-ai-agent-engineering	邻接	重构 AI 应用时参照其分层管道目标形态
devlab-eval-driven-agent	下游	重构后用评测集证明行为不变
devlab-srv-reliability-ops / infra-reliability-ops	并行	重构中出现运行期问题时只读诊断（研发服务/基础设施）

约束

• 不改业务语义；发现"其实是业务需求变更"时，转外层 SDD 框架（见 devlab-harness-ops Step 7）。
• 无安全网不动高风险路径 -- 先补表征测试。
• 每步可回退；禁止一次性大范围不可回退改动。
• 设计模式伪代码仅示意，不硬编码具体实现/框架。
• Phase 0 审计报告必须经用户确认后才进入后续阶段。

推荐触发方式

用 devlab-tech-debt-ops 帮我审计一下这个项目的技术债，给出优先级建议

这个 XXHandler 一千多行太乱了，用 devlab-tech-debt-ops 帮我安全拆分（宏观重构）

这个方法太长了，帮我做微观重构：提取方法+消除重复