메뉴
證據驅動除錯流程。Use for: (1) Bug 修復的結構化流程（重現 -> failing test -> 根因 -> 最小修復 -> 回歸防護）, (2) 防止盲目猜測修復, (3) 確保每次修復可驗證、可追溯、可累積。Use when: 收到 bug report、測試失敗需要調查、生產環境問題需要修復、任何非新功能的程式碼修正。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Branch Worktree Guardian - Git 分支和 Worktree 管理工具。Use for: (1) 新開發需求時建立隔離分支, (2) 使用 worktree 機制避免分支衝突, (3) 驗證當前工作分支正確性, (4) 預防在錯誤分支上開發
Claude Code release notes 框架影響評估工具。比對 last-reviewed 版本篩出新版本，逐項分類（對框架有幫助 / 需評估 / 無影響 / 不適用），對採用項引導建 ANA + WRAP + spawn 落地。Use when: 執行 /release-notes 看到新版本、定期檢查 CC 更新、評估新功能對專案框架的影響時。Triggers: release notes, release-notes, CC 更新, claude code 更新, 版本更新評估, 新功能評估, 框架影響評估。
Use this skill for managing git worktrees for Ticket-based development. Triggers include: creating a worktree for a new ticket, checking worktree status, viewing all worktrees, or any mention of /worktree, worktree management, feature branches, or setting up development environment.
版本發布整合工具。Use for: (1) 發布新版本（合併到 main、打 Tag、推送）, (2) 發布前健康檢查（所有 Ticket 完成？CHANGELOG 更新？）, (3) 更新版本文件（worklog 狀態、CHANGELOG）。Use when: 準備發布版本、執行 /version-release check 確認發布前狀態、完成所有 Ticket 後要收尾時。
Composes atomic, intent-revealing, grep-friendly writing (Zettelkasten) for code comments, docs, logs, prompts, schema/ticket fields, external-analysis transformation, and long-form technical articles. Use when cognitive load and token cost matter. **Also triggers during multi-round review / batch review / 寫作 audit** — provides the keyword bank (正向陳述 / 口語修辭 / 地區用語 / 廢話前綴 / 裝飾符號 / 對讀者喊話 / 自評誇飾 / 必然性框架) and frame-specific check lists that multi-round-review reviewer agents need. Triggers: 寫註解, 寫文件, 寫日誌, 寫 prompt, 寫文章, 技術文章, 商業分析, 外部分析文章, post-mortem, 架構決策, 除錯復盤, 欄位設計, atomic, reusable, 多輪審查, multi-round review, batch review, 寫作 audit, 正向陳述, 口語修辭, 字句層 grep.
寫多篇章節後做多輪 agent reviewer audit 的標準操作流程。每輪用不同 frame 切換、跨輪 finding 互不重疊、停止訊號是 frame 涵蓋而非 finding 數遞減。Round 1-A 寫作規範 reviewer 必須同步 invoke `compositional-writing` skill 的字句層 keyword bank（正向陳述 / 口語修辭 / 地區用語 / 廢話前綴 / 裝飾符號 / 對讀者喊話 / 自評誇飾 / 必然性框架）、且命中後要做語意判定（命中是候選不是判決）。觸發詞：多輪審查、Round 1/2/3、frame 切換、跨輪審查、reviewer 規劃、何時停止 review、寫作 audit、batch review、cadence 同骨化、enumeration 不窮盡、正向陳述、self-application sweep。Trigger when reviewing multiple writings via successive rounds of agent reviewers.
| 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。
流程：
Why：W17-102 Test G 設計時用「PM 是否已 Edit 過該檔」（檔案層級）作變因，否證後直接跳到「不是 PM 接觸史」結論。但真正的變因可能在不同粒度——「PM 是否已 Edit 過 prefix（.claude/）內任一檔」（前綴層級）。同一個變因在不同粒度可能得到相反結論。
Consequence：粒度錯誤會讓對照實驗的否證跳到錯誤結論。否證「該檔層級的 PM 接觸史」≠ 否證「整個 PM 接觸史變因」。
Action：列假設後、設計驗證實驗前，對每個假設執行粒度自檢：
| 粒度層 | 範例（以「檔案修改史」為變因） | 範例（以「session 狀態」為變因） |
|---|---|---|
| 檔案層 | 該特定檔是否被改過 | 該檔在當前 session 是否被觸碰 |
| 前綴 / 目錄層 | .claude/ 下任一檔是否被改 | session 內是否曾操作該前綴 |
| 模組 / 命名空間層 | 同模組任一檔是否被改 | session 內是否載入該模組 |
| Session 層 | 任一 session 內檔案修改紀錄 | 當前 session 是否處於某狀態（已 commit / 已 pytest） |
| 跨 session 層 | 跨 session 累積修改 | 跨 session 累積觸發狀態 |
| 時間層 | 修改時間段（過去 N 分鐘 / N 小時 / N 天） | session 啟動時間距今 |
| 全域層 | 系統全域狀態（CC 版本 / 環境變數 / OS） | runtime 全域狀態 |
自查問句（每個假設都要問）：
強制動作：每個假設至少考慮 2 個相鄰粒度層；若只考慮單一粒度即進入驗證實驗，標記為「粒度未充分」並補實驗或在結論中明示。
粒度修正的教訓：先以大粒度否證後，若未驗證相鄰粒度即下結論，假設族否證不完整（需補相鄰粒度實驗）。
工具選擇：
| 需求 | 工具 |
|---|---|
| 追蹤函式呼叫鏈 | 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 - 新增測試完整性保護規則（禁止修改測試繞過失敗）