Community程式設計與開發github.com

技術債分析

分析程式碼庫的技術債(死碼、重複、架構異味、延後工作、框架反模式、低價值測試),按嚴重程度排序,並在使用者確認清單後建立 GitHub Issue。

技術債分析 是什麼?

此技能可對程式碼庫進行全面的技術債審計,涵蓋六類分析:死碼、重複、架構、延後工作、模式違規與測試品質。它支援限定路徑、完整掃描、選擇特定類別以及乾執行(不建立 Issue)。分析過程是唯讀的,不會修改任何程式碼。技能會自動偵測專案的程式語言、框架與測試框架,並參考專案的自訂慣例以減少誤報。分析完成後,它會將發現結果以結構化 JSON 呈現,進行去重與合併,並與現有 GitHub Issue 比對。最終會向使用者顯示待建立 Issue 的清單,等待使用者確認後才透過 GitHub CLI 建立。此技能適用於 Claude Code、Cursor、Codex 等支援代理工具的 AI 平台,特別適合需要大規模重構或程式碼品質改善的開發團隊。

相容平台✓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。此分析為唯讀操作:執行此技能時絕不修改程式碼。

選項

從使用者的請求或命令參數中解析以下選項:

  • Scope paths:要分析的目錄或檔案(例如 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)。

  • 超過 1000 個檔案:警告執行時間會很長,並建議使用 --categories。
  • 超過 5000 個檔案:強烈建議一次只執行一個類別,並提供每個類別的大致時間。

步驟 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 或在 requirements / pyproject.toml 中包含 djangoDjango
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 則為 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": "Dead Code",
  "findings": [
    {
      "type": "Unused Import",
      "severity": "P3",
      "location": "src/utils/format.ts:5",
      "line_number": 5,
      "description": "Import 'date-fns' is never used in this file",
      "evidence": "import { format } from 'date-fns'",
      "remediation": "Remove the unused import",
      "complexity": "simple"
    }
  ]
}

對於重複類別,將每個位置放在 location 中,並以 , 分隔。對於架構類別的發現,將指標放入 description(例如「567 行,23 個公開方法」)。

嚴重程度參考

模式嚴重程度類別
隱藏安全問題的測試P0測試品質
資源存取缺少授權檢查P1模式違規
上帝類別(>500 行或 >20 個公開方法)P1架構
循環依賴P1架構
無法到達的程式碼P1死碼
僅模擬的測試(測試模擬了正在測試的內容)P1測試品質
Stub 被測試主體,然後對其進行斷言P1測試品質
同義反覆的測試P1測試品質
空的測試主體P1測試品質
過度模擬(>50% 的測試是設定程式碼)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延後工作

複雜度指南

  • simple:少於 10 行,一個檔案,修正方式顯而易見(移除未使用的匯入)。
  • moderate:10 到 50 行,2 或 3 個檔案,直接了當的重構(提取函式)。
  • complex:超過 50 行,需要架構性決策,或橫跨整個程式碼庫(拆分上帝類別)。請在修正建議中備註,其實作前可能需要先提出設計或提案。

步驟 5:收集與去重

  1. 按「類別 + 檔案 + 行號(10 行內)」對發現結果進行分組。在每個群組中,保留證據最詳細且嚴重程度最高的發現結果。
  2. 跨類別:如果「死碼」和「架構」標記了同一個類別,保留「架構」的發現結果。如果多個類別標記了同一行,合併並保留最高的嚴重程度。
  3. 先排序 P0,接著是 P1 到 P4。

步驟 6:檢查現有 Issue

僅在設定 --force 時跳過此步驟。對於每個發現結果,尋找滿足以下條件的開放 Issue:

  • 在其標題或內文中提到了相同的檔案路徑,且
  • 涵蓋相同類型的問題,或此發現結果行號前後 20 行內的行號。

優先尋找標題為 [TechDebt] 或帶有技術債標籤的 Issue,但任何明顯追蹤相同問題的開放 Issue 都可以配對。配對成功時,將該發現結果標記為「已追蹤為 #N」,並且不為其建立 Issue。同一個檔案中的不同問題類型視為不同的發現結果。

步驟 7:確認,然後建立 Issue

如果使用 --dry-run 或 gh_available=false,則跳過建立步驟,直接進入報告。

上限: 除非使用 --all,否則最多建立 20 個 Issue。依序填入名額:所有 P0 和 P1,然後是 P2(優先考慮分散在不同檔案,而非在一個檔案中建立多個 Issue),然後是 P3,最後是 P4。使用 --all 且超過 50 個 Issue 時,警告這將需要一段時間。

標籤: 僅使用 gh label list 中已存在的標籤。選擇最接近技術債的標籤(例如 tech-debt、technical-debt、debt、refactor、chore),並且如果儲存庫有,可以選擇與嚴重程度匹配的優先順序標籤以及類型標籤(例如 testing)。未經詢問,切勿建立標籤。如果沒有合適的標籤,請說明,並選擇不帶標籤建立 Issue,或詢問使用者是否要建立 tech-debt 標籤。

確認(必要): 在建立任何 Issue 之前,顯示完整清單並等待使用者回覆。絕不可在沒有確認的情況下建立 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。每個 Issue 內文必須能獨立閱讀,讓未觀看此報告的人也能理解:

gh issue create \
  --title "[TechDebt] <類別>: <簡短說明>" \
  --label "<現有標籤>" \
  --body "$(cat <<'EOF'
**分類:** <類別>
**嚴重程度:** P<N>
**位置:** <檔案:行號>

## 問題
<說明>

## 證據
```
<證據>
```

## 建議修正
<修正建議>

**複雜度:** <simple|moderate|complex>

## 驗收條件
- <可觀察的檢查,確認技術債已解決>
- 專案的完整測試套件通過
EOF
)"

標題範例:

  • [TechDebt] 死碼:移除 format.ts:5-12 中未使用的匯入
  • [TechDebt] 架構:拆分 OrdersController(567 行,23 個動作)
  • [TechDebt] 測試品質:修復 payment_service_test.go:45 中的僅模擬測試

如果 gh issue create 呼叫失敗,記錄錯誤和命令,繼續處理其餘 Issue,並在最後回報「已建立 X 個 Issue,Y 個失敗」。

如果儲存庫在 GitHub Project 板上追蹤工作(其代理程式指令的「Issue 追蹤」段落顯示「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/** : 排除 fixture
- 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.

相關技能