tech-debt

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow

技术债务

每次调用 AskUserQuestion 都遵循 .claude/docs/automation-modes.md （协作模式始终提问 · 引导模式仅针对重大事项提问 · 自主模式记录并继续； automation_always_ask 类别始终提问）。

阶段 1：解析子命令

根据参数确定模式：

• scan — 扫描代码库中的技术债务指标
• add — 手动添加一条技术债务记录
• prioritize — 重新确定现有债务登记表的优先级
• report — 生成当前债务状态的摘要报告

如果未提供子命令，输出用法说明并停止。判定：失败 — 缺少必需的子命令。

---

阶段 2A：扫描模式

搜索代码根目录（根据 .claude/docs/code-root-resolution.md 解析： 按引擎选择 src/、Assets/ 或 Source/）中的债务指标：

• TODO 注释（计数并分类）
• FIXME 注释（这些是伪装成债务的 Bug）
• HACK 注释（需要妥善解决的变通方案）
• @deprecated 标记
• 重复代码块（多个文件中存在相似模式）
• 超过 500 行的文件（可能是上帝对象）
• 超过 50 行的函数（可能存在复杂度问题）

将每项发现分类：

• 架构债务：抽象不当、缺少模式、耦合问题
• 代码质量债务：重复、复杂度、命名、缺少类型
• 测试债务：缺少测试、不稳定的测试、未测试的边缘情况
• 文档债务：缺少文档、文档过时、未记录的 API
• 依赖项债务：过时的包、已弃用的 API、版本冲突
• 性能债务：已知的慢速路径、未优化的查询、内存问题

在展示任何内容之前，先确认确实有内容可供扫描。 统计扫描实际覆盖的源文件数。如果代码根目录未能解析，报告 NOT ASSESSED — code root unresolved 并按下文所述停止。如果该数量为 零 — 代码根目录不存在，或其中没有源文件 — 则报告：

NOT ASSESSED — no source files to scan. 代码根目录中没有代码，因此“未发现债务指标”只是对空搜索结果的描述，并不代表代码库的情况。待实现工作开始后再运行一次。

并停止。不要写入登记表，也不要输出 COMPLETE 判定。

这一区别正是扫描的关键：在 400 个文件中未发现任何问题，说明代码库状况良好；在 0 个文件中未发现任何问题，则完全没有提供信息。 将两者都显示为“COMPLETE — scan findings written to register”，会让人以为是前者。报告发现时必须注明分母，即使数量很大且发现数确实为零，也要注明。

向用户展示发现。

询问：“我可以将这些发现写入 docs/tech-debt-register.md 吗？”

如果可以，更新登记表，绝不覆盖现有内容。**追加前先匹配：**如果某项发现与现有 Open 条目的文件和债务类型相同，则更新该条目，而不是添加重复项。如果某个现有 Open 条目的模式已不再出现在对应文件中，则将其列为 Resolved [date] 的建议项，并将这些条目一并纳入同一次审批。判定：COMPLETE — 扫描发现已写入登记表。

如果不可以，到此停止。判定：BLOCKED — 用户拒绝写入。

---

Phase 2B：添加模式

使用纯文本提示询问用户描述和受影响的文件。

作为子 Agent 运行？ lead-programmer 会预加载此技能，而子 Agent 没有 AskUserQuestion。在一条回复中返回以下三个问题（类别、工作量、影响），每个问题都简要列出选项，然后停止：由调用你的一方询问用户。收到回答前，不得将任何内容写入登记表。

然后使用 AskUserQuestion 收集类别：

• 提示词："这项技术债务属于什么类别？"
• 选项：
  • [A] Architecture Debt — wrong abstractions, missing patterns, coupling issues
  • [B] Code Quality Debt — duplication, complexity, naming, missing types
  • [C] Test Debt — missing tests, flaky tests, untested edge cases
  • [D] Documentation Debt — missing/outdated docs, undocumented APIs
  • [E] Dependency Debt — outdated packages, deprecated APIs, version conflicts
  • [F] Performance Debt — known slow paths, memory issues, unoptimized queries

然后使用 AskUserQuestion 收集预计修复工作量：

• 提示词："修复此项预计需要多少工作量？"
• 选项：
  • [A] S — Small (under 1 day)
  • [B] M — Medium (1–3 days)
  • [C] L — Large (3–7 days)
  • [D] XL — Extra Large (over 1 week)

然后使用 AskUserQuestion 收集若不修复的影响——登记表中的 Impact 列，/tech-debt prioritize 会根据该列进行评分：

• 提示词："如果永远不修复，这会造成什么代价？"
• 选项：[A] Low / [B] Med / [C] High / [D] Critical

向用户展示完整的新条目。

**追加前先匹配：**如果现有的 Open 条目中有文件和类别都相同的条目，向用户展示该条目，并询问是否更新该条目，而不是添加重复项。

询问："可以将此条目追加到 docs/tech-debt-register.md 吗？"（如果匹配到条目，则询问"可以更新现有条目吗？"）

如果可以，则追加条目（或更新匹配的条目）。结论：COMPLETE — 条目已添加到登记表。

如果不可以，则在此停止。结论：BLOCKED — 用户拒绝写入。

---

Phase 2C：优先级排序模式

读取 docs/tech-debt-register.md 中的债务登记表。如果文件不存在： 结论：NOT ASSESSED — docs/tech-debt-register.md 中没有登记表；请先运行 /tech-debt scan。停止。

根据每项自身的列进行评分：impact ÷ effort，其中 Impact 的 Low 为 1、 Med 为 2、High 为 3、Critical 为 4，Effort 的 S 为 1、M 为 2、 L 为 3、XL 为 4，四舍五入到小数点后一位并写入 Priority。分数越高越靠前；分数相同时，Added 日期较早的条目优先。Impact 或 Effort 为 — 的条目不评分：将其列在已评分条目之后，并标记为"未评分 — [列名] 未评定"，不得猜测评分。

按优先级分数重新排序登记表，并建议下一次冲刺应纳入哪些条目（对于没有冲刺的 workflow: minimal，则建议接下来构建哪些条目）。

向用户展示重新排序后的登记表。

询问："可以将重新排序后的登记表写回 docs/tech-debt-register.md 吗？"

如果可以，则写入更新后的文件。结论：COMPLETE — 登记表已重新排序并保存。

如果不可以，则在此停止。结论：BLOCKED — 用户拒绝写入。

---

Phase 2D：报告模式

读取债务登记表。如果文件不存在：结论：NOT ASSESSED — 没有可供报告的登记表；请先运行 /tech-debt scan。停止。

生成汇总统计：

• 按类别统计未结条目，并计算这些条目的预计修复工作量总和
• 根据各条目的 Added 日期和 Resolved [date] 状态，统计当前冲刺中新增和已解决的条目
• 趋势方向（增长／稳定／缩减）——统计该时间段内新增与已解决的条目

标记在登记表中存在超过 3 个冲刺的条目。

向用户输出报告。此模式为只读模式——不会写入任何文件。结论：COMPLETE — 债务报告已生成。

阶段 3：后续步骤

• 运行 /sprint-plan，将高优先级技术债务项安排到下一个冲刺中（对于没有冲刺的 workflow: minimal，改为将它们添加到简报的构建顺序中）。
• 在每个冲刺开始时运行 /tech-debt report，跟踪技术债务趋势。

技术债务登记表格式

## Technical Debt Register
Last updated: [Date]
Total items: [N] | Estimated total effort: [T-shirt sizes summed]

| ID | Category | Description | Files | Effort | Impact | Priority | Status | Added | Sprint |
|----|----------|-------------|-------|--------|--------|----------|--------|-------|--------|
| TD-001 | [Cat] | [Description] | [files] | [S/M/L/XL] | [Low/Med/High/Critical] | [Score] | [Open / Resolved YYYY-MM-DD / Accepted — reason] | [YYYY-MM-DD] | [Sprint to fix or "Backlog"] |

每个添加行的技能——包括此技能，以及将偏差记录为技术债务的 /story-done——都必须按以下顺序填写全部十列；创建文件的技能必须先写入上方的表头和表格标题：

• ID — TD- 加三位数字，比登记表中已有的最高 ID 大一（新登记表使用 TD-001）。ID 永不重复使用。
• Category — Scan Mode 下六个类别之一，去掉“Debt”：Architecture、Code Quality、Test、Documentation、Dependency、Performance——使用 /story-done 写入的拼写，以便 Report Mode 能将它们正确归类。
• Description — 说明技术债务是什么，以及为何承担它。
• Files — 受影响的路径，以逗号分隔；如果技术债务不涉及单个文件，则填写 —。
• Effort — 使用 Add Mode 中的 S、M、L 或 XL；如果尚未估算，则填写 —。
• Impact — Low、Med、High 或 Critical：表示不修复时的代价；如果尚未评估，则填写 —。
• Priority — /tech-debt prioritize 写入的分数；运行该命令前填写 —。
• Status — 添加时填写 Open。Resolved YYYY-MM-DD 表示技术债务修复日期；Accepted — reason 表示经慎重考虑后决定保留。
• Added — 写入该行的日期，格式为 YYYY-MM-DD。Report Mode 根据此日期和 Resolved 日期统计新增和已解决的项目。
• Sprint — 安排修复该项的冲刺，或填写 Backlog。

规则

• 技术债务本身并非坏事——它是一种工具。登记表用于跟踪经过慎重考虑的决策。
• 每条技术债务记录都必须说明接受它的原因（截止日期、原型、信息缺失）。
• “Scan”每个冲刺至少应运行一次，以发现新的技术债务。
• 超过 3 个冲刺仍未处理的项目，应予以修复，或经慎重考虑后接受，并记录原因。