修正 Bug
找出根本原因。不要修補症狀。不論是應用程式還是函式庫,這個原則都不變。
此技能僅在修復完成且變更為綠色後,才會載入 prove-it,而且只有當使用者選擇它或已要求證明時才會載入。它不會覆蓋 CopilotKit 的除錯技能。
使用時機
當失敗發生時載入:失敗的測試、紅燈的 CI、非預期的結果、堆疊追蹤,或使用者說「壞了」/「修正這個」。
跳過沒有失敗的全新功能開發。跳過文件及純類型修改。
嚴格守則
- 在從日誌中確定原因之前,不得進行任何修復。 不允許「隨便試幾個方法」。
- 在熱路徑上,至少要提出三個假設,且須來自不同位置(我們的函式、呼叫者、依賴項)。
- 在每個假設的路徑前後加入除錯日誌。如果涉及的第三方套件有除錯模式,請在此次調查中開啟它。
- 當原因確定後:刪除此技能加入的所有日誌,並關閉第三方除錯模式。 然後撰寫會失敗的測試。最後才進行修復。日誌絕不能留在修復中。
- 不得跳過、刪除或停用失敗的測試 來讓測試變成綠色。不得吞沒錯誤(
|| true、空的 catch 區塊)。不得為了隱藏競爭條件而提高超時時間。 - 修復根本原因,以及同檔案或附近模組中的相同模式。不要做額外的重構。
- 除非使用者選擇,或已要求證明此次修復,否則不要載入
prove-it。 測試套件變成綠色不代表已經過證明。預設為跳過。
熱路徑
從失敗的測試(或使用者操作)開始,沿著堆疊向下到錯誤行,以及呼叫和被呼叫的函式。
從那裡開始。排除。 縮小範圍。只有在該路徑上的所有假設都無效時,才擴大範圍。
程序
程序 1:讀取
- 讀取完整的錯誤訊息、堆疊追蹤或 CI 日誌。每一行都要看。
- 如果有的話,讀取失敗測試的內容。
- 如果有的話,讀取可能引入此錯誤的差異比對。
- 尚不進行編輯。
程序 2:假設
- 繪製熱路徑圖(檔案和函式)。
- 提出至少三個假設:「錯誤是由 X 引起的,因為 Y。」它們必須涵蓋整個熱路徑(不能只是對同一行程式碼的三種猜測)。
- 如果無法寫出三個,表示你讀得不夠。回到程序 1。
程序 3:植入儀器
- 對於假設中提到的每個第三方套件:查閱其文件,看是否有除錯旗標或環境變數。如果有,就開啟它。
- 在每個假設分支的前後加入暫時的日誌(輸入值進來、輸出值出去)。使用該儲存庫既有的日誌記錄器或
console。不要新增日誌記錄套件。 - 重現一次錯誤。讀取日誌。劃掉日誌證明為無效的假設。
- 如果三個假設都無效,將熱路徑向外擴展一步(下一個呼叫者或下一個依賴項)。提出新的假設。加入新的日誌。再次排除。
- 當一個原因被確定時:刪除此技能加入的所有日誌。 關閉第三方除錯模式。確認工作目錄中已沒有那些日誌殘留。
程序 4:先寫失敗測試,再修復
- 撰寫一個會因為這個 Bug 而失敗的測試(紅燈)。測試需有獨立預期值。不可跳過此步驟。
- 執行它。它必須因為你所指名的原因而失敗。
- 僅修正根本原因。同時修正同一個檔案或附近模組中相同錯誤的副本。
- 執行該測試(綠燈)。然後執行此套件/此檔案對應套件的現有測試。
- 如果出現新的失敗,將其視為新的 Bug。從程序 1 開始。不要在第一個修復之上疊加新的錯誤就出貨。
程序 5:選擇性證明(prove-it)
- 在此套件的測試套件變成綠色且日誌已移除後,詢問一次。選項:載入
prove-it,或跳過。預設 跳過。 - 等待。在使用者選擇之前,不要載入
prove-it。 - 如果他們在此對話中已經要求證明這個修復,則跳過詢問。直接載入
prove-it。 - 如果跳過: 說明此修復未經證明,是一個使用者路徑。不要將綠燈的測試套件當作證明。進入程序 6。
- 如果他們選擇
prove-it:載入prove-it並遵循其指示。然後進入程序 6。 - 不要在此技能內部點擊應用程式、curl API 或編寫證明報告。這些工作屬於
prove-it。
程序 6:結束
在跳過之後,或在 prove-it 回傳結果之後,結束。
決策樹
- 失敗發生 → 程序 1 → 2 → 3 → 4 → 5 → 6。
- 無法重現 → 結束。說明無法重現。請使用者提供步驟。不要猜測性地修復。
- 日誌推翻了所有熱路徑假設 → 擴大範圍,再次進行程序 2。
- 修復後測試仍然是紅燈 → 原因錯誤。還原修復。回到程序 2。
- 下一個函式中發現相同模式 → 在同一變更中一併修正(嚴格守則 6)。
- 測試套件變成綠色,但尚未詢問證明 → 程序 5(詢問,預設跳過)。
- 使用者已要求證明此修復 → 載入
prove-it,然後進入程序 6。
紅旗警示
| 訊號 | 代表意義 | 應該怎麼做 |
|---|---|---|
| 一個假設,然後直接修補 | 猜測 | 程序 2。在熱路徑上建立三個假設。 |
| 沒有日誌的修復 | 未經排除 | 程序 3。 |
差異比對中仍有除錯 console.log | 日誌未清除 | 程序 3 的步驟 5。然後才寫測試。 |
第三方 DEBUG=* 仍處於開啟狀態 | 除錯旗標被發布 | 與日誌一同關閉。 |
.skip / 刪除失敗測試 | 處理症狀 | 修正程式碼。 |
| ` | true` / 空的 catch 區塊 | |
| 更長的超時時間 | 隱藏競爭條件 | 修正競爭條件。 |
| 在修復時一併重構 | 順便亂改 | 只修正根本原因 + 相同模式。 |
| 執行整個 monorepo 的測試 | 未經要求 | 只執行這個套件 / 這個測試套件。 |
| 「在我機器上可以跑」 | 環境不同 | 使用與失敗時相同的命令 / 相同的條件。 |
未經詢問就載入 prove-it | 未經要求的證明 | 程序 5。預設跳過。 |
| 在此技能內進行迷你瀏覽器驗證 | 與 prove-it 重複 | 待使用者選擇後載入 prove-it。 |
| 「測試通過了,所以已經過證明」 | 將綠燈套件當作證明 | 程序 5。跳過即表示未經證明。 |
錯誤處理
- 無法重現: 說明情況。列出你執行了哪些步驟。不要憑空發明修復。
- 依賴項沒有除錯模式: 跳過該步驟。仍然對我們自己的熱路徑程式碼進行日誌記錄。
- 日誌過大: 只記錄假設分支的日誌,不要記錄檔案中的每一行。
- 尚無法撰寫失敗測試(無測試框架): 用一個單一檔案的腳本來斷言這個 Bug,作為替代方案。腳本仍是紅燈,然後修復,然後變成綠燈。
- 修復導致另一個測試失敗: 對該失敗進行程序 1。在第一個修復造成的連鎖問題解決之前,不要推送它。
- 此代理程式上缺少
prove-it: 說明情況。提議跳過。不要在此技能內自創第二個證明程序。 - 使用者選擇
prove-it,然後在裡面跳過: 此修復未經證明。程序 6。
此技能不會放置輔助工具或撰寫文件。證明僅是程序 5。