This article is not yet available in English. You are reading the Traditional Chinese original. The English edition will appear here once it is translated.
Browse articles that do have an English edition技術債追蹤與重構優先級排序：從主觀感受到數據驅動的決策
專案上線半年，新功能開發越來越慢，每次改動都要花半天除錯；新人接手舊模組，看不懂為什麼這裡要這樣寫，問了一圈沒人記得當初的設計決策。這類「技術債累積」是工程團隊最常見的隱形成本：慢、難以量化、而且決策取決於誰的聲音最大。這篇是操作配方：用 SonarQube、CodeClimate、LLM 節點與自訂儀表板串出一條技術債量化流水線，讓機器從程式碼提取指標、評估業務影響、計算重構 ROI，人只處理需要業務語境判斷的部分。全文最重要的一節是第五節——哪些環節可以從程式碼自動量化，哪些環節必須由人評估業務影響，這條邊界畫錯了，自動化會比人工更危險。
這個場景解決什麼
適合這個配方的流程有四種特徵：高頻率（每天都有新程式碼）、跨模組（技術債影響多個服務）、規則說得清楚（代碼異味、重複率、複雜度有明確指標）、繁瑣但必須做。四者俱備的人工評估，通常有三種損耗：主觀（不同人對技術債嚴重程度看法不同）、延遲（等到出事才想重構）、不完整（只看程式碼不看業務影響）。
做完這個配方之後的目標狀態：技術債被量化為可比較的數字，重構優先級基於業務影響與 ROI 自動排序，Tech Lead 能用數據說服產品經理撥出重構時間。人的角色從「憑感覺說這很爛」變成「根據數據決定先修哪個」。
同時畫清邊界：這篇處理的是技術債的量化與優先級排序，不是要你用 AI 取代架構決策；需要長期演進方向判斷與權衡取捨的環節（例如「這個模組是否值得重構還是直接重寫」）也不在自動化範圍內。判斷一個場景值不值得自動化，先讀什麼時候不該用 AI。
工具組合與前置準備
- SonarQube：開源代碼品質平台，支援 30+ 語言的靜態分析，涵蓋 bug、漏洞、代碼異味、重複率、圈複雜度等維度。可自架或採用雲端版 SonarCloud。自建與採購的系統性取捨見自建還是採購。
- CodeClimate：商業代碼品質平台，提供維護性指數（Maintainability Index）、技術債比率、測試覆蓋率等綜合指標。優點是指標全面、易於理解；缺點是需要訂閱。方案與定價以官網為準。
- LLM API（本文以 DeepSeek 為例，任何供應商皆可）：負責流程中「業務影響評估」與「自然語言生成」的判斷。單價以供應商官網為準；接通後第一件事是在供應商控制台設定花費上限與用量告警。
- 自訂儀表板（Grafana、Metabase 或簡易 HTML Dashboard）：將技術債指標可視化，支援按模組、時間、嚴重程度篩選。優點是客製化自由度高；缺點是需要額外開發。
前置檢查表——每一項都有明確答案才動工：
| 檢查項 | 要確認什麼 | 沒確認就做的後果 |
|---|---|---|
| 程式碼倉庫權限 | CI/CD 帳號是否有讀取所有相關倉庫的權限 | 部分模組無法分析，技術債評估不完整 |
| 歷史數據 | 是否有過去半年的 git log、issue tracker 數據 | 無法計算技術債增長趨勢 |
| 業務映射 | 是否能將程式碼模組映射到業務功能（如「訂單模組」、「用戶認證」） | 無法評估業務影響，優先級排序失去依據 |
| 維運責任 | 上線後誰看儀表板、誰調整評估模型 | 數據產出但無人使用，比沒有更糟 |
資料分級的判斷方法見企業資料安全基本盤。
憑證紀律（先講，因為最常被忽略）：所有 API Key、OAuth Token 放進 CI/CD 平台的 secrets 機制；不要寫死在 workflow 檔案、註解或說明文件裡；不要把含憑證的配置檔提交到公開倉庫。
一、盤點人工評估痛點
花兩週，把所有技術債評估中的常見問題列成一張表：
| 問題類型 | 發生頻率 | 平均發現時間 | 修復成本 | 現在誰發現 |
|---|---|---|---|---|
| 重複程式碼導致修改遺漏 | 每月 2-3 次 | 測試階段或上線後 | 高（需多處修改） | QA 工程師 |
| 高複雜度函式難以維護 | 每週 1-2 次 | 新人接手時 | 中（學習曲線陡峭） | 新入職工程師 |
| 缺少測試覆蓋的關鍵路徑 | 每月 1-2 次 | 生產環境報錯 | 極高（需緊急修復） | 值班工程師 |
| 過時依賴庫的安全漏洞 | 每季度 1-2 次 | 安全掃描或滲透測試 | 高（需升級並回歸測試） | 安全團隊 |
兩個填寫紀律：頻率與成本是從實際 issue tracker 與 git log 統計出來的，不靠印象——口頭回憶幾乎總是低估；修復成本要寫具體事件（哪次 hotfix、花了多少人天），寫不出成本的問題，說明它可能根本不值得優先自動化。
這張表有兩個用途：下一步的選型依據，以及上線後計算效益的基線。「自動化前平均每筆技術債評估多久、自動化後例外處理要多久」都從這張表與後面的執行紀錄算出來——自己測的數字，比任何文章裡的參考值可靠。
二、選一條最痛的模組
四個條件同時成立才動手：頻率高（經常變更）、規則寫得出來（有明確的代碼指標）、出錯有代價（影響業務穩定性）、工具鏈有介面。
兩類流程先避開：即將廢棄的 legacy 模組（不值得投入重構）；業務邏輯極度複雜且無文檔的模組（LLM 無法理解上下文，誤報率過高）。
第一版切小：只做「程式碼掃描 → 指標提取 → 業務影響評估 → ROI 計算 → 優先級排序 → 儀表板展示」這一條主幹。自動化重構建議、歷史趨勢預測全留到第二版。一條穩定跑通的主幹，勝過一張完整但沒上線的設計圖。
三、自架還是雲端
| 考量點 | 自架 | 官方雲端 |
|---|---|---|
| 資料位置 | 程式碼與分析結果在自己環境，適合分級要求高的專案 | 程式碼經供應商環境，須先過資料分級這一關 |
| 維護責任 | 升級、擴展、停機處置都是你的 | 供應商負責 |
| 起步速度 | 需要伺服器資源與基本 DevOps 能力 | 註冊即用，幾分鐘內完成整合 |
| 預算形態 | 伺服器費用加維運人力 | 訂閱制，金額以官網為準 |
決策方法：資料分級結果說「不能出網」時，自架 SonarQube 幾乎是唯一選項；否則先用 CodeClimate Cloud 把第一條流程跑通，累積了真實用量與失敗紀錄，再評估要不要遷移。不論哪種，都先用測試倉庫跑通示範流程，第一天不碰生產倉庫。
四、串出最小可跑版本
節點組裝順序：
- 觸發節點：定時觸發（每週一次）或
push事件觸發（監聽特定路徑）。優先定時觸發，避免每次 commit 都掃描造成資源浪費。 - 掃描節點：執行 SonarQube Scanner 或 CodeClimate CLI，輸出結構化的代碼指標 JSON（圈複雜度、重複率、代碼異味數、測試覆蓋率等）。
- 業務映射節點：將程式碼路徑映射到業務模組（如
src/orders/**→ 「訂單模組」），可透過配置檔或 LLM 自動推斷。 - LLM 評估節點：將代碼指標、近期 issue 數據、業務模組重要性送入 LLM，要求輸出業務影響評分與重構建議。
- ROI 計算節點：根據重構預估工時、預期減少的 bug 數、節省的開發時間，計算重構投資回報率。
- 優先級排序節點：綜合代碼指標評分、業務影響評分、ROI，計算綜合優先級分數，生成排序清單。
- 儀表板更新節點：將結果寫入資料庫或儀表板 API，更新可視化界面。
試跑期三條紀律：
- 用測試倉庫：建立
test-tech-debt倉庫，故意放入已知問題（高複雜度函式、重複程式碼、缺少測試），驗證工具能否正確檢測並評分。 - 留執行紀錄：除平台內建的執行歷史外，為重要流程加一個「台帳」分支——每次執行把時間、模組名稱、各項指標、優先級分數寫進一張專用表格或資料庫。這是第八節監控的原料。
- 影子模式上線：自動化先生成優先級清單但不強制執行，人照樣憑經驗決定重構順序，逐週比對兩邊結果。連續一致之後才讓自動化接管低風險模組的重構決策，人轉為審核高風險模組。
五、哪些環節交給自動量化、哪些必須用人評估
這是全文最重要的一節。原則一句話：確定性的代碼指標給自動化工具，LLM 只做「業務影響評估」這一類需要語境理解的事。
| 環節 | 用什麼 | 為什麼 |
|---|---|---|
| 圈複雜度、重複率、代碼異味數 | SonarQube / CodeClimate | 同樣輸入必須同樣輸出；這些是確定性指標，LLM 做不到這個保證 |
| 測試覆蓋率、未覆蓋路徑 | Jest / pytest / coverage.py | 基於執行軌跡的精確計算，準確率 100% |
| 模組業務重要性評分 | LLM 節點＋人工校準 | 需要理解業務價值、用戶量、營收貢獻，純程式碼分析無法得出 |
| 重構預估工時 | LLM 節點＋歷史數據 | 需要參考類似重構任務的實際耗時，LLM 能結合上下文給出合理估算 |
| 重構風險評估 | LLM 節點＋依賴圖分析 | 需要理解模組間耦合關係與潛在影響範圍 |
| 優先級排序的自然語言解釋 | LLM 節點 | 但排序背後的數字由確定性節點原樣注入，LLM 不得改寫任何指標 |
兩條鐵律：
- 代碼指標永遠不經過 LLM 的嘴。 圈複雜度、重複率、測試覆蓋率由自動化工具原樣計算；LLM 只產評估與建議，不產事實。自動化評估裡代價最高的事故，形態幾乎都是「模型改寫了一個指標，而且改得很像真的」。
- LLM 輸出永遠當作不可信輸入。 LLM 節點要求輸出固定結構的 JSON（欄位在提示詞裡逐一列舉）；下游第一個節點做格式校驗，校驗不過直接進例外分支，不允許「盡量解析」。
LLM 節點的提示詞寫法：給業務影響評估維度（用戶量、營收貢獻、戰略重要性）、給輸出 JSON 的欄位定義、給邊界規則（「只根據提供的指標與業務描述評估，不補充推測」），溫度調低以減少隨機性。提示詞不神奇，神奇的是它後面接了校驗節點。
以下是一個典型的 LLM 業務影響評估提示詞範例：
你是一位資深技術負責人，負責評估以下模組的技術債業務影響。
【模組資訊】
- 模組名稱：{{module_name}}
- 業務描述：{{business_description}}
- 日均活躍用戶：{{daily_active_users}}
- 月營收貢獻：{{monthly_revenue}}
【代碼指標】
- 圈複雜度平均值：{{avg_cyclomatic_complexity}}
- 重複率：{{duplication_rate}}%
- 代碼異味數：{{code_smell_count}}
- 測試覆蓋率：{{test_coverage}}%
- 近三月 bug 數：{{bug_count_last_3_months}}
【評估維度】
請從以下三個維度評估業務影響，每個維度給出 1-5 分（5 為最高影響）：
1. 用戶影響：技術債導致的問題會影響多少用戶
2. 營收影響：技術債導致的問題會損失多少營收
3. 開發效率：技術債會拖慢多少新功能開發速度
【輸出格式】
請嚴格按照以下 JSON 格式輸出，不要添加任何其他文字：
{
"business_impact": {
"user_impact": number,
"revenue_impact": number,
"efficiency_impact": number,
"overall_score": number
},
"refactoring_estimate": {
"estimated_hours": number,
"risk_level": "low" | "medium" | "high",
"expected_bug_reduction_percent": number,
"expected_efficiency_gain_percent": number
},
"roi_calculation": {
"cost_hours": number,
"benefit_hours_per_month": number,
"payback_months": number,
"recommendation": "immediate" | "next_quarter" | "backlog"
},
"justification": string
}
【邊界規則】
- 只根據提供的指標與業務描述評估，不補充推測
- 如果某些資訊缺失，在輸出中标記 "data_missing"
- 不要改寫任何代碼指標數值
六、錯誤處理、重試與冪等
先把失敗分成三類，因為三類的處置完全不同：
| 失敗類型 | 例子 | 處置 |
|---|---|---|
| 暫時性 | API 限流、網路逾時 | 節點自動重試（設次數與間隔）；重試耗盡仍失敗進例外分支 |
| 資料性 | 倉庫無法訪問、指標計算失敗、LLM 輸出格式錯誤 | 不重試（重試還是錯）；直接進例外分支，人修配置後重跑 |
| 設定性 | API Key 過期、SonarQube 服務停機、資料庫連接失敗 | 立即停止流程並告警，等人介入 |
冪等是重試的前提：流程要保證「同一個模組跑兩次不會重複寫入數據」。做法是在寫入前先查詢該模組該時間點的數據是否已存在——存在就跳過或更新，絕不無腦新增。沒有冪等設計就開重試，等於裝了一台數據製造機：重複的指標記錄，比人工記錄還難收拾。
七、失敗告警
- 告警發到「有人在值班」的渠道：即時通訊群組或 email，且群組裡有明確的值班表。告警沒人看，等於沒有告警。
- 告警內容模板：流程名稱、模組名稱、失敗節點、錯誤摘要、發生時間、重跑方式。讓收到的人在半分鐘內能決定「現在處理還是稍後處理」。
- 分級防洗版：單筆模組掃描例外進每週匯總；API Key 過期、服務停機這類「流程已停」的事件才即時推送。每筆例外都彈一次通知，值班的人很快會把渠道靜音——告警系統就死在靜音那一刻。
八、上線後的監控
- 前兩週是觀察期：每天看執行歷史與台帳，記錄執行總數、失敗次數、誤報率（人工標記為不合理的優先級比例）。兩週之後自己算誤報率與主因分佈——這是你的流程自己的數據，判斷門檻（誤報率高到多少要調整評估模型）由你的團隊容忍度決定，定了就寫進值班說明，不要引用任何文章裡的現成數字。
- 每週抽樣複核：固定抽 3-5 個已自動評估的模組，人工複查優先級是否合理、ROI 計算是否準確。抽樣筆數依模組量自定，關鍵是固定頻率、留下紀錄、發現問題就調整規則或提示詞。抽樣抓的是「流程沒報錯但優先級排序不合理」這類最安靜的事故。
- 變更紀律：團隊評估標準更新、LLM 供應商更新模型版本、你改提示詞，都算變更。改動前先用最近的例外樣本與幾筆正常樣本重跑一遍，確認沒有變差再上；改動寫進台帳。
- 成本：LLM 節點的用量乘上供應官網單價，加上 SonarQube/CodeClimate 授權費與你的維運時間，就是這條流程的真實成本；估算方法見AI 成本怎麼算。
成果與驗收標準
| 檢查點 | 通過標準 | 沒通過怎麼辦 |
|---|---|---|
| 盤點基線 | 有技術債痛點表，頻率與成本是從 issue tracker 統計的紀錄 | 回到第一節；先別急著搭流程 |
| 主幹跑通 | 測試倉庫端到端跑完，檢測到故意放入的問題 | 檢查工具配置與權限 |
| 確定性邊界 | 代碼指標沒有任何一個由 LLM 改寫 | 改成自動化工具直接計算 |
| LLM 輸出校驗 | LLM 輸出有格式校驗節點，不合法進例外分支 | 在 LLM 節點後補校驗 |
| 冪等 | 手動觸發同一個模組兩次，沒有重複數據記錄 | 加數據存在性檢查 |
| 影子期 | 與人工並行連續數週結果一致才交接 | 延長影子期，逐項找不一致的原因 |
| 告警有效 | 故意製造一次失敗（暫撤測試 API Key），告警在承諾時間內到達值班渠道且內容完整 | 修告警路由與值班安排 |
| 監控習慣 | 台帳連續兩週每週有紀錄，抽樣複核有留痕 | 把監控指派到具體的人，放進行事曆 |
常見踩坑
- 讓 LLM 做確定性工作：「讓 AI 順便算一下圈複雜度」一時方便，代價是同樣輸入可能不同輸出，出了錯無法重現、無從追查。
- 用個人帳號的憑證：當事人離職、改密碼的那天，流程集體猝死。用服務帳號，並納入組織的憑證管理。
- 直接在生產倉庫上實驗：正確順序是測試倉庫、非敏感模組小範圍、全量。跳級的人通常在第二步就出事。
- 沒做冪等就開重試：重試機制會把偶發錯誤放大成重複數據事故。
- LLM 節點不設花費上限：一個迴圈觸發的臭蟲能讓流程整夜持續呼叫 API。上限與告警在供應商控制台設定，五分鐘的事。
- 告警發到沒人看的渠道：沒有值班表的告警是自我安慰。
- 忽略業務語境：純技術指標無法反映業務影響，必須結合用戶量、營收貢獻等業務數據，否則優先級排序會偏離實際需求。
- 一次性評估所有模組：一週把上百個模組全部自動化，第二週就沒有人力調整誤報。先讓核心模組（最高頻使用的 10-20 個）穩定跑滿一個月，把模式沉澱成範本，再複製到其他模組。
- 缺乏管理層支持：技術債重構需要產品經理與管理層的認可，如果沒有提前溝通與教育，自動化產生的優先級清單會被忽視。第一個月重點不是降低誤報，而是建立「數據驅動決策」的文化共識，邀請產品經理參與評估模型的校準。
下一步
- 同一套「自動量化＋人工審核」模式用在代碼審查場景：自動化代碼審查助手
- API 文檔同步更新系統：API 文檔同步更新系統
- CI/CD 管道的異常檢測：CI/CD 管道異常檢測與修復建議
- 微服務架構的依賴可視化：微服務依賴關係地圖生成
- 資料分級與安全邊界：企業資料安全基本盤
- 上線前的合規檢查表：AI 合規與風險邊界
- 流程越串越多、要不要升級成平台：自建還是採購