القائمة
證據驅動除錯流程。Use for: (1) Bug 修復的結構化流程（重現 -> failing test -> 根因 -> 最小修復 -> 回歸防護）, (2) 防止盲目猜測修復, (3) 確保每次修復可驗證、可追溯、可累積。Use when: 收到 bug report、測試失敗需要調查、生產環境問題需要修復、任何非新功能的程式碼修正。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Composes atomic, intent-revealing, grep-friendly writing (Zettelkasten) for code comments, docs, logs, prompts, schema/ticket fields, and long-form technical articles. Use when cognitive load and token cost matter. Triggers: 寫註解, 寫文件, 寫日誌, 寫 prompt, 寫文章, 技術文章, post-mortem, 架構決策, 除錯復盤, 欄位設計, atomic, reusable.
Agent Teams 協作派發指南。Use when: (1) Agent A 的發現會改變 Agent B 正在進行的工作, (2) 用戶要求使用 team/swarm, (3) 多代理人需即時協商共用介面或 API 契約。涵蓋 team 建立、Ticket-Task 橋接、teammate 入職、生命週期管理。
Branch Worktree Guardian - Git 分支和 Worktree 管理工具。Use for: (1) 新開發需求時建立隔離分支, (2) 使用 worktree 機制避免分支衝突, (3) 驗證當前工作分支正確性, (4) 預防在錯誤分支上開發
broken-link 偵測工具。掃描 .claude/ 目錄所有 Markdown 文件中的路徑引用，偵測失效連結。Use for: (1) 一次性掃描所有 broken links, (2) 搭配 /loop 定期監控, (3) 修改規則/方法論/代理人文件後驗證路徑完整性。Use when: user runs /broken-link-check, 或搭配 /loop 定期執行, 或發現 broken link 錯誤後。
子任務拆分與 Context 卸載工具。將可拆分的大型任務分成 N 個子 Ticket，各由 Agent 獨立執行，結論直接寫入 Ticket 不回報主線程。Use for: 批量檔案評估, 大型審查任務拆分, 任何需要讀取大量資料但結果可落地到 Ticket 的任務
認知負擔評估與審查工具。作為決策樹、代理人、Code Review 的基本參考標準。用於: (1) 任務複雜度評估, (2) 代理人升級判斷, (3) 任務拆分建議, (4) 程式碼品質審查與熱點識別
| name | evidence-driven-bugfix |
| description | 證據驅動除錯流程。Use for: (1) Bug 修復的結構化流程（重現 -> failing test -> 根因 -> 最小修復 -> 回歸防護）, (2) 防止盲目猜測修復, (3) 確保每次修復可驗證、可追溯、可累積。Use when: 收到 bug report、測試失敗需要調查、生產環境問題需要修復、任何非新功能的程式碼修正。 |
核心原則：先有證據，才能動手。
沒有最小重現、沒有 failing test、沒有根因證據之前，禁止直接改程式碼。
| 反模式 | 後果 |
|---|---|
| 「我大概知道怎麼修，先 patch 再說」 | 修到症狀不是根因 |
| 跳過 failing test 直接改 code | 不知道到底修對沒 |
| 沒有調查紀錄 | 下次同類 bug 又得重查一次 |
| 一邊查一邊改 | 改動範圍失控，引入新問題 |
| 修改測試斷言來讓測試通過 | 測試失去防護價值，bug 仍存在 |
| 硬編碼預期值繞過測試 | 下次資料變動立即再次失敗 |
| 不查根因直接改程式碼試試看 | 表面通過但根因未解，同類 bug 反覆出現 |
本流程有兩種執行模式，依據緊急程度選擇：
| 模式 | 適用場景 | 必做階段 | 可延後階段 |
|---|---|---|---|
| 標準模式 | 一般 bug 修復 | Stage 1-8 全部 | 無 |
| Hotfix 模式 | 生產環境緊急問題 | Stage 1-5 | Stage 6-8（24 小時內補齊） |
/pre-fix-eval 是錯誤的入口分類器，/bugfix 是修復執行流程。
| pre-fix-eval 產出 | bugfix 入口 | 說明 |
|---|---|---|
| 有初步根因定位（Stage 4 完成） | 從 Stage 2 開始 | 根因假設已有，直接補 failing test 驗證 |
| 只有錯誤分類（Stage 1-3 完成） | 從 Stage 1 開始 | 需要完整重現和分析 |
| 直接由用戶觸發（無 pre-fix-eval） | 從 Stage 1 開始 | 完整流程 |
Stage 1: 最小重現 [執行者: 認領 Ticket 的開發者]
|
Stage 2: 補 Failing Test [執行者: 同上]
|
Stage 3: 驗證根因假設 [執行者: 同上 / incident-responder]
|
Stage 4: 實作最小修復 [執行者: 語言對應的 developer agent]
|
Stage 5: 回歸防護 [執行者: 同 Stage 4]
|
Stage 6: 規格合規審查 [執行者: /parallel-evaluation 派發]
|
Stage 7: 程式碼品質審查 [執行者: /parallel-evaluation 派發]
|
Stage 8: 結案報告 [執行者: 認領 Ticket 的開發者]
| 階段 | 對應的專案工具 |
|---|---|
| 進入本流程前 | /pre-fix-eval（錯誤分類 + Ticket 開設） |
| Stage 3 深度分析 | incident-responder（複雜根因需要時派發） |
| Stage 4 實作 | 語言對應的 developer agent |
| Stage 6-7 審查 | /parallel-evaluation（派發後以其檢查清單為準） |
| Stage 8 結案 | /doc-flow（工作日誌）、/error-pattern add（錯誤模式） |
目標：把「使用者描述的症狀」轉成「可判斷的重現條件」。
執行者：認領 Ticket 的開發者。
產出：重現步驟或腳本 + 環境條件記錄。
| 檢查項 | 說明 |
|---|---|
| 重現步驟是否穩定？ | 連續執行 3 次都能觸發 |
| 環境條件是否記錄？ | 瀏覽器版本、OS、資料狀態 |
| 是否為最小條件？ | 移除任何一步就無法重現 |
適用場景：race condition、時序問題、Chrome Service Worker 生命週期問題、特定網站結構下觸發。
| 替代條件 | 說明 |
|---|---|
| 有觸發條件描述 | 能說明在什麼狀態/時序下容易觸發 |
| 有日誌或錯誤截圖證據 | 至少有一次觸發的完整記錄 |
| 有機率估計 | 如「十次操作約觸發三次」 |
滿足以上三項即可通過閘門，進入 Stage 2 時使用防禦性測試策略（測試邊界條件而非精確重現）。
閘門：標準路徑或替代路徑任一滿足即可進入 Stage 2。兩者皆不滿足 → 回頭補充資訊。
目標：把重現步驟轉成穩定失敗的測試或結構化驗證計畫。
執行者：認領 Ticket 的開發者。
至少一個 failing test，精確描述「預期行為」與「實際行為」的差異。
| 要求 | 說明 |
|---|---|
| 測試命名 | 描述 bug 行為，如 test_should_not_crash_when_empty_input |
| 斷言精確 | 斷言預期的正確行為，不是斷言「不 crash」 |
| 獨立可執行 | 不依賴其他測試的副作用 |
適用場景：Chrome 跨 context 通訊、popup/background 互動、UI 渲染問題等 Jest mock 無法真實覆蓋的場景。
產出一份結構化手動驗證計畫：
## 手動驗證計畫
### 前置條件
[環境設定、資料準備]
### 驗證步驟
1. [具體操作步驟]
2. [預期結果]
3. [實際結果欄位（執行時填寫）]
### 通過標準
[明確的 pass/fail 判斷條件]
手動驗證計畫視為技術債，在 Stage 8 記錄，後續版本補自動化測試。
閘門：標準產出或替代產出任一完成即可進入 Stage 3。
目標：帶著 failing test 回頭讀 code，找出真正失敗的原因。
執行者：認領 Ticket 的開發者。複雜問題可派發 incident-responder。
流程：
工具選擇：
| 需求 | 工具 |
|---|---|
| 追蹤函式呼叫鏈 | Serena find_referencing_symbols |
| 搜尋特定模式 | Grep / search_for_pattern |
| 理解符號結構 | Serena get_symbols_overview |
若 Stage 3 確認根因不在本專案（如外部平台 API 行為變更、目標站點改版、上游套件行為變更）：
閘門：根因已確認（含外部因素確認） → 進入 Stage 4。禁止「看起來像是這裡的問題」就動手。
迭代上限：Stage 3↔4 來回不超過 3 次（Hotfix 模式下為 2 次）。超過上限仍無法定位 → 升級為 incident，派發 incident-responder 深度分析。Stage 6/7 回退到 Stage 4 後，迭代計數器重置（因根因已確認，問題性質不同）。
目標：只改讓 failing test 通過的最小範圍。
執行者：語言對應的 developer agent。
| 原則 | 說明 |
|---|---|
| 最小變更 | 修改檔案數 <= 3，diff 行數建議 < 50 行 |
| 超過需說明 | 超過上述範圍須在 Ticket log 記錄理由 |
| 不擴大範圍 | 發現周圍有問題 → 開新 Ticket，不在此修 |
| 確認 test 變綠 | 修完立即執行 Stage 2 的 failing test |
| 修產品程式碼，不修測試 | 見下方「測試完整性保護」 |
修復的目標是讓產品程式碼符合測試描述的正確行為，而非反過來。
| 禁止行為 | 範例 | 為什麼禁止 |
|---|---|---|
| 修改斷言值 | expect(result).toBe(3) 改成 toBe(5) | 測試描述的是正確行為，改斷言 = 改需求 |
| 硬編碼通過 | 函式直接 return 3 讓測試過 | 沒有解決邏輯問題，只騙過斷言 |
| 刪除失敗測試 | 刪掉「不方便」的測試案例 | 測試覆蓋率下降，bug 不被偵測 |
| 放寬驗證條件 | toEqual 改成 toBeTruthy | 降低測試精度，喪失防護力 |
唯一允許修改測試的場景：Stage 3 根因分析確認測試本身的預期值有誤（如需求變更但測試未同步）。此時必須：
閘門：Stage 2 的 failing test 變綠 → 進入 Stage 5。未變綠 → 回到 Stage 3（受迭代上限約束）。
目標：避免同一個 bug 之後偷偷回來。
執行者：同 Stage 4。
| 動作 | 說明 |
|---|---|
| 確認 failing test 已納入 CI | 不是臨時腳本，是正式測試 |
| 補邊界測試 | 根因相同但輸入不同的場景，至少補 1 個測試 |
| 執行完整測試套件 | npm test 確認無回歸 |
完整測試套件出現失敗時：
| 情況 | 判斷方式 | 處理 |
|---|---|---|
| 本次修復導致 | git stash 後失敗消失 | 回到 Stage 4 修正 |
| 既有 flaky test | git stash 後仍失敗 | 開獨立 Ticket 追蹤，不阻擋本流程 |
閘門：完整測試套件通過（排除已記錄的 flaky test） → 進入 Stage 6。未通過 → 依分流表處理。
目標：確認修復符合原始需求與驗收條件。
執行者：透過 /parallel-evaluation 派發，以其檢查清單為準。
以下為最低檢查項（若 /parallel-evaluation 已涵蓋則不重複）：
| 檢查項 | 說明 |
|---|---|
| 修復是否符合 use case 描述？ | 對照 docs/use-cases.md |
| 是否引入行為變更？ | 對使用者可見的行為改變需記錄 |
| 驗收條件是否滿足？ | 對照 Ticket 的驗收條件 |
閘門：審查通過 → 進入 Stage 7。不通過 → 回到 Stage 4 修正（不重置 Stage 3 的根因結論）。
目標：確認修法乾淨、可維護、無副作用。
執行者：同 Stage 6（通常與 Stage 6 在同一次 /parallel-evaluation 中完成）。
以下為最低檢查項（若 /parallel-evaluation 已涵蓋則不重複）：
| 檢查項 | 說明 |
|---|---|
| 符合專案品質基線？ | 對照 .claude/references/quality-common.md |
| 無硬編碼？ | 常數提取、訊息外部化 |
| 可觀測性？ | 錯誤路徑有日誌 |
| 無過度修改？ | diff 只含必要變更 |
閘門：審查通過 → 進入 Stage 8。不通過 → 回到 Stage 4 修正。
目標：整理修復紀錄，讓經驗可累積。
執行者：認領 Ticket 的開發者。
最小產出：
## Bug Fix Report
### 症狀
[使用者觀察到的問題]
### 根因
[Stage 3 確認的根本原因]
### 修復方式
[Stage 4 的修改摘要]
### 影響範圍
[修改的檔案清單 + 影響的功能模組]
### 排除的假設
[Stage 3 中排除的其他假設及排除理由]
### 回歸防護
[Stage 5 新增的測試]
### 殘留風險
[已知但未處理的相關問題，已開 Ticket 追蹤]
### 技術債
[Stage 2 的手動驗證計畫待自動化、其他待處理項目]
### 關聯資訊
- Ticket ID: [ID]
- 修復耗時: [時間]
- 關聯 Ticket: [相關 Ticket ID]
額外動作：
/error-pattern add 記錄/doc-flow/ticket track complete一個 bug report 實際上包含多個獨立問題時：
| 時機 | 判斷標準 | 處理 |
|---|---|---|
| Stage 1 發現 | 重現步驟觸發多個不同症狀 | 拆分為獨立 Ticket，各自走完整流程 |
| Stage 3 發現 | 根因分析指向多個獨立原因 | 當前 Ticket 只修第一個根因，其餘開新 Ticket |
| 階段 | 閘門條件 | 不通過時 |
|---|---|---|
| Stage 1 → 2 | 標準路徑或替代路徑任一滿足 | 回頭補充資訊 |
| Stage 2 → 3 | 有 failing test 或手動驗證計畫 | 不准開始分析 |
| Stage 3 → 4 | 根因已確認（含外部因素） | 不准開始修改 |
| Stage 3 → 8 | 外部因素確認（捷徑） | 產出簡化報告，開 workaround Ticket |
| Stage 4 → 5 | failing test 變綠 | 回到 Stage 3（上限 3 次 / Hotfix 2 次） |
| Stage 5 → 6 | 完整測試通過（排除已知 flaky） | 依分流表處理 |
| Stage 6 → 7 | 規格合規審查通過 | 回到 Stage 4 修正（迭代計數器重置） |
| Stage 7 → 8 | 品質審查通過 | 回到 Stage 4 修正（迭代計數器重置） |
/bugfix顯示本流程概覽和閘門總覽。
/bugfix start [ticket-id]從 Stage 1 開始完整流程。行為：
/bugfix stage N [ticket-id]跳到指定階段。行為：
/bugfix hotfix [ticket-id]啟動 Hotfix 模式。行為：
Last Updated: 2026-04-02 Version: 2.2.0 - 新增測試完整性保護規則（禁止修改測試繞過失敗）