technical-debt-register

技术债务登记表技能

为团队或服务生成完整的技术债务登记表。债务登记表不是投诉清单，而是一份按优先级排序、考虑业务影响的清单，帮助工程团队审慎决定要偿还哪些债务、按什么顺序偿还，以及预期能获得什么回报。

良好的债务管理并非消除所有债务，而是确保债务清晰可见、有人负责，并在偿还债务的利息成本超过修复成本时予以解决。

必需输入

如果用户尚未提供，请询问以下信息：

• 团队或服务名称 — 此登记表涵盖的团队和／或服务
• 已知债务项 — 已知技术债务清单；或者请 Claude 通过询问以下方面来引导梳理：遗留代码、缺失的测试、过时的依赖项、架构捷径、手动流程、可观测性缺口、安全积压问题
• 技术栈 — 语言、框架、基础设施（帮助 Claude 正确分类和评分）
• 团队规模和开发速度 — 工程师人数，以及每个迭代的大致故事点数或天数（用于估算工作量）
• 当前季度／规划周期 — 以便路线图针对正确的时间范围

输出格式

---

技术债务登记表：[团队／服务名称]

团队： [名称] | 服务： [名称] 作者： [名称] | 最后更新： [日期] 规划周期： [第 [X] 季度 [年份]] | 审查频率： [每月／每季度]

---

概述

[用 2–3 句话描述团队当前的债务状况、主要债务类别和业务背景——例如，团队是否处于重视开发速度的增长阶段，或者即将迎来合规截止日期、因此安全债务尤为关键？]

登记表中的条目总数： [X] 未解决条目： [X] 高／严重优先级条目： [X] 预计总解决工作量： [X 故事点／X 工程师周]

---

债务类别定义

类别	说明	示例
代码质量	可以正常运行，但难以安全修改的代码	重复逻辑、层级过深的条件语句、不一致的错误处理、缺少抽象
架构	限制可扩展性或增加耦合的结构性决策	应当拆分的单体架构、应改为异步的同步调用、缺少领域边界
测试	测试覆盖缺口会增加回归风险	缺少单元测试、没有集成测试、测试套件不稳定、没有测试数据管理
安全	已知漏洞或缺失的安全控制	含有 CVE 的过时依赖项、缺少速率限制、硬编码密钥、身份验证不足
依赖项	过时或有风险的外部依赖项	已停止维护的库、主版本落后、已被弃用的包
基础设施	限制可靠性或开发人员效率的基础设施	手动部署步骤、没有 IaC、单可用区、缺少自动扩缩容
可观测性	可见性方面的缺口会拖慢事件响应	缺少指标、没有分布式追踪、日志结构不佳、没有针对关键 SLI 的告警
流程	手动或容易出错的运维流程	手动数据库迁移、没有操作手册、未记录的口口相传知识

---

债务登记表

评分方法

业务影响（1–5）：

• 5 — 阻碍增长、导致生产事故或带来合规风险
• 4 — 显著拖慢交付或增加事故发生的可能性
• 3 — 造成明显减速；尚可应对，但问题正在累积
• 2 — 造成轻微阻碍；近期风险较低
• 1 — 仅影响外观或属于理想化改进；目前没有业务影响

解决所需工作量（1–5，分数越低越容易）：

• 1 — <0.5 天；由一名工程师完成
• 2 — 0.5–2 天；由一名工程师完成
• 3 — 3–5 天；由一名工程师或小型搭档完成
• 4 — 1–2 周；需要团队协作
• 5 — >2 周；需要大量规划和协调

优先级评分 = 业务影响 × (6 − 工作量) （优先考虑影响大、工作量小的事项）

---

ID	事项	类别	业务影响（1–5）	工作量（1–5）	优先级评分	状态	负责人
TD-001	[例如：支付流程没有集成测试]	测试	5	3	15	待处理	[Name]
TD-002	[例如：身份验证库落后 3 个主要版本]	安全	5	2	20	待处理	[Name]
TD-003	[例如：数据库查询未使用连接池]	架构	4	2	16	待处理	[Name]
TD-004	[例如：[service] 的部署流程需要手动操作]	基础设施	4	3	12	进行中	[Name]
TD-005	[例如：订单处理函数长达 200 行，职责过多]	代码质量	3	3	9	待处理	[Name]
TD-006	[例如：没有结构化日志——仅使用纯文本]	可观测性	3	2	12	待处理	[Name]
TD-007	[例如：ORM 版本存在已知的 N+1 查询问题]	依赖项	3	3	9	待处理	[Name]
TD-008	[例如：没有[critical operation]的操作手册]	流程	3	1	15	待处理	[Name]
TD-009	[例如：测试覆盖率为 34%——缺乏有效的安全保障]	测试	4	4	8	待处理	[Name]
TD-010	[例如：应用代码中存在硬编码的配置值]	代码质量	2	1	10	待处理	[Name]
TD-011	[例如：服务部署在单个可用区，且没有故障转移]	基础设施	5	4	10	待处理	[Name]
TD-012	[例如：没有针对 [endpoint] 的 P95 延迟告警]	可观测性	4	1	20	待处理	[Name]

---

类别细分

Category distribution (by item count):
─────────────────────────────────────────────
Code quality     ████████░░  [X items]  ([X]%)
Architecture     ██████░░░░  [X items]  ([X]%)
Testing          █████████░  [X items]  ([X]%)
Security         ████░░░░░░  [X items]  ([X]%)
Dependencies     ███░░░░░░░  [X items]  ([X]%)
Infrastructure   ████░░░░░░  [X items]  ([X]%)
Observability    ████░░░░░░  [X items]  ([X]%)
Process          ██░░░░░░░░  [X items]  ([X]%)
─────────────────────────────────────────────

Priority distribution:
Critical (score 20–25): [X items]
High     (score 12–19): [X items]
Medium   (score  6–11): [X items]
Low      (score   1–5): [X items]

---

优先级最高的 5 项——解决计划

TD-XXX：[优先级最高的事项名称]

优先级评分： [Score] | 类别： [Category] | 负责人： [Name]

问题： [用 2–3 句话说明技术债是什么、表现形式，以及目前造成的痛点。请具体说明——引用实际事故、减速情况或风险。]

业务影响： [如果不解决会发生什么？请引用任何事故、险些发生的事故或增长障碍。例如：“该问题在上个季度导致了 2 起生产事故，并使此领域的任何变更都多出约 30 分钟的调试时间。”]

解决方案： [清楚描述修复方案。不要只写“改进代码”——请说明具体工作：“将支付处理逻辑提取到专用的 PaymentService 类中，编写单元测试以达到 80% 的覆盖率，并更新 3 个调用位置。”]

步骤：

1. [具体且可创建工单的步骤]
2. [具体且可创建工单的步骤]
3. [具体且可创建工单的步骤]

验收标准：

• [可衡量的标准——例如：“应用代码中不再存在硬编码的配置值”]
• [可衡量的标准——例如：“CI 流水线通过新增测试”]
• [可衡量的标准]

工作量估算： [X 个故事点 / X 天] 建议安排的迭代： [Q[X] Sprint [Y] / [dependency] 完成后]

---

TD-XXX：[优先级第二的事项名称]

优先级评分： [Score] | 类别： [Category] | 负责人： [Name]

问题： [描述]

业务影响： [影响描述]

解决方案： [方案描述]

步骤：

1. [步骤]
2. [步骤]
3. [步骤]

验收标准：

• [标准]
• [标准]

工作量估算： [X 个故事点 / X 天] 建议安排的迭代： [迭代或时间范围]

---

TD-XXX：[优先级第三的事项]

（遵循上述格式）

---

TD-XXX：[第四优先级事项]

（遵循上述相同格式）

---

TD-XXX：[第五优先级事项]

（遵循上述相同格式）

---

债务削减路线图

指导原则

• 每个冲刺分配 [X%] 的产能用于解决债务——健康团队建议分配 15–20%
• 无论优先级得分如何，安全和依赖项债务都按固定节奏处理
• 除非当前冲刺已安排解决债务，否则不得在存在 Critical 债务的模块中开展新功能工作
• 未解决而直接关闭的债务项（已接受／已延期）必须指定负责人和复审日期

季度计划

季度	重点领域	目标事项	预计产能	预期成果
[Q1 Year]（当前）	安全 + 可观测性	TD-002、TD-012、TD-006	[X] 点 / [Y] 工程师日	认证库更新至当前版本；延迟告警上线；结构化日志交付
[Q2 Year]	架构 + 可靠性	TD-003、TD-011、TD-004	[X] 点 / [Y] 工程师日	修复连接池；部署多可用区；完成部署自动化
[Q3 Year]	测试覆盖率	TD-001、TD-009	[X] 点 / [Y] 工程师日	支付流程集成测试上线；总体覆盖率 ≥60%
[Q4 Year]	代码质量 + 流程	TD-005、TD-008、TD-010	[X] 点 / [Y] 工程师日	重构巨型函数；完成运行手册；清除所有硬编码配置

冲刺产能分配模型

Sprint capacity: [X] story points

Allocation:
  ├── Feature work:        [X * 0.75 = ~Y] points  (75%)
  ├── Debt resolution:     [X * 0.15 = ~Y] points  (15%)
  └── Unplanned/bugs:      [X * 0.10 = ~Y] points  (10%)

Debt items that fit in one sprint ([≤Y] points each):
  ✓ TD-002 ([X] points)
  ✓ TD-012 ([X] points)
  ✓ TD-006 ([X] points)
  ✓ TD-008 ([X] points)

Multi-sprint debt items (break into phases):
  ~ TD-001: Phase 1 ([X] pts) → Phase 2 ([X] pts)
  ~ TD-009: Requires dedicated debt sprint or pairing

---

已接受／已延期的债务

当前修复成本超过业务价值，已明确接受并设定复审日期的事项。

ID	事项	延期原因	复审日期	负责人
TD-XXX	[事项]	[例如：“按当前规模重写需要 3 周，且不会为用户带来可见价值；流量达到 10 倍时重新评估”]	[日期]	[姓名]
TD-XXX	[事项]	[例如：“依赖项存在 CVE，但 Q3 之前没有升级路径；已通过 WAF 规则缓解”]	[日期]	[姓名]

**政策：**任何事项延期超过两次，必须上报工程经理。

---

深入资料

此技能附带支持文件——如有，请使用：

• references/debt-pricing.md — 债务定价：将“情况很糟”转化为可排序的数字。生成输出时请应用其中的方法；该文件包含校准方法和判断要点，而上文的方法摘要对它们作了简化。
• templates/debt-entry.md — 可填写的交付成果模板，内含质量门槛。若用户希望自行编写文档，而不是让系统生成，请提供该模板。

评分标准（0–40）

移交前为此技能生成的任何输出评分；达到 32 分及以上即可交付。

维度	0	5	10
业务影响转化	仅用工程术语描述事项	说明了影响，但未量化	每个事项都用非工程人员也能排序的业务术语（风险、速度损失、成本）定价
评分严谨性	凭感觉确定优先级	使用了公式，但安全／依赖项仍被低估	一贯应用公式，并明确纠正“技术上感觉很重要”的偏见
解决计划质量	优先级最高的事项只有模糊的意向	有计划，但无法转化为工单	前 5 项计划都是具体、可转化为工单的步骤，包含顺序安排和完成定义
产能规划的现实性	路线图忽略冲刺预算	说明了产能分配，但超出实际产能	季度产能分配符合实际产能，且已接受／已延期的事项均指定负责人和复审日期

质量检查

• 每项都指定了负责人 — 不存在无人负责的债务
• 优先级分数根据公式计算，而非随意指定
• 不要因为安全和依赖项看起来“偏技术”就低估其实际业务影响
• 前 5 项的解决计划包含具体且可创建工单的步骤 — 不能是“提高测试覆盖率”之类的模糊描述
• 季度路线图分配了合理的产能 — 债务处理所占产能不得超过实际迭代预算
• 已接受/延期的项目都有复审日期和指定负责人 — 不存在永久延期的项目
• 登记表区分了债务（有意采取或逐渐累积的捷径）与缺陷（非预期的问题）
• 只有满足验收标准后，项目才能标记为已解决 — 不能在 PR 合并时就关闭

反模式

• 不要随意给债务项目打分 — 优先级分数必须根据文档中说明的公式计算
• 不要混淆技术债务（有意采取的捷径）与缺陷（非预期的问题）— 两者需要不同的修复策略
• 不要因为安全和依赖项看起来抽象就低估其重要性 — 应根据实际业务影响打分
• 不要创建“永久延期”的项目 — 每个已接受的项目都必须有复审日期和指定负责人
• 不要在解决计划中使用模糊描述 — 每项计划都必须包含具体且可创建工单的步骤