From zenbu-powers
系統化除錯方法論。遇到任何 bug、測試失敗或非預期行為時使用,在提出任何修復方案前強制執行。 以 4 階段流程(根因調查 → 模式分析 → 假設驗證 → 實作修復)杜絕「猜一下、改一下」的隨機修補, 並針對 WordPress / React / AIBDD 場景補充常見 bug 模式。 改寫自 obra/superpowers 的 systematic-debugging skill,在地化為 WP 生態。
npx claudepluginhub zenbuapps/zenbu-powers --plugin zenbu-powersThis skill uses the workspace's default tool permissions.
**沒有根因調查就沒有修復。** 隨機修補浪費時間且製造新 bug,症狀修復是失敗。
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Checks Next.js compilation errors using a running Turbopack dev server after code edits. Fixes actionable issues before reporting complete. Replaces `next build`.
Guides code writing, review, and refactoring with Karpathy-inspired rules to avoid overcomplication, ensure simplicity, surgical changes, and verifiable success criteria.
Share bugs, ideas, or general feedback.
沒有根因調查就沒有修復。 隨機修補浪費時間且製造新 bug,症狀修復是失敗。
⚠️ 鐵律:完成 Phase 1(根因調查)之前,禁止提出任何修復方案。
違反此原則的字面意思就是違反除錯的精神。
對任何技術問題都適用:
特別必須使用的時機:
禁止的鬆綁理由:
在提出任何修復之前:
完整讀錯誤訊息
可重現性確認
檢查最近變更
git diff、git log -10composer.json / package.json 改動多元件系統的 instrumentation
WordPress 與 React 應用通常跨多層(PHP → REST API → React → WP REST → DB)。 提出修復前,先在每個元件邊界加 log:
// PHP layer
error_log( '[DEBUG][hook=init] user_id=' . get_current_user_id() );
// REST API layer
error_log( '[DEBUG][rest] payload=' . wp_json_encode( $request->get_params() ) );
// React layer
console.log('[DEBUG][useQuery]', { isLoading, error, data });
跑一次收集證據 → 看哪一層斷掉 → 再深入該層調查。
資料流回溯
錯誤出現在 stack 深處時,往上追到「壞值的源頭」,在源頭修,不在症狀點修。
詳見 references/root-cause-tracing.md。
修之前先找模式:
科學方法:
修根因,不修症狀:
先寫一個能重現 bug 的失敗測試
@zenbu-powers:test-creator 產生骨架zenbu-powers:tdd-workflow 的 Red 階段單一修復 — 解決根因;禁止「順便重構」、「順便改一下」
驗證修復
zenbu-powers:tdd-workflow 的 Green Gate(貼命令輸出)修不好怎麼辦
架構性問題的訊號:
這時候不要再試 Fix #4,而是:
必須與使用者討論後才能繼續。 這不是「假設失敗」,是「架構錯誤」。
| 模式 | 症狀 | 真正的根因 |
|---|---|---|
| Hook 順序錯誤 | add_action 沒觸發 / 觸發時資料還沒準備好 | priority 設錯、hook 在當前 request 已經跑完了、用 init 做 wp_loaded 該做的事 |
| Nonce 失效 | REST API 401、表單提交失敗 | nonce 過期、user 已登出、nonce action 名稱不一致、cache 把 nonce 快取了 |
| Capability 漏檢查 | 越權、API 任何人能打 | permission_callback 寫成 __return_true、current_user_can 帶錯 capability |
| Object Cache 不一致 | 改了資料但讀回來是舊的 | 改完忘了 wp_cache_delete、persistent cache 跨 request 殘留、update_option 後沒清相關 transient |
| HPOS 雙寫漂移 | WooCommerce order 在 wp_posts 與 wc_orders 表不一致 | 直接寫 wp_posts 而沒用 CRUD API、舊 plugin 還在用 get_post_meta 讀 order meta |
| PHP 8 deprecation | warning 滿天飛、未來版本壞掉 | null 傳給期待 string 的函式、{} 字串存取語法 |
autoload=yes 撐爆 wp_options | 整站慢 | 把大物件用 update_option 存且沒設 autoload=no |
| 模式 | 症狀 | 真正的根因 |
|---|---|---|
| Render race condition | 資料 flash、UI 閃舊值 | useEffect 沒清 stale closure、useState 沒帶 functional updater、TanStack Query 的 keepPreviousData 用錯 |
| Hook 規則違反 | 「Rendered fewer hooks than expected」 | early return 在 hook 之前、hook 寫在 if 裡 |
| Stale closure | 事件 handler 拿到舊 state | useCallback 依賴漏列、setInterval 沒重建 |
| List key 重複 | 重排時 component state 錯位 | 用 array index 當 key、key 不穩定 |
| TanStack Query cache 不刷新 | mutate 後資料沒更新 | 沒呼叫 invalidateQueries、queryKey 結構不一致 |
| 模式 | 症狀 | 真正的根因 |
|---|---|---|
| Feature 對 API 漂移 | E2E 跑得過、整合測試失敗 | feature 改了但 api.yml 沒同步、用 zenbu-powers:aibdd-consistency-analyzer 掃 |
| Entity / ERM 漏欄位 | handler 拿不到欄位、type error | erm.dbml 過時、Aggregate 沒重生 |
| ASM/GAP 標註被忽略 | 規格腦補導致實作走偏 | 看到 ASM、GAP 沒回澄清就硬寫 |
如果你發現自己在想:
全部停手。回 Phase 1。
3+ 次修復失敗 → 質疑架構(Phase 4.5)。
當使用者講以下這些話,代表你的方法錯了:
看到這些訊號,立刻停手回 Phase 1。
| 藉口 | 真相 |
|---|---|
| 「問題很簡單,不用走流程」 | 簡單 bug 也有根因,跑流程很快 |
| 「緊急情況沒時間走流程」 | 系統化比亂改快 |
| 「先試一下這個再來調查」 | 第一個修復定錨後續,一開始就要做對 |
| 「修好之後再補測試」 | 沒測試的修復不持久 |
| 「一次改多個地方省時間」 | 隔離不出哪個有效,新增 bug |
| 「reference 太長,我改一下 pattern 就好」 | 半吊子理解 = 必 bug,完整讀 |
| 「我看到問題了,直接修」 | 看到症狀 ≠ 理解根因 |
| 「再試最後一次」(試了 2+ 次) | 3+ 次失敗 = 架構問題 |
| 整合對象 | 角色 |
|---|---|
zenbu-powers:tdd-workflow | Phase 4 的失敗測試走 Red 階段;Phase 4 的修復驗證走 Green Gate |
@zenbu-powers:test-creator | Phase 4 寫失敗測試的執行者 |
zenbu-powers:aibdd-consistency-analyzer | AIBDD 場景下檢查規格漂移 |
@zenbu-powers:wordpress-master | WP 領域實作根因修復 |
@zenbu-powers:react-master | React 領域實作根因修復 |
@zenbu-powers:security-reviewer | 若 bug 涉及權限、資料外洩,必須拉進來審 |
| Phase | 主要動作 | 完成條件 |
|---|---|---|
| 1. 根因 | 讀錯誤、重現、檢查變更、加 log、追資料流 | 知道什麼壞了、為什麼壞了 |
| 2. 模式 | 找對照組、讀 reference、列差異 | 找出工作版與壞版的差異 |
| 3. 假設 | 寫下假設、最小化測試 | 假設被證實或被推翻 |
| 4. 修復 | 寫失敗測試、修根因、驗證 | bug 解掉、所有測試綠 |
| 4.5 | 3+ 次失敗 → 質疑架構 | 與使用者討論後決定方向 |
| 隨機修補 | 系統化除錯 |
|---|---|
| 2-3 小時 thrash | 15-30 分鐘解掉 |
| 第一次修對率 ~40% | ~95% |
| 經常製造新 bug | 幾乎不製造 |
走流程不是慢,是快。
完整的 root cause tracing、defense in depth、condition-based waiting 技巧:
superpowers:systematic-debugging skill 的 reference 檔案