메뉴
本專案 (MV3 Chrome extension) 的除錯紀律與 playbook：先重現再修、證據優先於模式匹配、單變因修改、跨 context 時序問題、service worker 終止、storage 問題、flaky E2E 分流。當使用者提到「除錯、debug、壞掉、不會動、修不好、查原因、root cause、flaky、時好時壞」時觸發。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
建立本專案的 Pull Request：雙語描述 (zh-TW/en)、gh CLI、.agent/skills/pull-request/scripts/check-pr.sh 預驗證、references/pr_template.md 與 checklist.md。當使用者提到「開 PR、建 PR、create PR、pull request、提交變更、發 PR、新建 PR」時觸發。
維護本專案 AI agent harness（AGENTS.md / CLAUDE.md / GEMINI.md / .agent/{rules,skills,workflows} / docs/wiki）的 SOP：單一事實來源對照表、drift 稽核步驟、新增/刪除 skill 的判準、wiki 同步機制。當使用者提到「更新 harness、同步 AGENTS、文件過時、drift、稽核設定檔、整理 skills、維護 wiki」時觸發。
交付前驗證紀律：依變更類型選擇最小充分驗證組合（unit / 目標 E2E / happy-path CI / make build）、Makefile 打包檢查、i18n 連動、GEMINI.md key_files 同步、誠實回報。當使用者提到「驗證、收尾、完成了嗎、可以交付嗎、送 PR 前、檢查一下」或任何實作即將收尾時觸發。
清理已合併進 main 的本地與遠端 git 分支。本專案採 squash merge，PR 合併後特性分支可直接刪除。當使用者提到「清理分支、cleanup branches、刪除舊分支、清掉已合併分支、整理 branch」時觸發。
本專案 (Manifest V3 Chrome extension) 的 commit 規範與範例：subject 使用英文 Conventional Commits、body 使用繁中說明背景與原因。當使用者提到「commit、提交訊息、commit message、寫 commit、commit 規範」時觸發。
撰寫本專案的 PRD (產品需求文件)，位置為 /docs/specs/{type}/{ID-PREFIX}_{desc}/PRD_spec.md。當使用者提到「PRD、產品需求、需求文件、寫規格、新功能規劃、acceptance criteria」時觸發。分級 SDD 之 T2（完整流程）的 Phase 1，產出物提供給 sa skill 銜接；T1 輕量案件不需獨立 PRD。
| name | debugging |
| description | 本專案 (MV3 Chrome extension) 的除錯紀律與 playbook：先重現再修、證據優先於模式匹配、單變因修改、跨 context 時序問題、service worker 終止、storage 問題、flaky E2E 分流。當使用者提到「除錯、debug、壞掉、不會動、修不好、查原因、root cause、flaky、時好時壞」時觸發。 |
修 bug 的品質差異不在「會不會寫 code」，而在下修改之前的判斷。本 skill 把判斷步驟固定下來，任何模型照走都能避開最常見的失敗模式。
chrome://extensions 的「錯誤」按鈕 / CI 的完整 log，不要只讀最後一行。git log --oneline -- <file> 看最近誰動過；行為是「本來好的」就用 git bisect（npm run test:ci 或單一測試檔當判準）。console.log（帶 context 前綴，如 [SW] / [panel]），修完必須移除。| 症狀 | 高機率根因 | 驗證方式 |
|---|---|---|
| 功能第一次好、閒置後壞 | MV3 service worker 被終止，in-memory 狀態消失 | SW console 看是否重啟；狀態是否該落 chrome.storage |
| options 頁改設定、sidepanel 沒反應 | settingsBridge 未映射該 storage key | 檢查 modules/ui/settingsBridge.js 的 resolveSettingChangeActions |
| Spotlight 動作沒在正確視窗執行 | panelBridge 旗標定址/TTL 守門擋掉 | 看 classifyPendingAction 判定與 windowId |
| 兩個 context 互相覆寫資料 | storage 全表寫入蓋掉別人的 delta（見 workspace mutateWindowMap 教訓） | 找出所有寫同一 key 的 context，確認是否 read→merge→write |
chrome.storage.sync 寫入無效 | 超過 8KB/key 或總量 quota | setStorageStrict（apiManager）回報 lastError |
| E2E 本機過、CI 掛 | race condition：固定 setTimeout 等待、事件委派未就緒 | 對照 review-pr.md CI 穩定性方針 8 條逐項檢查 |
| UI 事件沒觸發 | 事件委派容器還沒渲染就 dispatch / listener 延遲註冊 | 先 waitForSelector 容器再操作 |
| release 版壞、dev 版好 | 檔案沒進 Makefile 打包清單，或 esbuild bundle 差異 | 解開 zip 比對；make release 後檢查產物 |
# E2E 單檔快速迭代（最便宜的重現環境）
npx jest usecase_tests/puppeteer_tests/<file>.test.js
chrome://extensions → 該擴充功能 → 「服務工作處理程序」inspect。worker.evaluate）：
chrome.storage.local.get(null, console.log)、chrome.storage.sync.get(null, console.log)。.agent/workflows/puppeteer-test.md §4。sdd skill 判級：根因明顯的單點小修 = T0；需要調查、影響多模組 = T1（SPEC.md 寫根因分析）。