技術債發現
分析程式碼庫中的技術債,並將結果轉化為可操作的 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:確定範圍
- 如果提供了路徑,則使用它們。
- 如果提供了
--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)。
- 超過 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.rb | Ruby on Rails |
manage.py 或在 requirements / pyproject.toml 中包含 django | 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 則為 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": "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 | 測試品質 |
| 參考了工單的 TODO | P4 | 延後工作 |
複雜度指南
- simple:少於 10 行,一個檔案,修正方式顯而易見(移除未使用的匯入)。
- moderate:10 到 50 行,2 或 3 個檔案,直接了當的重構(提取函式)。
- complex:超過 50 行,需要架構性決策,或橫跨整個程式碼庫(拆分上帝類別)。請在修正建議中備註,其實作前可能需要先提出設計或提案。
步驟 5:收集與去重
- 按「類別 + 檔案 + 行號(10 行內)」對發現結果進行分組。在每個群組中,保留證據最詳細且嚴重程度最高的發現結果。
- 跨類別:如果「死碼」和「架構」標記了同一個類別,保留「架構」的發現結果。如果多個類別標記了同一行,合併並保留最高的嚴重程度。
- 先排序 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 編號替換為 [將建立]。
原則
- 唯讀。 分析期間不進行任何程式碼修改。
- 保守。 在不確定的情況下,跳過而非回報誤報。嘈雜的報告會被忽略。
- 尊重專案。 儲存庫中的框架慣例(回呼、裝飾器、依賴注入、基於慣例的路由)以及文件中記錄的選擇,不屬於技術債。
- 證據優先。 每個發現結果都引用檔案、行號以及證明它的程式碼。
- 結構化輸出。 類別分析回傳 JSON,以便可靠地進行合併和去重。
- 使用者確認後才建立。 始終先顯示清單。