Devlab Tech Debt Ops

---
name: devlab-tech-debt-ops
description: "技术债全生命周期运维：审计分析\u2192建议报告\u2192确认后重构（微观+宏观）\u2192回归验证。覆盖从\u201c发现债务\u201d到\u201c安全消除\u201d的闭环。Triggers on \"\u91cd\u6784\", \"\u6280\u672f\u503a\", \"\u6280\u672f\u503a\u5ba1\u8ba1\", \"audit\", \"god class \u592a\u5927\", \"\u62c6\u5206\u6a21\u5757\", \"refactor\", \"tech debt\", \"\u4ee3\u7801\u592a\u4e71\u8981\u91cd\u6784\", \"tech debt audit\"."
---

# 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 审计报告必须经用户确认后才进入后续阶段。

## 推荐触发方式

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

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

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