Community编程与开发github.com

技术债务发现

分析代码库中的技术债务(死代码、重复代码、架构问题、延期工作、框架反模式、低质量测试),按严重程度排序,并在用户确认后将其提交为 GitHub Issue。

技术债务发现 是什么?

该技能用于对代码库进行全面的技术债务审计。它能够系统地扫描代码,识别六大类问题:死代码、代码重复、架构问题、延期工作、框架反模式以及测试质量。对于每一项发现,技能会提供严重等级(P0-P4)、具体位置、证据和修复建议。分析过程是只读的,不会修改任何代码。技能支持多种执行模式,包括全量扫描、限定路径、按类别筛选以及试运行(dry-run),方便用户根据需求控制分析范围和深度。分析完成后,技能会生成结构化的 JSON 汇总,并检查现有 Issue 以避免重复。最终,它会向用户展示一份包含所有待创建 Issue 的清晰列表,等待用户确认后才通过 GitHub CLI 创建。这确保了审计结果的透明度和开发团队的实际掌控权,特别适合需要系统管理和追踪技术债项的团队。该技能适用于任何基于 Git 的代码仓库,并会自动检测项目的语言和技术栈以调整分析规则。

兼容平台✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/JAdshead/toolkit/tree/HEAD/skills/tech-debt

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

技术债务发现 是做什么的?

分析代码库中的技术债务,并将发现结果转化为可操作的 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:确定范围

  1. 如果给出了路径,则使用它们。
  2. 如果指定了 --full,则使用上述排除项扫描仓库。
  3. 否则,自动检测存在的主源代码和测试目录(常见的: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.rbRuby on Rails
manage.py 或 django 在 requirements / pyproject.toml 中Django
pyproject.toml / requirements.txt 包含 fastapi 或 flaskPython Web
package.json 包含 next、react、vue、svelte、express、nestjsJS/TS 框架
go.modGo
Cargo.tomlRust
pom.xml / build.gradle*JVM(如果存在 Spring)
composer.json 包含 laravel/frameworkLaravel
*.csproj.NET

同时检测测试框架(RSpec、Minitest、pytest、unittest、Jest、Vitest、Mocha、Go 的 testing、JUnit、PHPUnit 等)和测试目录。

在做出任何判断之前,阅读项目自身的约定:README、CONTRIBUTING、代理指令文件(AGENTS.md、CLAUDE.md、GEMINI.md)、linter 配置和任何架构文档。项目有意识选择的模式不是债务。

报告:检测到的技术栈:[语言/框架/测试运行器]。分析规则已相应调整。

步骤 4:运行类别分析

对每个启用的类别(默认全部六个):

  1. 宣告 正在分析 [类别]...(第 X 个,共 N 个)。
  2. 应用 references/categories.md 中该类别的检查清单,并根据检测到的技术栈进行调整。
  3. 以下面的 JSON 格式收集发现。
  4. 报告 [类别] 完成: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测试质量
引用工单的 TODOP4延期工作

复杂度指南

  • 简单:少于 10 行,一个文件,明显的修复(移除未使用的导入)。
  • 中等:10 到 50 行,2 或 3 个文件,直接的重构(提取函数)。
  • 复杂:超过 50 行,需要架构决策,或横跨整个代码库(拆分上帝类)。在修复建议中注明可能需要先设计方案或提案。

步骤 5:收集并去重

  1. 按类别 + 文件 + 行(10 行内)对发现进行分组。在每个组中,保留证据最详细、严重程度最高的发现。
  2. 跨类别:如果死代码和架构标记了同一个类,保留架构发现。如果多个类别标记了同一行,合并它们并保留最高严重程度。
  3. 按 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 编号替换为 [将创建]。

原则

  1. 只读。 分析期间不进行代码更改。
  2. 保守。 不确定时,跳过而不是报告误报。嘈杂的报告会被忽略。
  3. 尊重项目。 框架约定(回调、装饰器、依赖注入、基于约定的路由)和仓库中记录的决策不是债务。
  4. 证据优先。 每个发现都引用文件、行和证明它的代码。
  5. 结构化输出。 类别分析返回 JSON,以便合并和去重是可靠的。
  6. 用户确认后才创建。 列表始终先显示。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能