問題分類
調查回報的問題,找出其根本原因,並建立一個包含 TDD 修復計畫的 GitHub Issue。這是一個盡量減少人工干預的工作流程 - 將對使用者的提問降到最低。
流程
1. 捕捉問題
從使用者那裡獲取問題的簡短描述。如果使用者尚未提供,請只問一個問題:「您遇到的問題是什麼?」
請勿再追問。立即開始調查。
2. 探索與診斷
使用子代理類型為 Explore 的 Agent 工具來深入探索程式碼庫。你的目標是找出:
- 錯誤在哪裡表現出來(進入點、UI、API 回應)
- 涉及了哪些程式碼路徑(追蹤流程)
- 為什麼它會失敗(根本原因,而非症狀)
- 有哪些相關的程式碼存在(相似模式、測試、相鄰模組)
查看:
- 相關的原始檔案及其依賴項目
- 現有的測試(測試了什麼、缺少什麼)
- 受影響檔案最近的變更(在相關檔案上執行
git log) - 程式碼路徑中的錯誤處理
- 程式碼庫中其他地方能正常運作的相似模式
3. 確定修復方法
根據你的調查結果,決定:
- 修復根本原因所需的最小變更
- 哪些模組/介面會受到影響
- 哪些行為需要透過測試來驗證
- 這個問題是回歸錯誤、缺少功能、還是設計缺陷
4. 設計 TDD 修復計畫
建立一個具體、有序的「紅-綠」循環列表。每個循環都是一個垂直切片:
- RED:描述一個能捕捉到損壞/缺失行為的特定測試
- GREEN:描述讓該測試通過所需的最小程式碼變更
規則:
- 測試應透過公開介面驗證行為,而非實作細節
- 一次只進行一個測試,採垂直切片方式(不要先寫所有測試,再寫所有程式碼)
- 每個測試都應能承受內部的重構
- 如有需要,在最後包含一個重構步驟
- 穩定性:僅建議那些能夠承受劇烈程式碼庫變更的修復方案。描述行為與合約,而非內部結構。測試應斷言可觀察的結果(API 回應、UI 狀態、使用者可見的效果),而非內部狀態。好的建議讀起來像一份規格書;差的建議讀起來像一個差異比較。
5. 建立 GitHub Issue
使用 gh issue create 指令並搭配下方的範本建立 GitHub Issue。不要要求使用者先審閱再建立 - 直接建立並分享 URL。
問題
問題的清晰描述,包含:
- 實際發生的狀況(實際行為)
- 應該發生的狀況(預期行為)
- 如何重現(如果適用)
根本原因分析
描述你在調查過程中的發現:
- 涉及的程式碼路徑
- 目前程式碼失敗的原因
- 任何促成因素
請勿包含與目前程式碼佈局耦合的特定檔案路徑、行號或實作細節。請改為描述模組、行為與合約。即使經過重大重構,這個 Issue 仍應保持其適用性。
TDD 修復計畫
一個編號的「紅-綠」循環列表:
-
RED:撰寫一個測試,用來[描述預期行為] GREEN:[讓測試通過的最小變更]
-
RED:撰寫一個測試,用來[描述下一個行為] GREEN:[讓測試通過的最小變更]
...
REFACTOR:[所有測試都通過後所需的任何清理工作]
驗收標準
- 標準 1
- 標準 2
- 所有新測試通過
- 現有測試仍能通過
建立 Issue 後,請列印 Issue URL 與一行根本原因摘要。