systematic-debugging

systematic-debugging 技能是一項強制性的技術協議，旨在消除代理程式在遇到錯誤時傾向於應用「快速修補」或「猜測」的常見陷阱。此技能將開發重點從快速的試錯轉向以證據為基礎的工程實踐。對於優先考慮架構完整性、穩定性和長期維護性，而非表面、短期修正的資深工程師與開發者而言，此技能至關重要。它在處理難以診斷的間歇性錯誤、效能瓶頸和環境特有問題的複雜系統中尤其有效。

• 第一階段（根本原因調查）：要求仔細檢查堆疊追蹤、日誌、錯誤訊息和 Git 紀錄。它要求必須能一致地重現問題，並在收集到足夠證據前禁止任何修補嘗試。

• 多組件儀表化：引導代理程式在組件邊界（API、服務、資料庫層）注入日誌和診斷遙測，以準確隔離狀態或資料流偏離預期模式的具體位置。

• 模式分析：將損壞的實作與已知的工作程式碼和參考模式進行比較，以識別細微的配置不匹配或依賴偏移。

• 假設驅動測試：在執行最小可能的程式碼變更前，需要清晰的單一假設，並確保更新或建立測試（RED-GREEN-REFACTOR）以驗證根本原因是否已解決。

• 架構護欄：如果超過三次嘗試失敗，將觸發強制暫停和諮詢機制，這表明問題很可能是架構性的而非簡單的邏輯錯誤，從而防止長時間的無效折騰。

• 適用於任何意外行為、建置失敗、整合問題或生產環境錯誤。

• 輸入包括錯誤日誌、堆疊追蹤、重現步驟和系統架構細節。

• 輸出包括經驗證的根本原因聲明、最小失敗測試案例，以及經過驗證的單一程式碼修正。

• 約束條件：除非四階段調查完成，否則代理程式嚴格禁止提出修補方案。「鐵律」禁止在未識別失敗根源的情況下修復症狀。

• 與 tdd 和規劃技能直接整合，確保在解決過程中維持程式碼品質。