技术债务发现 是做什么的?
分析代码库中的技术债务,并将发现结果转化为可操作的 GitHub Issue。分析过程仅为只读:运行此技能时绝不修改代码。
选项
根据用户的请求或命令参数解析:
- 范围路径:要分析的目录或文件(例如
src/services lib/)。 - --full:扫描整个仓库,排除依赖项、构建和版本控制目录(
node_modules、vendor、.git、dist、build、target、tmp、log、虚拟环境、生成的代码)。 - --dry-run:报告发现但不创建 Issue。
- --all:解除 20 个 Issue 的上限。
- --force:即使存在类似的开放 Issue 也创建 Issue。
- --yes:跳过确认提示(仅在用户明确传递时)。
- --categories=X,Y:仅运行这些类别:
dead-code、duplication、architecture、deferred-work、patterns、tests。
执行模型
每个类别独立分析。如果你的代理可以生成并行子代理,请为每个类别分配一个子代理,并包含范围、检测到的技术栈以及 references/categories.md 中该类别的检查清单,让每个子代理返回下面的 JSON 格式。否则,依次顺序运行类别,一次一个,以保持在上下文限制内。
完整的六个类别顺序运行在中等规模的代码库上大约需要 15 到 30 分钟。为获得更快的结果,建议使用 --categories 或更窄的范围。
步骤 1:确定范围
- 如果给出了路径,则使用它们。
- 如果指定了
--full,则使用上述排除项扫描仓库。 - 否则,自动检测存在的主源代码和测试目录(常见的:
src/、app/、lib/、pkg/、internal/、cmd/、test/、tests/、spec/)。显示:自动检测到的范围:[目录]。大约 X 个文件。是否继续?(使用 --full 进行完整扫描)
使用仓库实际使用的扩展名统计范围内的源文件数(例如 git ls-files -- <scope> | grep -E '\.(rb|py|ts|tsx|js|go|java|kt|rs|php|cs)$' | wc -l)。
- 超过 1,000 个文件:警告运行时间会很长,并建议使用
--categories。 - 超过 5,000 个文件:强烈建议一次只运行一个类别,并给出每个类别的大致时间。
步骤 2:预分析检查
除非指定了 --dry-run,否则检查 GitHub CLI:
gh auth status
如果失败,设置 gh_available=false 并提示:“找不到 gh CLI 或未通过身份验证。发现结果将报告但不创建 Issue。运行 gh auth login 以启用 Issue 创建。”
如果可用,获取稍后需要的数据:
gh issue list --state open --limit 200 --json number,title,body,labels
gh label list --limit 200 --json name,description
保留 Issue 列表用于重复检测,保留标签列表用于添加标签。
步骤 3:检测技术栈
从仓库中检测语言、框架和测试运行器,而不是假设一个。典型指标:
| 指标 | 技术栈 |
|---|---|
Gemfile 包含 rails,或 config/application.rb | Ruby on Rails |
manage.py 或 django 在 requirements / pyproject.toml 中 | Django |
pyproject.toml / requirements.txt 包含 fastapi 或 flask | Python Web |
package.json 包含 next、react、vue、svelte、express、nestjs | JS/TS 框架 |
go.mod | Go |
Cargo.toml | Rust |
pom.xml / build.gradle* | JVM(如果存在 Spring) |
composer.json 包含 laravel/framework | Laravel |
*.csproj | .NET |
同时检测测试框架(RSpec、Minitest、pytest、unittest、Jest、Vitest、Mocha、Go 的 testing、JUnit、PHPUnit 等)和测试目录。
在做出任何判断之前,阅读项目自身的约定:README、CONTRIBUTING、代理指令文件(AGENTS.md、CLAUDE.md、GEMINI.md)、linter 配置和任何架构文档。项目有意识选择的模式不是债务。
报告:检测到的技术栈:[语言/框架/测试运行器]。分析规则已相应调整。
步骤 4:运行类别分析
对每个启用的类别(默认全部六个):
- 宣告
正在分析 [类别]...(第 X 个,共 N 个)。 - 应用
references/categories.md中该类别的检查清单,并根据检测到的技术栈进行调整。 - 以下面的 JSON 格式收集发现。
- 报告
[类别] 完成:X 项发现。
如果某个类别的运行时间远长于其他类别(大约 5 分钟的主动分析),则停止该类别,并在报告中标记为 未完成(截断),而不是阻塞整个运行。
发现格式
每个类别返回:
{
"category": "死代码",
"findings": [
{
"type": "未使用的导入",
"severity": "P3",
"location": "src/utils/format.ts:5",
"line_number": 5,
"description": "文件中的 'date-fns' 导入从未使用",
"evidence": "import { format } from 'date-fns'",
"remediation": "移除未使用的导入",
"complexity": "简单"
}
]
}
对于重复项,将所有位置放在 location 中,用 , 分隔。对于架构发现,将指标放在 description 中(例如“567 行,23 个公有方法”)。
严重程度参考
| 模式 | 严重程度 | 类别 |
|---|---|---|
| 隐藏安全问题的测试 | P0 | 测试质量 |
| 资源访问缺少授权检查 | P1 | 模式违规 |
| 上帝类(>500 行或 >20 个公有方法) | P1 | 架构 |
| 循环依赖 | P1 | 架构 |
| 不可达代码 | P1 | 死代码 |
| 仅模拟测试(测试模拟了正在测试的内容) | P1 | 测试质量 |
| 对测试对象进行 Stub 然后对其断言 | P1 | 测试质量 |
| 循环论证测试 | P1 | 测试质量 |
| 空测试体 | P1 | 测试质量 |
| 过度模拟(>50% 的测试时间是 setup) | P1 | 测试质量 |
| Stub 类的每个实例 | P1 | 测试质量 |
| 测试间共享可变状态 | P1 | 测试质量 |
| 长函数(>50 行) | P2 | 架构 |
| 高耦合(>10 个项目导入) | P2 | 架构 |
| 完全或接近重复 | P2 | 重复代码 |
| 弃用通知 | P2 | 延期工作 |
| 临时或变通标记 | P2 | 延期工作 |
| 框架反模式 | P2 | 模式违规 |
| 实现耦合的测试 | P2 | 测试质量 |
| 仅断言“不抛出异常”的测试 | P2 | 测试质量 |
| 未引用函数、死分支、孤立文件 | P2 | 死代码 |
| 深层嵌套(>4 层) | P3 | 架构 |
| 未使用的导入 | P3 | 死代码 |
| TODO / FIXME 注释 | P3 | 延期工作 |
| 注释掉的代码 | P3 | 延期工作 |
| 约定违规 | P3 | 模式违规 |
| 脆弱的测试断言 | P3 | 测试质量 |
| 引用工单的 TODO | P4 | 延期工作 |
复杂度指南
- 简单:少于 10 行,一个文件,明显的修复(移除未使用的导入)。
- 中等:10 到 50 行,2 或 3 个文件,直接的重构(提取函数)。
- 复杂:超过 50 行,需要架构决策,或横跨整个代码库(拆分上帝类)。在修复建议中注明可能需要先设计方案或提案。
步骤 5:收集并去重
- 按类别 + 文件 + 行(10 行内)对发现进行分组。在每个组中,保留证据最详细、严重程度最高的发现。
- 跨类别:如果死代码和架构标记了同一个类,保留架构发现。如果多个类别标记了同一行,合并它们并保留最高严重程度。
- 按 P0 优先排序,然后是 P1 到 P4。
步骤 6:检查现有 Issue
仅当设置了 --force 时跳过此步骤。对于每项发现,查找一个开放的 Issue:
- 在其标题或正文中提到了相同的文件路径,并且
- 涵盖了相同类型的问题,或与该发现行相距 20 行内的某行。
优先选择标题包含 [TechDebt] 或带有 tech-debt 标签的 Issue,但也匹配任何明确跟踪同一问题的开放 Issue。匹配时,将发现标记为 已在 #N 中跟踪,并且不创建该 Issue。同一文件中的不同问题类型是单独的发现。
步骤 7:确认,然后创建 Issue
如果指定了 --dry-run 或 gh_available=false,跳过创建;直接进入报告。
上限: 最多 20 个 Issue,除非指定了 --all。按顺序填充插槽:所有 P0 和 P1,然后是 P2(优先分散到不同文件,而不是一个文件多个 Issue),然后是 P3,然后是 P4。使用 --all 且超过 50 个 Issue 时,警告这将需要一些时间。
标签: 仅使用 gh label list 中已存在的标签。选择最匹配技术债务的标签(例如 tech-debt、technical-debt、debt、refactor、chore),并且如果仓库有,则使用与严重程度匹配的优先级标签和类型标签(例如 testing)。未经询问绝不创建标签。如果没有合适的标签,说明情况,然后不带标签创建或询问用户是否要创建 tech-debt。
确认(必需): 在创建任何内容之前,显示完整列表并等待用户的回答。绝不未经确认就创建 Issue,除非他们传递了 --yes。
将创建 X 个 Issue(标签:tech-debt, P2):
1. [P1] [TechDebt] 架构:拆分 OrderService(612 行,27 个公有方法)
2. [P1] [TechDebt] 测试质量:修复 payment_test.py:45 中的纯模拟测试
3. [P2] [TechDebt] 重复:提取地址验证(user.ts:40, account.ts:88)
...
已在跟踪(跳过):3。超过上限(未创建):12。
是否继续?您也可以按编号删除项目或更改标签。
应用用户做出的任何编辑,然后创建每个 Issue。每个正文必须独立成文,让未看过此报告的人也能读懂:
gh issue create \
--title "[TechDebt] <类别>: <简短描述>" \
--label "<现有标签>" \
--body "$(cat <<'EOF'
**类别:** <类别>
**严重程度:** P<N>
**位置:** <文件:行>
## 问题
<描述>
## 证据
```
<证据>
```
## 建议修复
<修复建议>
**复杂度:** <简单|中等|复杂>
## 验收标准
- <可观察的检查点,确认债务已解决>
- 项目的完整测试套件通过
EOF
)"
标题示例:
[TechDebt] 死代码:移除 format.ts:5-12 中的未使用导入[TechDebt] 架构:拆分 OrdersController(567 行,23 个操作)[TechDebt] 测试质量:修复 payment_service_test.go:45 中的纯模拟测试
如果 gh issue create 调用失败,记录错误和命令,继续处理其余部分,并在最后报告 创建 X 个 Issue,Y 个失败。
如果仓库在 GitHub Project 板上跟踪工作(其代理指令的 Issue tracking 部分显示 Mode: project,或者没有该部分且 gh repo view --json projectsV2 显示已链接的看板),则提议对新 Issue 运行 place-issues 技能。
步骤 8:摘要报告
=== 技术债务发现报告 ===
范围:[分析的路径]
分析的文件数:[数量]
技术栈:[语言/框架/测试运行器]
耗时:[所用时间]
## 摘要
- 发现总数:X | 创建的 Issue:Y | 已在跟踪:Z | 超过上限:W
- 按严重程度:P0: A, P1: B, P2: C, P3: D, P4: E
## 按类别发现的发现
### 死代码(X)
- [ ] #N: 移除 format.ts:5-12 中的未使用导入 (P3)
### 重复代码(X)
- [ ] #N: 提取地址验证(user.ts:40, account.ts:88)(P2)
### 架构(X)
- [ ] #N: 拆分 OrderService(612 行,27 个公有方法)(P1)
### 延期工作(X)
- [ ] #N: 解决 billing.py:123 中的 TODO (P3)
### 模式违规(X)
- [ ] #N: 修复 OrdersController#index 中的 N+1 查询风险 (P2)
### 测试质量(X)
- [ ] #N: 修复 payment_test.py:45 中的纯模拟测试 (P1)
## 已在跟踪
- billing.py:100 TODO → #N
## 额外发现(超过上限,未创建)
[列表]
运行时使用 --all 以创建剩余的 X 项发现。
## 已跳过(误报或有意为之)
- tests/fixtures/** : 已排除 fixtures
- conftest.py 中的 TODO(#42) : 有关联工单 (P4)
## 分析状态
- 死代码:完成
- ...
- 测试质量:未完成(截断)
## 错误
[任何失败的 gh 命令]
对于 --dry-run,将 Issue 编号替换为 [将创建]。
原则
- 只读。 分析期间不进行代码更改。
- 保守。 不确定时,跳过而不是报告误报。嘈杂的报告会被忽略。
- 尊重项目。 框架约定(回调、装饰器、依赖注入、基于约定的路由)和仓库中记录的决策不是债务。
- 证据优先。 每个发现都引用文件、行和证明它的代码。
- 结构化输出。 类别分析返回 JSON,以便合并和去重是可靠的。
- 用户确认后才创建。 列表始终先显示。