bug-close

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），使用指定的範圍。

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 建立

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 為空，則跳過此步驟。

7. 回傳結果

向使用者回傳：

• 更新後的 Notion 頁面連結
• 變更摘要（修改了幾個檔案、根因分類、目前狀態）
• 知識庫條目連結（若有同步）
• 提示後續操作：

  Bug 已結案！後續事項：
  • 驗證完成後請在 Notion 頁面勾選驗證項目
  • 若上線後問題復發，可使用 /bug-update reopen 重新開啟
  

---

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，應降級為「普通」。

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

---

邊界情況

• 設定檔不存在：提示使用者先執行 /bug-setup 完成初始設定
• 無 commit 可擷取：提示使用者先 commit 修復程式碼
• Notion 頁面內容與模板不符：使用 replace_content 而非 update_content，先保留原有內容再附加修復資訊
• 使用者想手動補充調查過程：提示可直接在 Notion 頁面編輯「調查過程」區塊
• diff 過大（> 500 行）：僅摘要檔案清單和關鍵變更，不貼完整 diff