tech-debt-audit

技术债务审计

一项 Claude Code 技能，可对整个代码库进行审慎且有明确立场的审计，并生成包含引用依据的 TECH_DEBT_AUDIT.md。

通过 /tech-debt-audit 调用时，请遵循以下流程。到 --- 分隔线为止的所有内容都是 Claude 执行的流程。分隔线之后的部分是供安装或维护此技能的人员阅读的文档。

---

操作原则

找出真正的问题。不要圆滑，不要只看表面。不要脱离这个仓库，照搬通用最佳实践。不要奉承。不要用“总体而言，代码库结构良好”之类的废话充数。

每项具体发现都要引用 file:line。像“代码总体上……”这样的模糊说法不算。先读代码再评判——孤立来看似乎有问题的模式，可能是系统正常运转的关键。

阶段 1：了解全貌

不要跳过这一步。未了解系统就先入为主，会导致糟糕的审计。

1. 阅读 README、包清单（package.json / pyproject.toml / Cargo.toml / go.mod），以及 /docs 或 /adr 中的架构文档。
2. 梳理目录结构，并识别主要模块和分层。
3. 运行 git log --oneline -200 和 git log --stat --since="6 months ago"，了解实际变更内容及变更集中的位置。
4. 识别入口点、热点路径和少受关注的部分。
5. 列出行数最多的 20 个文件，以及过去 6 个月内修改最频繁的 20 个文件。两者的交集通常是债务藏身之处。
6. 使用 TodoWrite 发布计划，让用户能看到各阶段的进度。

继续之前，先写出 1–2 段关于架构的整体认知。如果你的认知与 README 矛盾，请指出——这本身就是一项发现。

阶段 2：从以下维度进行审计

使用 rg、ast-grep 和语言原生工具寻找具体示例。每项发现都要引用 path/to/file.ext:LINE。

1. 架构退化——循环依赖、分层违规、巨型文件（>500 LOC）和巨型函数、在 3 个以上位置重复出现且本应抽象的逻辑、已经存在但无人使用的抽象、死代码（未使用的导出、不可达分支、过时的注释代码块）。

2. 一致性腐化——同一件事有多种处理方式（HTTP 客户端、错误处理、日志记录、配置加载、验证、日期处理）。命名漂移。与代码实际职责不再相符的文件夹结构。

3. 类型与契约债务——any / unknown / as any / # type: ignore / 宽松的字典。未类型化的 API 边界。信任边界缺少架构验证。

4. 测试债务——如有覆盖率工具则运行；找出关键路径上的测试缺口。断言实现而非行为的测试。跳过的或不稳定的测试。高频变更但没有测试的文件。

5. 依赖与配置债务——针对 CVE 运行 npm audit / pip-audit / cargo audit。未使用的依赖。功能重复的依赖。环境变量泛滥（代码中有引用但文档未说明；不同环境的默认值不一致）。

6. 性能与资源管理——N+1 查询、异步路径中的同步工作、热点路径上的阻塞 I/O、未清理的监听器或句柄、不必要的序列化。

7. 错误处理与可观测性——被吞掉的异常、笼统的捕获、只记录但不处理的错误、模块间不一致的错误结构、关键路径缺少结构化日志。

8. 安全卫生——硬编码的密钥、字符串拼接 SQL、信任边界缺少输入验证、过于宽松的身份验证或 CORS、薄弱的加密。

9. 文档漂移——README 中与实际情况不符的说法、与相邻代码矛盾的注释、缺少文档字符串的公共 API。

第 3 阶段：交付物

在仓库根目录的 TECH_DEBT_AUDIT.md 中按以下结构撰写：

• 执行摘要 — 最多 10 条，按影响排序。
• 架构心智模型 — 说明你对系统实际情况的理解。
• 发现项表格 — 列：ID | Category | File:Line | Severity (Critical/High/Medium/Low) | Effort (S/M/L) | Description | Recommendation。目标为 30–80 项；超过这个数量的凑数内容只会造成干扰。
• 前 5 项“如果其他问题都不修，至少修好这些” — 提供具体的差异草案或重构大纲，不要给出含糊的建议。
• 快速修复 — 以清单形式列出低工作量 × 中等及以上严重程度的问题。
• 看起来糟糕但实际没问题的事项 — 列出你考虑过要标记、但最终没有标记的问题，并说明原因。此部分为必需项。 如果为空，说明你检查得还不够深入。
• 向维护者提出的开放问题 — 列出你无法判断属于技术债还是有意设计的问题。

规则

• 每个具体发现项都要注明 file:line。
• 如果不确定某事属于技术债还是有意设计，请在开放问题部分提出，不要直接断言。
• 不要建议重写。请建议具体且范围明确的改动。
• 不要凑数。如果某个类别没有实质性问题，请写“无实质性问题”并继续。
• 不要阿谀奉承。直接指出问题所在。

特定技术栈的工具

根据清单文件识别技术栈，并运行相关工具。尽可能并行运行。

• TypeScript / JavaScript — npm audit、npx knip（未使用的导出）、npx madge --circular（循环依赖）、npx depcheck（未使用的依赖）、tsc --noEmit（类型漂移）。
• Python — pip-audit、ruff check、vulture（死代码）、pydeps --show-cycles、mypy --strict（类型漂移）。
• Rust — cargo audit、cargo udeps、cargo machete、cargo clippy -- -W clippy::pedantic。
• Go — govulncheck、go vet、staticcheck、golangci-lint run。

如果工具未安装，请在审计中注明并继续，不要因此停下。未经许可，不要全局安装开发工具。

大型仓库：派生子 Agent

如果仓库超过 50k LOC，或顶层模块超过 5 个，请并行派生子 Agent（Task 工具）——每个模块一个——并综合其报告。在大型仓库中串行阅读会在写出发现项前耗尽上下文窗口。

每个子 Agent 都要分配：范围（一个模块）、上文列出的检查维度、引用要求，以及 200 项发现的上限。主 Agent 负责合并、去重和排序。

重复运行模式

如果仓库中已存在 TECH_DEBT_AUDIT.md，请先阅读。将已解决的问题标记为 RESOLVED，更新过时的问题，并将新问题标记为 NEW。这样审计就会成为一份可持续更新的文档，便于长期跟踪。

---

项目文档

以下内容面向安装、使用或为此技能做出贡献的人员，不属于审计流程。

安装

个人安装（适用于你的所有项目）：

mkdir -p ~/.claude/skills/tech-debt-audit

curl -o ~/.claude/skills/tech-debt-audit/SKILL.md https://raw.githubusercontent.com/ksimback/tech-debt-skill/main/SKILL.md

或者仅为某个项目安装（仅适用于此仓库）：

mkdir -p .claude/skills/tech-debt-audit && cp /path/to/SKILL.md .claude/skills/tech-debt-audit/SKILL.md

验证是否已加载：

echo "/skills" | claude

使用方法

在 Claude Code 中，进入你要审计的仓库：

/tech-debt-audit

就这样。输出会写入仓库根目录的 TECH_DEBT_AUDIT.md。首次运行需要 5–20 分钟，具体取决于仓库大小；后续以重复运行模式执行时会更快。

理念

大多数“代码审查”提示词都会给出一串泛泛的最佳实践违规项，并将其包装成问题发现。本技能旨在避免这种失误模式。三个设计选择发挥了主要作用：

先建立认知，再做判断。 阶段 1 不是可有可无的装饰。没有真正理解架构，每个阶段 2 的问题发现都只是在套用通用启发式规则。阅读 git log 了解代码变更情况，才能找出那些确实存在技术债的文件，而不只是看起来杂乱的文件。

每个问题发现都要标注文件和行号。 这是影响质量的最大因素。没有引用的问题发现只是凭感觉。凭感觉的问题不会得到修复。

必须包含“看起来糟糕但实际上没问题”的部分。 大多数人在改编提示词时，最常删掉的就是这一部分。别删。要求模型列出它考虑过但最终决定不提出的问题，才能将真正的审计与照本宣科的清单区分开来。如果这一部分为空，审计就不够深入。

本技能还明确禁止建议重写，也禁止为了凑数而填充类别。这两者都是 LLM 常见的失误模式——重写比诊断容易，而凑数会让输出显得全面，实际却并非如此。

你将获得什么

TECH_DEBT_AUDIT.md 的结构如下：

# Tech Debt Audit — <repo name>
Generated: 2026-04-25

## Executive summary
- 3 Critical findings, 12 High, 31 Medium, 18 Low
- Largest debt concentration: src/payments/* (god module, 4 of 3 Critical findings)
- ...

## Architectural mental model
The system is a [...]

## Findings
| ID | Category | File:Line | Severity | Effort | Description | Recommendation |
|----|----------|-----------|----------|--------|-------------|----------------|
| F001 | Architectural decay | src/payments/processor.ts:1240 | Critical | L | 1,400-line god class handling routing, validation, retry, and reconciliation | Extract retry and reconciliation into separate services |
| ... |

## Top 5
1. **F001 — Decompose payments/processor.ts** ...

## Quick wins
- [ ] F042: Remove unused dep `lodash.merge` (replaced by native ...)
- [ ] ...

## Things that look bad but are actually fine
- The deeply nested callback pattern in `src/legacy/webhooks.ts` looks like a refactor target, but it preserves ordering guarantees that the queue-based replacement would break. Leave it.
- ...

## Open questions
- Is `src/experiments/` intentionally untested, or did it fall through?
- ...

适配说明

项目级覆盖。 特定仓库中的 .claude/skills/tech-debt-audit/SKILL.md 会覆盖全局版本。适用于需要自定义维度的项目——例如，Agent 代码库可以增加“提示词注入攻击面”或“每轮工具调用成本”等审计类别。

审计过程中的调整。 阶段 1 完成后，你可以打断并提出：“进入阶段 2 之前，请告诉我阶段 1 中有哪些意外发现，以及你想调查哪些不在维度列表中的内容。” 最好的发现往往来自提示词未曾预料的情况。每个新代码库首次运行时都值得这样做。

调整严重性评估标准。 如果模型标记的问题过多或过少，可以编辑阶段 2 的维度列表，加入明确的阈值。例如，如果你的代码库通常规模更大，可以将“超大文件（>500 LOC）”改为“>800 LOC”。

添加类别。 阶段 2 中的 9 个维度只是起点。可根据技术栈添加特定领域的类别——前端项目可添加无障碍性，基础设施项目可添加 IaC 漂移，ML 项目可添加模型评估，LLM 应用可添加提示词版本管理。

拆分为辅助文件。 随着此 SKILL.md 增长，你可以将部分内容提取到同级文件（severity-rubric.md、stack-tooling.md）中，并在协议中引用。Claude Code 只会在需要时延迟加载这些文件。

局限性

这是静态审计，不是安全审计。它能发现明显的安全卫生问题（硬编码密钥、SQL 注入模式），但无法取代真正的渗透测试或威胁建模。

它无法发现业务逻辑错误。发现这类问题需要模型不具备的领域知识。

它无法区分有意为之的简单与意外造成的简单。“待确认问题”部分正是为此而设——拿不准时，本技能会先提问，而不是妄下结论。

对于非常大的仓库（>200k LOC），即使分派子 Agent 也可能得出浅显的结果。可考虑将范围限定到某个模块：/tech-debt-audit src/payments。

贡献

欢迎提交 PR。提交前请：

1. 在至少两个技术栈不同的真实代码库上进行测试。
2. 如果要添加维度，请说明现有 9 个维度为何未涵盖它。
3. 如果要收紧规则，请提供审计摘录的前后对比，以展示改进效果。

唯一的设计约束是：本技能必须产出工程师会采取行动的问题发现。任何让结果变成“看起来面面俱到，实际却毫无改变”的做法，都是一种退步。

许可证

MIT。使用、分叉、发布皆可。欢迎注明出处，但并非必须。

致谢

本技能基于 Claude Code Agent Skills 标准构建。其灵感源自使用 Claude Code 处理随着时间推移变得十分混乱的代码库的经历。