除錯不是試錯過程，是品質提升的系統性工程。隨機修復會產生隨機品質。系統化除錯產生一致的架構改善。

當AI協作處理複雜程式問題時，系統化除錯方法論成為唯一的執行準則。模糊的修復策略會產生模糊的結果。明確的除錯方法論產生一致的品質改善。

系統化除錯的本質

系統化除錯不是什麼

系統化除錯不是：

• 症狀修復：不掩蓋警告，只找根本原因
• 批量處理：不自動修復，只精確分析
• 簡單先行：不從容易修的開始，只按風險優先級
• 表面清理：不只消除警告，只完成未完成的設計

系統化除錯是什麼

系統化除錯是：

• 根因分析：明確區分未完成實作vs過度設計
• 風險導向：按業務風險和架構影響排序修復
• 主從分工：主線程管控進度，代理人執行修復
• 品質提升：每次修復都強化程式設計完整性

除錯的第一原則：根因分析優先

問題本質分類

每個unused警告都屬於以下三類之一：

未完成實作

• 識別：功能設計完整但驗證邏輯缺失
• 處理：補完實作而非移除程式碼
• 範例：測試中建立了secondImport變數但未驗證重複匯入行為

過度設計

• 識別：功能已完成但包含不必要的複雜性
• 處理：移除多餘程式碼保持精簡設計
• 範例：建立獨立服務實例但架構採用單例模式

程式碼風格問題

• 識別：邏輯正確但命名或結構不一致
• 處理：重構改善可讀性和一致性
• 範例：使用File物件但混用path字串操作

分析判斷標準

• 變數有明確的業務意圖 → 未完成實作
• 變數創建後立即被丟棄 → 過度設計
• 變數使用方式不一致 → 程式碼風格問題

不存在「可能是」的情況。如果無法明確分類，則需要更深入的程式碼分析。

範例：完整的根因分析

情境：test檔案中unused變數 ‘initialMemory’

錯誤分析

「這個變數沒用到，直接刪掉。」

正確分析過程

1. 變數意圖：記憶體效率測試的基線測量
2. 使用模式：建立但未在驗證邏輯中引用
3. 分類判斷：未完成實作（測試設計完整但驗證缺失）
4. 修復策略：補完基線比較邏輯而非移除變數

除錯的第二原則：風險導向排序

檔案風險等級

檔案修復必須按風險等級執行：

高風險檔案（立即修復）

• 核心業務邏輯：Domain層實作檔案
• 基礎設施元件：Database、Service、Repository
• 關鍵測試：端到端測試、整合測試

中風險檔案（計畫修復）

• 輔助功能：Utility、Helper類別
• 測試工具：Mock、TestData產生器
• 配置檔案：Configuration、Environment設定

低風險檔案（可延後修復）

• 單元測試變數：純測試輔助變數
• 範例程式碼：Demo、Sample實作
• 文件產生器：Documentation工具

風險評估標準

• 影響核心功能 → 高風險
• 影響開發效率 → 中風險
• 純粹警告清理 → 低風險

每個檔案只能歸類到一個風險等級。無法分類表示需要進一步的架構分析。

修復優先序執行規則

• 高風險檔案：立即修復，不考慮複雜度
• 中風險檔案：當前Sprint完成
• 低風險檔案：下個版本或維護期處理

除錯的第三原則：主從分工模式

角色定義

系統化除錯採用明確的角色分工：

主線程職責

• 進度管控：追蹤修復狀態和整體進展
• 策略決策：確定修復優先序和資源配置
• 品質檢查：驗證修復結果符合品質要求
• 工作記錄：更新工作日誌避免遺漏

代理人職責

• 詳細分析：深入檢查程式碼設計意圖
• 修復執行：實際編寫和修改程式碼
• 測試驗證：確保修復後功能正常
• 技術回報：提供修復細節和影響評估

協作執行規則

• 主線程永不直接修復程式碼
• 代理人永不決定修復優先序
• 每修復一個檔案都必須更新工作日誌
• 所有修復決策都必須通過主線程確認

範例：完整的協作流程

情境：發現5個檔案有unused警告

主線程執行

1. 風險評估：將5個檔案按業務風險分類
2. 優先排序：確定高風險檔案的修復順序
3. 委託分析：要求代理人分析第一個檔案
4. 進度追蹤：更新TodoList標記當前處理檔案

代理人執行

1. 根因分析：判斷unused變數屬於未完成實作vs過度設計
2. 修復實施：根據分析結果執行對應的修復策略
3. 結果驗證：執行靜態分析工具確認警告消除
4. 影響報告：回報修復內容和對整體架構的影響

主線程確認

1. 驗證結果：檢查靜態分析工具輸出確認修復成功
2. 更新記錄：在工作日誌中記錄修復成果
3. 繼續協作：標記完成並委託下一個檔案分析

品質標準

修復完成的判斷標準

每個檔案修復完成必須滿足：

• 警告消除：靜態分析工具不再顯示該檔案的unused警告
• 功能完整：所有測試通過，不引入新的錯誤
• 架構一致：修復符合Clean Architecture分層原則
• 文件更新：工作日誌記錄修復內容和影響

整體品質提升指標

• 警告減少率：unused警告數量持續下降
• 功能完整性：修復過程中完成更多未完成的實作
• 架構一致性：程式碼風格和設計模式更加統一
• 可維護性：程式碼可讀性和邏輯清晰度提升

品質驗證機制

• 每個檔案修復後立即執行靜態分析工具驗證
• 定期檢查整體警告數量變化趨勢
• 記錄修復過程中發現的架構改善機會
• 確認每次修復都強化而非弱化程式品質

執行流程

標準修復流程

1. 問題評估 執行靜態分析工具識別所有unused警告

2. 風險分析 將含有警告的檔案按風險等級分類

3. 優先排序 確定高風險檔案的修復順序

4. 逐檔修復 按優先序對每個檔案執行：

   • 委託代理人詳細分析
   • 根因判斷(未完成實作vs過度設計vs程式碼風格)
   • 執行對應修復策略
   • 驗證修復結果
   • 更新工作記錄

5. 整體驗證 確認警告總數下降且無新錯誤引入

修復策略對應表

例外處理原則

• 分析器誤報：確認變數確實被使用後保持現狀
• 架構衝突：優先解決架構問題後再處理警告
• 測試失敗：立即修復測試問題，暫停警告修復
• 複雜邊界：分解為更小的問題單位處理

成果評估

量化指標

• 警告消除數量：已修復的unused警告總數
• 警告減少率：相對於初始狀態的改善百分比
• 檔案修復數量：完成修復的檔案總數
• 架構改善項目：修復過程中完成的設計改善

質化評估

• 根因解決率：真正解決問題vs僅消除警告的比例
• 架構一致性：程式碼風格和設計模式統一程度
• 功能完整性：修復過程中完成的未完成實作數量
• 可維護性提升：程式碼清晰度和邏輯簡潔性改善

實戰案例：v0.8.19成果

量化成果：

• 初始警告：49個
• 最終警告：25個
• 改善率：49.0%
• 修復檔案：7個高風險檔案

質化成果：

• 補完3個未完成的功能實作
• 移除4處過度設計的複雜程式碼
• 統一5個檔案的程式碼風格
• 解決2個架構不一致問題

持續改進

方法論優化

系統化除錯方法論必須持續優化：

• 記錄邊界案例：遇到的特殊情況和處理方式
• 更新風險分類：基於實戰經驗調整風險評估標準
• 改進協作模式：優化主線程和代理人的分工效率
• 補充修復策略：新增針對特定問題類型的處理方法

知識累積

每次系統化除錯的經驗都必須沉澱為方法論改進：

• 成功的修復策略納入標準流程
• 失效的方法從規範中移除
• 新發現的問題模式補充到分類標準
• 協作過程中的效率改善點持續優化

結論

系統化除錯方法論是品質提升的執行標準。它的價值在精確，它的目的是完成設計。

每個修復都是一次架構改善。每個分析都是一次設計檢視。每個協作都是一次品質提升。

執行系統化除錯就是執行品質標準。遵循這個方法論，我們能持續強化程式架構完整性和設計一致性。

這是工程規範，確保每次除錯都提升而非妥協專案品質。

延伸：套用到 Linux 系統除錯

這套方法論是語言與領域無關的通則。把它落到 Linux 系統除錯這個具體領域——「讀權威狀態而非肉眼猜表象」的紀律、症狀到情境的分流、逐層定位——見 Linux 除錯與診斷：診斷心法。那裡用實機案例（把鎖屏誤判兩次的教訓）展示同一套系統化紀律在 Linux 現場長什麼樣。