tech-debt

技术债

概览

本文件中的路由器将技术债的两种互补立场拆分开来：

• 模式 A — 预防： 在你进行更改时，将代码调整到预期的最终状态。删除已失效的兼容路径，而不是保留它。
• 模式 B — 分类处理： 在你评估现有代码时，对技术债进行分类、评分和优先级排序，制定修复计划。

它们适用于技术债生命周期中的不同阶段：编写时预防，规划时分类处理。分类处理的结果会逐项反馈到预防中。

何时使用

以下情况使用模式 A：

• 你正在实现、收尾或审查某项功能、修复或重构，并且用户希望更改整洁明了。
• 你正准备保留一个回退方案、别名、模式标志或包装器，以防万一——先确认是否有调用方。
• 用户说“把这件事做好”“不要打补丁凑合”“零技术债”或“别留下烂摊子”。

以下情况使用模式 B：

• 用户要求进行技术债审计、代码健康度审查，或询问“我们应该重构什么？”
• 用户希望为维护或重构积压事项、路线图确定优先级。
• 技术债不断累积，没人确定应该先修复什么。

以下情况不要使用：

• 单个明显的局部问题，且没有结构性影响——直接修复，不要调用技术债框架。
• 风格或格式方面的小问题——让他们使用代码检查器或格式化工具，而不是这里。
• 绿地项目，且尚不清楚预期的最终状态（模式 A 无法针对尚未定义的目标）。

此技能的工作方式——路由器

此技能是一个路由器。 本文件保持精简，只负责协调。它会选择一种模式（或 A→B→A 链），然后你加载匹配的 references/*.md 并遵循其中的内容。 两份参考文档包含实际步骤、规则和示例。

绝不要将参考文档正文内联到此处。 如果某个分支的内容超过 2–3 行摘要，就应该放在 references/ 中。选择哪个分支的决策应留在此处。

原因：保持路由器精简，便于快速浏览；只有确认模式后才加载分支正文，可以避免在错误分支上浪费上下文。

路由

判断标准——任务的一个布尔属性：用户现在是否正在主动进行更改（正在编写或编辑代码，或已有差异）？yes → 模式 A；no → 模式 B。链式规则：分类出的条目一旦开始实施，就针对该更改切换到模式 A。

digraph tech_debt_route {
  rankdir=TB;
  node [shape=box];

  start  [label="User task touches tech debt" shape=oval];
  q      [label="Actively making a change\n(writing/editing code, has a diff)?" shape=diamond];
  a      [label="MODE A — PREVENT\nRework THIS change to the\nintended end state"];
  b      [label="MODE B — TRIAGE\nCategorize + score the\nwhole codebase's debt"];
  loadA  [label="Load references/prevent-during-change.md"];
  loadB  [label="Load references/triage-backlog.md"];
  chain  [label="Implementing a triaged item?\nSwitch to Mode A for that change" shape=diamond];

  start -> q;
  q -> a [label="yes"];
  q -> b [label="no — assessing existing code"];
  a -> loadA;
  b -> loadB;
  loadB -> chain;
  chain -> loadA [label="yes, per item"];
}

路由表

如果用户正在……	模式	加载
实现或收尾某项功能、修复或重构，并希望更改整洁明了	A	references/prevent-during-change.md
准备保留一个回退方案、别名或标志，以防万一	A	references/prevent-during-change.md
要求进行技术债审计／询问“我们应该重构什么”／要求审查代码健康度	B	references/triage-backlog.md
要求为维护或重构积压事项确定优先级	B	references/triage-backlog.md
修复分类处理中识别出的条目	A（逐项处理）	references/prevent-during-change.md

模式 A — 预防（更改期间）

从预期的最终状态出发重新设计更改，而不是沿着当前补丁的形成路径优化。着眼于应该存在的代码；删除失效的兼容路径，而不是改进它们。优先选择一个清晰的组件或流程，而不是模式标志。

加载 references/prevent-during-change.md 并遵循其中的内容。

模式 B — 分类处理（审计积压事项）

系统地识别、分类并确定代码库中现有技术债的优先级。生成带有工作量估算的优先级列表，以及可与功能开发并行推进的分阶段修复计划。

加载 references/triage-backlog.md 并遵循其中的内容。

总结

更改代码时预防新技术债；规划修复事项时分类处理旧技术债。