bug-close

name	bug-close
description	修復 Bug 後，從 Git diff 自動擷取修復細節並更新 Notion 頁面。當使用者提到「結案」、「關閉 bug」、「bug 完成」、「bug-close」、「修完了」時觸發此 Skill。

Bug Close — 結案並自動補齊修復細節

修復 Bug 並 commit 後，從 Git 自動擷取修改資訊，更新 Notion「任務追蹤工具」的 Bug 頁面，並在「Bug 知識庫」同步建立精簡條目。

---

設定檔

執行前依序檢查以下路徑，讀取第一個找到的設定檔：

1. ~/.claude-company/bug-workflow-config.md（公司環境）
2. ~/.claude/bug-workflow-config.md（個人環境）

若都不存在，提示使用者先執行 /bug-setup。

---

前置條件

• 已使用 /bug-start 建立 Bug 條目（Notion「任務追蹤工具」中有狀態為「進行中」的 🐞 錯誤條目）
• 修復程式碼已 commit

前置檢查：參照 references/prerequisites.md 執行完整前置檢查（CLAUDE.md + 設定檔 + 專案註冊）。

---

流程

1. 從 Git 擷取修復資訊

依序執行以下指令：

# 當前分支
git branch --show-current

# 最近 10 筆 commit（供使用者選擇範圍）
git log --oneline -10

# 預設取最近 1 個 commit 的變更
git diff HEAD~1..HEAD --stat

# 完整 diff（用於摘要化）
git diff HEAD~1..HEAD

若使用者指定 commit 範圍（如 HEAD~3..HEAD），使用指定的範圍。

1.5 Merge 引導（Feature Branch → DEV）

結案前，若偵測到修復在 feature branch 上進行，引導使用者 merge 回開發分支。

判斷條件

同時滿足以下三項才觸發：

1. 當前分支是 Bug 的修復分支：git branch --show-current = Bug Notion 頁面的「修復分支」欄位
2. 當前分支是 feature/hotfix 分支（非 DEV/PRD）：不匹配專案設定中的 dev_branch、uat_branch、prod_branch
3. 能取得 DEV 分支名稱：從 feature-workflow 的 projects/{repo-id}.md 讀取 dev_branch 欄位

dev_branch 取得路徑：先嘗試 ~/.claude-company/feature-workflow/projects/{repo-id}.md，再嘗試 ~/.claude/feature-workflow/projects/{repo-id}.md。

互動式引導

📋 結案前分支合併

當前在 feature/qa-log-user-id-statistics
目標 DEV 分支：MOM01P2401_DEV

要合併回 DEV 嗎？
  1. 是，merge --no-ff 並繼續結案
  2. 否，我稍後自己合併
  3. 已經合併過了，直接結案

選 1：執行 Merge

1. 檢查工作區乾淨：git status --porcelain
   • 有未提交變更 → 提示先 commit 或 stash，暫停
2. 切換到 DEV：git checkout {dev_branch}
3. 拉取最新：git pull（若有 remote tracking）
4. 合併：git merge {feature_branch} --no-ff
   • 成功 → 繼續結案流程
   • 衝突 → 顯示衝突檔案列表，暫停結案，提示使用者解決衝突後重新執行 /bug-close
5. 不自動 push，在結案結果中提示：git push origin {dev_branch}

選 2 或 3：跳過 Merge

直接進入原有的結案流程。

條件不滿足時

• 當前不在修復分支 → 跳過
• 當前在 DEV/PRD 分支 → 跳過
• dev_branch 未設定 → 顯示簡化提示：

  💡 目前在 feature branch，結案後記得 merge 回開發分支。
     若要啟用自動 merge 引導，請在專案設定中新增 dev_branch。
  

2. 搜尋對應的 Bug 條目

搜尋 Notion「任務追蹤工具」（Data Source ID 見設定檔）中符合條件的條目：

使用 notion-search 搜尋：

• 條件：狀態為「進行中」且任務類型包含「🐞 錯誤」

同時取得 Git Repo 識別碼（從 git remote get-url origin 解析），用於輔助篩選同一專案下的 Bug。

優先匹配邏輯：

1. 若「修復分支」欄位與當前 Git branch 完全匹配 → 自動選定
2. 若有多個候選，優先顯示與當前 Git Repo 所屬專案相關的條目
3. 若有多個候選 → 列出清單讓使用者選擇
4. 若無候選 → 提示使用者先用 /bug-start 建立

2.5 退出驗證門檻

結案前執行 4 項檢查，確保修復品質達標：

#	檢查項	驗證方式	失敗處理
C1	根因分析已填寫	Notion 頁面「根因分析」區塊非空	WARN：提醒補填，允許繼續但狀態強制為「測試中」
C2	修復 commit 存在	git log --oneline -10 中有相關 commit	BLOCK：必須先 commit
C3	迴歸測試存在	grep test 目錄中含 "Regression: {bug 相關關鍵字}"	WARN：建議用 /bug-fix 產出
C4	驗證項目至少一項勾選	Notion 頁面 checkbox 狀態	WARN：提醒驗證

驗證結果顯示：

退出驗證：
  ✅ C1 根因分析已填寫
  ✅ C2 修復 commit 存在（abc1234）
  ⚠️  C3 無迴歸測試
  ⚠️  C4 驗證項目未勾選

結論：可結案，建議處理 C3 和 C4

若 C1 為 WARN → 目標狀態選項中移除「已完成」，只能選「測試中」。

3. 互動式補充資訊

詢問使用者（若未在初始輸入中提供）：

1. 根因分類：邏輯錯誤 / 資料異常 / 設定問題 / 第三方API / 效能 / 權限 / 前端UI
2. 根因說明：一句話描述為什麼會發生（例如：「employees 表的 status 欄位被誤設為 99 導致查詢不到」）
3. 目標狀態：測試中（預設）或 已完成

4. 產出修復摘要

根據 git diff 自動產出以下內容：

修改檔案清單：從 --stat 擷取，格式化為列表 修改說明：根據 diff 內容，以分層架構摘要（如 Java 專案的 Controller / Service / DAO 層） 修改後程式碼：擷取關鍵的程式碼變更片段（不超過 50 行）

5. 更新 Notion Bug 頁面

使用 notion-update-page 更新條目：

Properties 更新：

欄位	值
狀態	使用者選擇（預設「測試中」）
根因分類	使用者選擇的分類
修復分支	當前 Git branch（若原本為空）

Content 更新：

使用 update_content 指令，搜尋模板中的空白區塊並填入：

1. 「根因分析」區塊：

   • 問題根因 = 使用者提供的根因說明
   • 問題檔案 = 從 diff stat 擷取的檔案路徑
   • 問題程式碼 = diff 中被刪除的關鍵程式碼

2. 「修復方案」區塊：

   • 修改檔案清單 = 格式化的檔案列表
   • 修改說明 = 自動產出的分層摘要
   • 修改後程式碼 = diff 中新增的關鍵程式碼
   • 修復 Commit = commit hash + message
   • 修復分支 = branch 名稱

6. 同步到知識庫

在「Bug 知識庫」資料庫建立一筆精簡條目（Data Source ID 見設定檔）：

欄位	值
Name	Bug 標題
Tags	根據 bug 內容自動推測相關標籤
難易度	根據修改檔案數和 diff 行數判斷：≤3 檔案且 ≤50 行 → 普通(2~4h)，否則 → 困難(4~6h)
專案資料庫	同一專案
參考連結	任務追蹤工具的頁面 URL

頁面內容為精簡版：

**根因**：{根因說明}

**解法**：{修復摘要，2-3 句話}

**關鍵程式碼**：
（修改前後的關鍵差異）

若設定檔中「Bug 知識庫」ID 為空，則跳過此步驟。

6.5 學習捕捉

AI 分析本次 bug 的根因、修復和調查過程，判斷是否有可複用的洞察。

學習類型

類型	說明	範例
pattern	可複用的 bug 模式	「此專案的 token 過期 bug 常發生在推播模組」
pitfall	應避免的陷阱	「LINE API 的 503 需要特別處理，不能只處理 401」
architecture	架構層面的洞察	「PushService 和 TokenService 的耦合度太高」
environment	環境相關的知識	「正式環境的 LINE API rate limit 是 100 req/min」

學習格式

寫入 ~/.claude-company/bug-workflow/learnings/{project-slug}.jsonl：

{
  "date": "2026-04-24",
  "skill": "bug-close",
  "bug_title": "推播排程發送失敗",
  "root_cause": "LINE API refresh 回傳 503 未處理",
  "pattern": "third-party-api",
  "type": "pitfall",
  "insight": "LINE API 的 refresh token 端點偶爾回傳 503，retry 邏輯必須涵蓋 503 且加入 exponential backoff",
  "confidence": 9,
  "files": ["PushService.java"],
  "notion_url": "https://www.notion.so/xxx"
}

project-slug 來自 Git Repo 識別碼（/ 替換為 -）。每行一筆 JSON（JSONL 格式）。

自動 vs 手動

AI 自動判斷是否有學習價值：

• 有明確洞察 → 自動寫入，在結案訊息中顯示「學習已捕捉：{insight}」
• 不確定 → 詢問使用者：「這次 bug 有什麼值得記下來的嗎？」
• 太泛/太明顯 → 不記錄（如「要注意 null check」太泛，不記）

學習目錄建立

mkdir -p ~/.claude-company/bug-workflow/learnings

若目錄不存在，首次使用時自動建立。

7. 回傳結果

向使用者回傳：

• 更新後的 Notion 頁面連結
• 變更摘要（修改了幾個檔案、根因分類、目前狀態）
• 知識庫條目連結（若有同步）
• Merge 結果（若 Step 1.5 執行了 merge）：「已合併 feature/xxx → {dev_branch}」
• 提示後續操作：

  Bug 已結案！後續事項：
  {若有 merge} • git push origin {dev_branch}  — 推送合併結果
  • 驗證完成後請在 Notion 頁面勾選驗證項目
  • 若上線後問題復發，可使用 /bug-update reopen 重新開啟
  {若 feature branch 不再需要} • git branch -d feature/xxx  — 清理分支
  

---

Gotchas

• update_content 找不到區塊標題：如果使用者手動修改過 Notion 頁面（例如把「🧠 根因分析」改成「根因分析」），update_content 的搜尋模式會匹配失敗。遇到這種情況，改用 replace_content 重寫整個頁面內容（先讀取現有內容合併）。
• diff 包含二進位檔案：git diff 遇到圖片、Excel 等二進位檔案會顯示 Binary files differ，不要把這些納入「修改後程式碼」區塊。只擷取文字類檔案的 diff。
• 知識庫 Tags 推測容易偏離：自動推測 Tags 時，Claude 傾向選太多標籤。限制最多 3 個，優先選與 bug 直接相關的模組標籤（如「推播」、「排程」），避免選泛用標籤（如「API」、「效能」除非確實是那類問題）。
• commit 範圍判斷：使用者可能在修 bug 過程中穿插了不相關的 commit（如 merge commit）。若 git log --oneline -10 中混有非修復用途的 commit，應先確認正確範圍再擷取 diff，不要盲目用 HEAD~1..HEAD。
• 難易度判斷閾值偏保守：「≤3 檔案且 ≤50 行 → 普通」的規則在重構型修復（改很多檔但每個只改一行）時會誤判為困難。若 diff 中大部分是 import 變更或 rename，應降級為「普通」。
• Merge 引導是建議不是強制：Step 1.5 的 merge 引導可以跳過。有些場景使用者會在其他工具（如 GitLab MR）做 merge，不需要在 CLI 操作。
• dev_branch 跨 plugin 讀取：Merge 引導需要讀取 feature-workflow 的設定檔取得 dev_branch，但 bug-close 是 bug-workflow 的 skill。讀取失敗時顯示簡化提示，不阻擋流程。
• Merge 衝突不自動解決：衝突屬於需要人類判斷的操作，遇到衝突時暫停結案流程，等使用者解決後重新執行 /bug-close。
• 不自動 push：merge 完成後不自動執行 git push，因為 push 會影響遠端共享狀態，需使用者明確操作。

參考 examples/good-closure-report.md 了解理想的結案報告結構和品質。

---

邊界情況

• 設定檔不存在：提示使用者先執行 /bug-setup 完成初始設定
• 無 commit 可擷取：提示使用者先 commit 修復程式碼
• Notion 頁面內容與模板不符：使用 replace_content 而非 update_content，先保留原有內容再附加修復資訊
• 使用者想手動補充調查過程：提示可直接在 Notion 頁面編輯「調查過程」區塊
• diff 過大（> 500 行）：僅摘要檔案清單和關鍵變更，不貼完整 diff
• merge 衝突：顯示衝突檔案列表，暫停結案流程，提示使用者解決衝突後重新執行 /bug-close
• feature-workflow 未安裝或未設定：Merge 引導改為簡化提示，不阻擋結案
• DEV 分支在本地不存在：嘗試 git checkout {dev_branch}（git 會自動從 remote tracking 建立本地分支），若失敗則 git fetch && git checkout {dev_branch}
• Feature branch 是否應刪除：不自動刪除，僅在結案提示中建議。若 Feature 仍在開發中，刪除分支會造成問題