bug-update

bug-update — 調查過程中更新 Bug 文件 / 重新開啟已結案 Bug

在調查 Bug 期間，將關鍵 Log、SQL 查詢、初步判斷、問題描述補充等資訊，即時寫入 Notion「任務追蹤工具」的 Bug 頁面對應區塊。

也支援將已結案（測試中/已完成）的 Bug 重新開啟（reopen），適用於上線後發現問題未完全修復的情境。

---

設定檔

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

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

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

---

前置條件

• 已使用 /bug-start 建立 Bug 條目

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

---

流程

0. 判斷操作模式

根據使用者輸入判斷是「一般更新」還是「重新開啟」：

• 輸入包含 reopen、重新開啟、復發、退回 → Reopen 模式（跳至步驟 1-B）
• 其他 → 一般更新模式（跳至步驟 1-A）

1-A. 定位目標 Bug 頁面（一般更新）

從設定檔讀取「任務追蹤工具」Data Source ID，精確查詢該資料庫：

使用 notion-search 搭配 data_source_url: collection://{任務追蹤工具 Data Source ID} 搜尋：

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

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

優先匹配邏輯：

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

選定後，使用 notion-fetch 取得頁面完整內容，以便後續 update_content 操作。

1-B. 定位目標 Bug 頁面（Reopen 模式）

Reopen 模式需要定位「測試中」或「已完成」的 Bug。

Step 1 — 解析使用者輸入

使用者輸入	判斷
包含 Notion URL（notion.so/ 或 notion.site/）	→ 直接定位模式：以 URL 中的 page_id 定位頁面
包含非 URL 文字	→ 關鍵字搜尋模式：在「任務追蹤工具」Data Source 中搜尋「測試中」+「已完成」的 Bug，以關鍵字匹配標題
什麼都沒提供（僅 reopen）	→ 互動式清單模式

Step 2 — 互動式清單模式（無參數時）

當使用者只輸入 /bug-update reopen，不帶任何參數時：

1. 從設定檔讀取「任務追蹤工具」Data Source ID（所有查詢都用此 ID，不做全 Workspace 搜尋）
2. 取得當前 Git Repo 識別碼，匹配設定檔中的專案
3. 使用 notion-search 搭配 data_source_url: collection://{任務追蹤工具 Data Source ID}，搜尋狀態為「測試中」或「已完成」且所屬專案匹配的 Bug（按建立時間降序，最多顯示 10 筆）
4. 若當前在修復分支上且能匹配到 Bug，將該筆標記為推薦
5. 顯示互動式清單：

偵測到 Git Repo：TPE01P2101/LineBC

以下為該專案近期已結案的 Bug：

1. [2026-03-15] 訂閱推播開封數欄位與點擊率公式不一致
2. [2026-03-12] customAggregationUnits 含連字號導致 LINE API 400 錯誤  ⭐ 推薦（符合當前分支）
3. [2026-03-10] 傳送數重複計算與 API 回應格式處理

請選擇要重新開啟的 Bug：
  • 輸入編號（如 1）
  • 輸入關鍵字搜尋更多
  • 貼上 Notion 頁面連結

5. 根據使用者回應：
   • 數字 → 選定對應的 Bug
   • Notion URL → 直接定位頁面
   • 其他文字 → 作為關鍵字重新搜尋，顯示新的結果清單

Step 3 — 定位失敗處理

若以上方式都找不到目標 Bug：

找不到符合條件的已結案 Bug，請嘗試：
  1. 貼上 Notion 頁面連結（在 Notion 找到該 Bug 頁面，複製連結）
  2. 提供更精確的關鍵字
  3. 切換到當初的修復分支後重試

定位成功後，執行 Reopen 操作：

1. 更新狀態：使用 notion-update-page 將狀態從「測試中/已完成」改回「進行中」
2. 新增復發紀錄：使用 notion-update-page 的 update_content，在「驗證」區塊之前插入「復發紀錄」區塊：

---

## 🔄 復發紀錄

### [{日期} 復發] {使用者提供的復發說明，若無則留空待補}
- **復發環境**：{若使用者有提供則填入，否則留空}
- **復發現象**：{若使用者有提供則填入，否則留空}
- **前次修復為何無效**：

---

3. 取消驗證勾選：將「驗證」區塊中已勾選的項目取消勾選（改回 - [ ]）
4. 回傳結果：向使用者顯示：
   • 已重新開啟的 Bug 標題與 Notion 連結
   • 目前狀態已退回「進行中」
   • 提示後續用法：

     Bug 已重新開啟，後續可使用：
     • /bug-update <調查內容>  — 補充新的調查資訊
     • /bug-close              — 二次修復完成後結案
     

2. 判斷更新類型

根據使用者輸入的內容，自動判斷應更新哪個區塊：

使用者輸入特徵	目標區塊	說明
包含「通報」、「回報」、「反映」、機關名稱	問題描述 > 通報來源	補充通報來源
包含重現步驟描述（「先...再...然後...」）	問題描述 > 重現步驟	填入具體步驟
包含「預期」、「應該」	問題描述 > 預期行為	填入預期行為
包含 log、stacktrace、Exception、ERROR	調查過程 > 關鍵 Log	以 code block 格式貼入
包含 SQL、select、update、insert	調查過程 > 相關 SQL 查詢	以 sql code block 格式貼入
包含「判斷」、「推測」、「可能是」、「初步」	調查過程 > 初步判斷	寫入判斷內容
使用者明確指定區塊	指定區塊	依使用者指示

若無法自動判斷，詢問使用者要更新哪個區塊。

3. 支援的輸入方式

方式 A：直接在指令中提供內容

/bug-update 關鍵 log：NullPointerException at PushService.java:235

/bug-update 初步判斷：推播排程在取得 access token 時發生空指標，可能是 token 過期未更新

/bug-update 通報來源：公共運輸處窗口 王小明

方式 B：從剪貼簿或終端機貼入

使用者可直接貼入多行 log 或 SQL：

/bug-update

然後 Claude Code 會詢問「請貼上要更新的內容」，使用者貼入後自動判斷類型並更新。

方式 C：從檔案讀取

/bug-update log /opt/tomcat/logs/catalina.out

讀取指定 log 檔案的最後 50 行，擷取 ERROR/Exception 相關內容，寫入「關鍵 Log」。

4. 更新 Notion 頁面

使用 notion-update-page 的 update_content 指令：

原則：

• 附加而非覆蓋：同一區塊可多次更新，每次新內容附加在既有內容之後
• 加上時間戳：每次更新前加上 [HH:mm] 時間標記，方便追溯調查過程
• 格式化：Log 用 code block、SQL 用 sql code block、一般文字用 bullet point

5. 回傳結果

向使用者回傳：

• 已更新的區塊名稱
• 更新內容的前 2 行預覽
• Notion 頁面連結

---

快捷用法彙整

一般更新

/bug-update 通報來源：公共運輸處窗口         → 更新問題描述
/bug-update 預期行為：應正常顯示使用者列表    → 更新問題描述
/bug-update 重現步驟：1.登入後台 2.點選使用者管理 3.搜尋「嵇南淩」 → 更新問題描述
/bug-update <直接貼 stacktrace>               → 更新關鍵 Log
/bug-update <直接貼 SQL>                      → 更新相關 SQL 查詢
/bug-update 初步判斷：employees 表 status=99   → 更新初步判斷
/bug-update log /path/to/catalina.out         → 從檔案擷取 ERROR 寫入關鍵 Log

重新開啟（Reopen）

/bug-update reopen                                        → 顯示該專案近期已結案 Bug 清單，互動式選擇
/bug-update reopen SSO登入找不到使用者                      → 用關鍵字搜尋已結案 Bug
/bug-update reopen https://www.notion.so/abe41af9...      → 直接指定 Notion 頁面連結
/bug-update reopen SSO登入 正式環境仍出現相同錯誤            → 關鍵字 + 復發說明一起提供

---

Gotchas

• update_content 語意是覆蓋不是附加：notion-update-page 的 update_content 對同一區塊寫入時會覆蓋該區塊內容。多次寫同一區塊時，必須先 notion-fetch 取得現有內容，串接新內容後再寫回，否則會覆蓋之前的調查紀錄。
• Reopen 勾選取消格式：checkbox 是 Notion 的 to_do block，用 update_content 改 checked 狀態即可；用 replace_content 會意外刪除使用者手動新增的內容。
• 時間戳用本地時間：[HH:mm] 標記要用 24 小時制本地時區。Claude 預設 UTC，需用 date 指令取本地時間（如 date +%H:%M）再填入。

---

邊界情況

• 設定檔不存在：提示使用者先執行 /bug-setup 完成初始設定
• 頁面內容與標準模板不符：嘗試模糊匹配區塊標題（如「關鍵 Log」或「Log」），找不到則附加在頁面最後
• 更新內容過長（> 200 行）：自動截斷，保留前 50 行和後 20 行，中間以 ... (省略 N 行) ... 替代
• 多次更新同一區塊：新內容附加在既有內容之後，以時間戳區隔
• Reopen 已完成的 Bug：保留原有的根因分析與修復方案（不覆蓋），新增「復發紀錄」區塊記錄新一輪調查
• 多次復發：每次 reopen 在「復發紀錄」區塊下新增一個子區塊，以日期區隔，完整保留所有歷程
• Reopen 找不到目標：顯示三種補救方式（Notion 連結 / 關鍵字 / 切換分支）
• Reopen 互動清單為空：該專案沒有已結案 Bug，提示確認專案是否正確或改用關鍵字/Notion 連結
• Reopen 清單輸入 Notion URL：直接切換為 URL 定位模式，不再搜尋