技术债台账检查·责任人与严重度

技术债台账最常见的翻车不是「没登记」，而是「登记了却没法执行」：负责人空着、严重度空着、
描述写一句「优化一下、有点乱」就当交差；没有证据或复现说明，别人无法核实；有负责人却没有
计划修复时间；条目挂着「未关闭」却大半年没人更新；也不交代「不修会怎么恶化」（债务利息）。
本工具在评审、排期、向上汇报前，把每一条的写法与管理问题扫一遍，并给出可定位到条目的整改建议。

> 与「扫描代码算债」不同：本技能不读你的源码、不做代码度量，只对你已经维护的那张技术债台账（CSV）做写法与完整性体检。

执行原则

1. 只体检台账，不扫源码。 输入是你维护的技术债台账 CSV；不要在没有台账时去扫代码库临时生成债单。
2. 先补硬伤再看排序。 无负责人、无有效条目属高风险，先补再评；不要把严重度排序直接当成排期结论输出。
3. 有列才查。 W6 证据、W8 债务利息仅在台账含对应列时检查；不要在整表无该列时逐条误报。
4. 分档是启发式。 W4 按「影响×修复成本」推算且只报相差一档以上，阈值可按组织口径调整；不要把推算档位当成事实，也不要当成还债 ROI。
5. 空话识别靠词表。 W5 只命中固定短语（优化一下 / 有点乱 / 待重构 / 历史遗留）；不要把具体描述误判为空泛。

何时使用

CRITICAL: 只要用户提出检查 / 评审技术债台账（CSV），或问这张表能不能排期、每条债有没有人管，就必须使用本 skill，即使看起来可以用别的方式解决。

• 技术债台账（Excel/CSV）刚填完或每季度整理时，想确认「每条债有没有人负责、能不能落地」。
• 用户给出技术债台账，问「帮我看看这张表有什么问题」「哪些债该先还」。
• 迭代规划 / 技术债专项汇报前，检查严重度是否自洽、条目是否陈旧、高严重度是否扎堆、工时是否离谱。

何时不该使用

易混淆场景

怎么用

python3 scripts/debt_lint.py tech_debt.csv
python3 scripts/debt_lint.py tech_debt.csv --json
python3 scripts/debt_lint.py tech_debt.csv --as-of 2026-10-11 --stale-days 90   # 指定基准日与陈旧阈值
python3 scripts/debt_lint.py tech_debt.csv --max-high-ratio 0.5                # 高严重度占比阈值
python3 scripts/debt_lint.py --sample                                          # 内置虚构样例演示

• 退出码：0 = 未发现问题，1 = 发现问题（便于接入 CI / 代码评审流水线）。
• --as-of 用于判断「条目是否陈旧」，默认取运行当天；--stale-days 默认 90 天。
• --max-high-ratio 默认 0.4，用于表级的 W11。

输入格式

技术债台账 CSV（首行为表头，UTF-8，可含 BOM）。列名自动识别，大小写、空格差异兼容；列顺序不限。

取值约定：

• 严重度：填 高 / 中 / 低（也认 严重 / 一般 / 轻微、P0–P4、high/medium/low、1–5）。
• 影响：填 高 / 中 / 低 或 1–5（高=5、中=3、低=1），用于与工时推算档位。
• 修复成本/工时：数字加可选单位，如 8h / 2d / 1w / 40（1d=8h、1w=40h、1月=160h、1 故事点≈8h）。
• 状态：含 已完成 / 已关闭 / 已修复 / 已上线 等视为已关闭；含 未… / 待… / 进行中 / 处理中 视为未关闭。
• 缺失占位（无 / 暂无 / 待定 / N/A / - 等）视同留空。
• 「无证据/链接」W6 与「无债务利息」W8 仅在台账含对应列时才检查，避免整表无该列时逐条误报。

检查项与规则码

> 档位推算口径（影响×修复成本）：≥12 判高、6–11 判中、≤5 判低；工时先折算为小时再分档（≤4h→1、≤8h→2、≤40h→3、≤160h→4、更大→5）。
> W4 仅在相差「一档以上」（如 高 ↔ 低）时报告，相邻档位差视为口径误差不报。
> W11 仅在已填严重度的条目 ≥ 5 条时评估，占比以已填严重度的条目为分母。

输出示例（节选）

文件：tech_debt.csv（基准日：2026-10-11，陈旧阈值：90 天）

=== 技术债台账体检报告 ===

债务条目：10
高严重度占比：56%（已填严重度 9 条）
问题合计 19 项：高 2 · 中 13 · 低 4
结论：存在硬伤（条目无负责人 / 无有效条目），先补再评

—— 高风险 ——
[W1] D1「优化一下支付模块」无负责人（D1，第 2 行）
    · 说明：负责人列为空，这条债没有人认领，大概率会一直挂着
    · 建议：指定明确的责任人（到岗到人，不要写「相关同学」「后端组」）
—— 中风险 ——
[W4] D2「订单查询接口响应慢单页12s」严重度与影响×修复成本推算不符（D2，第 3 行）
    · 说明：填报为「低」，但按影响×修复成本推算应为「高」，相差一档以上
    · 建议：复核影响/工时打分或严重度判定口径，二者对齐
[W9] D6「缺少单元测试覆盖核心结算逻辑，需要补充」与 D3 重复（D6，第 7 行）
    · 说明：条目相同或高度相似，重复登记会虚增债务数量与工作量
    · 建议：合并为一条，或改写为不同债务并说明差异
[W11] 高严重度条目占比偏高（5/9 = 56%）（整表）
    · 建议：复核严重度口径；若确实如此，应制定专项清偿计划而不是继续并行堆新债
—— 低风险 ——
[W3] D1「优化一下支付模块」无债务类型（D1，第 2 行）
[W8] D5「历史遗留代码，有点乱」未说明「不修会如何恶化」（D5，第 6 行）

设计边界

• 纯标准库 Python（3.12+），只读，无网络请求，无 subprocess / eval / exec / os.system；输入按 UTF-8（含 BOM）读取。
• 只做台账写法与管理完整性检查（责任人、严重度、类型、自洽性、描述具体度、证据、时效、利息、重复、排期、占比、工时），不做源码扫描、代码度量、债务量化建模或还债 ROI 精算。
• W5 空话识别为词表匹配：命中「优化一下 / 有点乱 / 待重构 / 历史遗留」等固定短语才报，属提示而非定论；像「重构订单模块以降低耦合」这类具体描述不会误报。
• W4 基于「影响×修复成本」的启发式分档，阈值（12 / 6）与工时折算口径可按组织习惯调整；仅报相差一档以上的明显不符。
• W4 的「影响×修复成本」是任务给定的口径：影响越大、成本越高，推算档位越高；若你的团队按「影响高 / 成本低 = 优先」排序，请自行调整口径，不要照搬。
• W7 优先用「更新时间」，缺失时回退「发现日期」判断陈旧；两者都没有则跳过该项。
• W9 重复判断基于文本归一化与关键词相似度，近似描述会归为「高度相似」，需人工确认。
• W12 只判「非数字或极端值」，留空不报（缺工时属于 W2 可推算性范畴）。
• 样例为构造的演示数据，人名、模块与工单号均为虚构。
• 本包为开源改编作品，来源与改动见 来源与许可.md，遵守 MIT 许可证（LICENSE.md）。

交付物模板

可交付的 Markdown 模板见 assets/技术债评审交付模板.md（复制后填充，不适用项写「不适用」，不要留空）。

免责声明

本技能输出的是对技术债台账写法与管理完整性的检查参考，不是还债决策结论：不扫源码、
不做代码度量与债务量化建模，也不测算还债 ROI；严重度档位与工时口径可按组织习惯调整。评估结论是基于给定输入的推断，需结合实际上下文判断——同一条债在不同团队、不同迭代阶段的处理优先级可能完全不同。

依赖

仅需 Python 3.12+，使用标准库，无需联网、无需安装第三方包。