技术债清理 / 死代码移除

归属：docs/guides/sops/ 触发：清理无引用代码、死资源、遗留导出、技术债项 关联概念：04-refactor、flow-code、flow-review

场景定义

移除没有任何消费者的死代码 / 死资源，或清理明确欠下的技术债项。与重构（04-refactor，改结构）不同，技术债清理以删除 / 简化为主，同样要求行为保持。

目标与不做什么

• 目标：安全移除无引用代码，降低维护面，保持行为不变。
• 不做：不删除仍被引用的公共 API；不把「疑似无用」但无确证的代码删掉（需验证）。

标准方法论（行业通行）

借鉴死代码清除与技术债管理的通行做法：

1. 盘点：用引用分析工具 / 搜索确认候选死代码——无任何引用、无测试覆盖、非对外公开 API。
2. 验证可移除：区分「内部死代码」与「可能被外部消费的公开接口」；对有风险的不确定项，先确认消费者再删。
3. 行为保持移除：删除后全量回归必须绿；删除本身不改行为。
4. 技术债登记（可选）：对无法立即清理的债项，登记在技术债清单，标注影响与优先级，避免反复考古。
5. 小步提交：按「一次一类死代码」小步删除，每步测试绿，便于回退。

本项目落地流程

1. 盘点候选：用搜索 / 静态分析找出无引用导出、死资源、无调用链代码；区分内部死代码与疑似公开接口。
2. 确认移除安全：对不确定项（可能被外部消费的公开 API、生成代码、文档引用的标识符）先确认消费者，再决定删 / 保留 / 标注 deprecated。
3. 行为保持移除：在独立分支 chore/<slug> 或 refactor/<slug> / worktree 内删除，跑相关测试 + 全量回归确认绿。
4. 可选技术债清单：对有遗留价值的债项，在 docs/dev/tech-debt.md 登记（含影响、优先级、关联 Issue）。
5. 审查与合并：复用 flow-review；审查确认「删除不涉及行为变更、未误删被引用代码」；CI 绿后合并。
6. 清理：销毁 worktree。

验证与门禁

• [ ] 被删代码确证无引用 / 无消费者（或已确认外部安全）
• [ ] 删除后全量回归（npm test）绿
• [ ] 未误删仍被引用的代码
• [ ] 审查确认行为保持 + CI 绿

产出物

• 死代码移除 commit（chore/<slug> 或 refactor/<slug> PR）
• （可选）技术债清单 docs/dev/tech-debt.md

复用与新增资产

• 复用：flow-code（worktree 编码）、flow-review（审查合并）、flow-tdd（如需回归测试）。
• 新增（缺口）：chore/<slug> 分支约定；技术债清单规范。

反模式 / 注意事项

• 删除仍被引用的公开 API / 生成代码。
• 凭感觉「疑似无用」就删，不做引用与消费者核验。
• 一次删除大量无关死代码（难回退、难审查）。
• 删除后不跑回归，掩盖破坏。
• 把死代码移除夹带进无关功能 PR。