技術債追蹤與重構優先級排序：從主觀感受到數據驅動的決策

專案上線半年，新功能開發越來越慢，每次改動都要花半天除錯；新人接手舊模組，看不懂為什麼這裡要這樣寫，問了一圈沒人記得當初的設計決策。這類「技術債累積」是工程團隊最常見的隱形成本：慢、難以量化、而且決策取決於誰的聲音最大。這篇是操作配方：用 SonarQube、CodeClimate、LLM 節點與自訂儀表板串出一條技術債量化流水線，讓機器從程式碼提取指標、評估業務影響、計算重構 ROI，人只處理需要業務語境判斷的部分。全文最重要的一節是第五節——哪些環節可以從程式碼自動量化，哪些環節必須由人評估業務影響，這條邊界畫錯了，自動化會比人工更危險。

這個場景解決什麼

適合這個配方的流程有四種特徵：高頻率（每天都有新程式碼）、跨模組（技術債影響多個服務）、規則說得清楚（代碼異味、重複率、複雜度有明確指標）、繁瑣但必須做。四者俱備的人工評估，通常有三種損耗：主觀（不同人對技術債嚴重程度看法不同）、延遲（等到出事才想重構）、不完整（只看程式碼不看業務影響）。

做完這個配方之後的目標狀態：技術債被量化為可比較的數字，重構優先級基於業務影響與 ROI 自動排序，Tech Lead 能用數據說服產品經理撥出重構時間。人的角色從「憑感覺說這很爛」變成「根據數據決定先修哪個」。

同時畫清邊界：這篇處理的是技術債的量化與優先級排序，不是要你用 AI 取代架構決策；需要長期演進方向判斷與權衡取捨的環節（例如「這個模組是否值得重構還是直接重寫」）也不在自動化範圍內。判斷一個場景值不值得自動化，先讀什麼時候不該用 AI。

工具組合與前置準備

• SonarQube：開源代碼品質平台，支援 30+ 語言的靜態分析，涵蓋 bug、漏洞、代碼異味、重複率、圈複雜度等維度。可自架或採用雲端版 SonarCloud。自建與採購的系統性取捨見自建還是採購。
• CodeClimate：商業代碼品質平台，提供維護性指數（Maintainability Index）、技術債比率、測試覆蓋率等綜合指標。優點是指標全面、易於理解；缺點是需要訂閱。方案與定價以官網為準。
• LLM API（本文以 DeepSeek 為例，任何供應商皆可）：負責流程中「業務影響評估」與「自然語言生成」的判斷。單價以供應商官網為準；接通後第一件事是在供應商控制台設定花費上限與用量告警。
• 自訂儀表板（Grafana、Metabase 或簡易 HTML Dashboard）：將技術債指標可視化，支援按模組、時間、嚴重程度篩選。優點是客製化自由度高；缺點是需要額外開發。

前置檢查表——每一項都有明確答案才動工：

資料分級的判斷方法見企業資料安全基本盤。

憑證紀律（先講，因為最常被忽略）：所有 API Key、OAuth Token 放進 CI/CD 平台的 secrets 機制；不要寫死在 workflow 檔案、註解或說明文件裡；不要把含憑證的配置檔提交到公開倉庫。

一、盤點人工評估痛點

花兩週，把所有技術債評估中的常見問題列成一張表：

兩個填寫紀律：頻率與成本是從實際 issue tracker 與 git log 統計出來的，不靠印象——口頭回憶幾乎總是低估；修復成本要寫具體事件（哪次 hotfix、花了多少人天），寫不出成本的問題，說明它可能根本不值得優先自動化。

這張表有兩個用途：下一步的選型依據，以及上線後計算效益的基線。「自動化前平均每筆技術債評估多久、自動化後例外處理要多久」都從這張表與後面的執行紀錄算出來——自己測的數字，比任何文章裡的參考值可靠。

二、選一條最痛的模組

四個條件同時成立才動手：頻率高（經常變更）、規則寫得出來（有明確的代碼指標）、出錯有代價（影響業務穩定性）、工具鏈有介面。

兩類流程先避開：即將廢棄的 legacy 模組（不值得投入重構）；業務邏輯極度複雜且無文檔的模組（LLM 無法理解上下文，誤報率過高）。

第一版切小：只做「程式碼掃描 → 指標提取 → 業務影響評估 → ROI 計算 → 優先級排序 → 儀表板展示」這一條主幹。自動化重構建議、歷史趨勢預測全留到第二版。一條穩定跑通的主幹，勝過一張完整但沒上線的設計圖。

三、自架還是雲端

決策方法：資料分級結果說「不能出網」時，自架 SonarQube 幾乎是唯一選項；否則先用 CodeClimate Cloud 把第一條流程跑通，累積了真實用量與失敗紀錄，再評估要不要遷移。不論哪種，都先用測試倉庫跑通示範流程，第一天不碰生產倉庫。

四、串出最小可跑版本

節點組裝順序：

1. 觸發節點：定時觸發（每週一次）或 push 事件觸發（監聽特定路徑）。優先定時觸發，避免每次 commit 都掃描造成資源浪費。
2. 掃描節點：執行 SonarQube Scanner 或 CodeClimate CLI，輸出結構化的代碼指標 JSON（圈複雜度、重複率、代碼異味數、測試覆蓋率等）。
3. 業務映射節點：將程式碼路徑映射到業務模組（如 src/orders/** → 「訂單模組」），可透過配置檔或 LLM 自動推斷。
4. LLM 評估節點：將代碼指標、近期 issue 數據、業務模組重要性送入 LLM，要求輸出業務影響評分與重構建議。
5. ROI 計算節點：根據重構預估工時、預期減少的 bug 數、節省的開發時間，計算重構投資回報率。
6. 優先級排序節點：綜合代碼指標評分、業務影響評分、ROI，計算綜合優先級分數，生成排序清單。
7. 儀表板更新節點：將結果寫入資料庫或儀表板 API，更新可視化界面。

試跑期三條紀律：

• 用測試倉庫：建立 test-tech-debt 倉庫，故意放入已知問題（高複雜度函式、重複程式碼、缺少測試），驗證工具能否正確檢測並評分。
• 留執行紀錄：除平台內建的執行歷史外，為重要流程加一個「台帳」分支——每次執行把時間、模組名稱、各項指標、優先級分數寫進一張專用表格或資料庫。這是第八節監控的原料。
• 影子模式上線：自動化先生成優先級清單但不強制執行，人照樣憑經驗決定重構順序，逐週比對兩邊結果。連續一致之後才讓自動化接管低風險模組的重構決策，人轉為審核高風險模組。

五、哪些環節交給自動量化、哪些必須用人評估

這是全文最重要的一節。原則一句話：確定性的代碼指標給自動化工具，LLM 只做「業務影響評估」這一類需要語境理解的事。

兩條鐵律：

1. 代碼指標永遠不經過 LLM 的嘴。 圈複雜度、重複率、測試覆蓋率由自動化工具原樣計算；LLM 只產評估與建議，不產事實。自動化評估裡代價最高的事故，形態幾乎都是「模型改寫了一個指標，而且改得很像真的」。
2. 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"
- 不要改寫任何代碼指標數值

六、錯誤處理、重試與冪等

先把失敗分成三類，因為三類的處置完全不同：

冪等是重試的前提：流程要保證「同一個模組跑兩次不會重複寫入數據」。做法是在寫入前先查詢該模組該時間點的數據是否已存在——存在就跳過或更新，絕不無腦新增。沒有冪等設計就開重試，等於裝了一台數據製造機：重複的指標記錄，比人工記錄還難收拾。

七、失敗告警

• 告警發到「有人在值班」的渠道：即時通訊群組或 email，且群組裡有明確的值班表。告警沒人看，等於沒有告警。
• 告警內容模板：流程名稱、模組名稱、失敗節點、錯誤摘要、發生時間、重跑方式。讓收到的人在半分鐘內能決定「現在處理還是稍後處理」。
• 分級防洗版：單筆模組掃描例外進每週匯總；API Key 過期、服務停機這類「流程已停」的事件才即時推送。每筆例外都彈一次通知，值班的人很快會把渠道靜音——告警系統就死在靜音那一刻。

八、上線後的監控

• 前兩週是觀察期：每天看執行歷史與台帳，記錄執行總數、失敗次數、誤報率（人工標記為不合理的優先級比例）。兩週之後自己算誤報率與主因分佈——這是你的流程自己的數據，判斷門檻（誤報率高到多少要調整評估模型）由你的團隊容忍度決定，定了就寫進值班說明，不要引用任何文章裡的現成數字。
• 每週抽樣複核：固定抽 3-5 個已自動評估的模組，人工複查優先級是否合理、ROI 計算是否準確。抽樣筆數依模組量自定，關鍵是固定頻率、留下紀錄、發現問題就調整規則或提示詞。抽樣抓的是「流程沒報錯但優先級排序不合理」這類最安靜的事故。
• 變更紀律：團隊評估標準更新、LLM 供應商更新模型版本、你改提示詞，都算變更。改動前先用最近的例外樣本與幾筆正常樣本重跑一遍，確認沒有變差再上；改動寫進台帳。
• 成本：LLM 節點的用量乘上供應官網單價，加上 SonarQube/CodeClimate 授權費與你的維運時間，就是這條流程的真實成本；估算方法見AI 成本怎麼算。

成果與驗收標準

常見踩坑

• 讓 LLM 做確定性工作：「讓 AI 順便算一下圈複雜度」一時方便，代價是同樣輸入可能不同輸出，出了錯無法重現、無從追查。
• 用個人帳號的憑證：當事人離職、改密碼的那天，流程集體猝死。用服務帳號，並納入組織的憑證管理。
• 直接在生產倉庫上實驗：正確順序是測試倉庫、非敏感模組小範圍、全量。跳級的人通常在第二步就出事。
• 沒做冪等就開重試：重試機制會把偶發錯誤放大成重複數據事故。
• LLM 節點不設花費上限：一個迴圈觸發的臭蟲能讓流程整夜持續呼叫 API。上限與告警在供應商控制台設定，五分鐘的事。
• 告警發到沒人看的渠道：沒有值班表的告警是自我安慰。
• 忽略業務語境：純技術指標無法反映業務影響，必須結合用戶量、營收貢獻等業務數據，否則優先級排序會偏離實際需求。
• 一次性評估所有模組：一週把上百個模組全部自動化，第二週就沒有人力調整誤報。先讓核心模組（最高頻使用的 10-20 個）穩定跑滿一個月，把模式沉澱成範本，再複製到其他模組。
• 缺乏管理層支持：技術債重構需要產品經理與管理層的認可，如果沒有提前溝通與教育，自動化產生的優先級清單會被忽視。第一個月重點不是降低誤報，而是建立「數據驅動決策」的文化共識，邀請產品經理參與評估模型的校準。

下一步

• 同一套「自動量化＋人工審核」模式用在代碼審查場景：自動化代碼審查助手
• API 文檔同步更新系統：API 文檔同步更新系統
• CI/CD 管道的異常檢測：CI/CD 管道異常檢測與修復建議
• 微服務架構的依賴可視化：微服務依賴關係地圖生成
• 資料分級與安全邊界：企業資料安全基本盤
• 上線前的合規檢查表：AI 合規與風險邊界
• 流程越串越多、要不要升級成平台：自建還是採購