Quick Verify — MCP Chrome 快速驗證

原則：GitHub Issue 留言區 = 唯一真相來源。所有除錯過程（重現、根因、修復、驗證）都必須完整記錄在 Issue 留言區。對話會消失，Issue 留言不會。任何人隨時都能回顧完整脈絡。

Usage

code

/quick-verify {issue_number}

RULES

Rule 0: 所有過程記錄到 GitHub Issue（最重要）

不管驗證簡單或複雜，完整過程都必須 post 到 Issue 留言區：

code

必須記錄的內容（缺一不可）：
1. 重現過程 — 做了什麼操作、看到什麼結果、截圖
2. 根因分析 — 為什麼出錯（即使是 QA 文檔錯誤也要說明）
3. 修復內容 — 改了什麼、PR 編號
4. 驗證結果 — BEFORE/AFTER 截圖、在哪個環境驗證的

目的：
- 案主/PM/其他工程師可以隨時回顧這個 bug 的完整脈絡
- 下次遇到類似問題可以搜尋 Issue 找到歷史參考
- 防止同一個 bug 重複調查

Rule 1: MCP Chrome 優先

MCP Chrome 是第一選擇。只有以下情況才跳到 Playwright/Worktree：

•需要雙瀏覽器同步測試
•Fix 還沒部署到 staging（需要 localhost worktree）
•用戶明確要求 worktree mode

Rule 2: 截圖是必須的

每次驗證必須產出：

•BEFORE 截圖（bug 存在的證據）— 如果 fix 已部署則跳過
•AFTER 截圖（bug 修復的證據）
•截圖必須存檔到 .claude/evidence/issue-{N}/（feature branch 上）
•截圖必須透過 GitHub raw URL 嵌入 issue comment

Rule 3: 不可跳過重現

即使 issue 描述很清楚，也必須親眼在瀏覽器裡看到。「讀 code 分析」不等於「重現 bug」。

Steps

Step 1: 準備

bash

# 建立 evidence 目錄
mkdir -p /tmp/bugfix/issue-{N}

# 讀 issue
gh issue view {N}

# 讀 project CLAUDE.md 取得 credentials 和 staging URL

Step 2: MCP Chrome 重現 Bug（BEFORE）

code

1. tabs_context_mcp(createIfEmpty: true)
2. 建立新 tab: tabs_create_mcp()
3. navigate(tabId, staging_url + "/login")
4. 登入：
   - find(tabId, "email input") → form_input(ref, "demo.counselor@example.com")
   - find(tabId, "password input") → form_input(ref, "demo123")
   - find(tabId, "login button") → computer(left_click)
5. 按照 issue 的重現步驟操作
6. computer(action: "screenshot", tabId) ← 截圖 BEFORE

如果 fix 已部署到 staging：BEFORE 可能無法重現（bug 已修復）。這種情況：

•截一張 AFTER 截圖證明已修復
•在 issue comment 說明「fix 已在 staging，bug 無法重現（已修復）」
•不需要 worktree

Step 3: 確認修復（AFTER）

情況 A — Fix 已在 staging： Step 2 的截圖就是 AFTER，確認 bug 不存在即可。

情況 B — Fix 在本地 branch：

bash

# 切到 fix branch，啟動 local server
git checkout fix/issue-{N}-*
cd frontend && npm run dev &
cd ../backend && python -m uvicorn app.main:app --port 8000 &

然後用 MCP Chrome 打開 http://localhost:3000，重複 Step 2 的操作步驟。

Step 4: 存檔截圖到 Branch Evidence Folder

截圖必須存到 feature branch 的 evidence folder（不是 /tmp，不是 staging branch）。這樣截圖有 GitHub URL，可以顯示在 issue comment 裡。

bash

# 確保在 feature branch 上（不要在 staging/main）
BRANCH=$(git branch --show-current)
if [ "$BRANCH" = "staging" ] || [ "$BRANCH" = "main" ]; then
  git checkout -b evidence/issue-{N}
  BRANCH="evidence/issue-{N}"
fi

# 直接存到 repo 的 evidence folder
EVIDENCE_DIR=".claude/evidence/issue-{N}"
mkdir -p "$EVIDENCE_DIR"

截圖方式（三選一，依情況）：

A. MCP Chrome 截圖（推薦，最快）： MCP Chrome computer(action: "screenshot") 截圖後，用戶在對話中可見。同時用 Playwright CLI 存一份到 evidence folder：

bash

# Playwright CLI 一行截圖（不需要寫 .spec.ts）
npx playwright screenshot --browser chromium \
  "https://staging-url/room/xxx" \
  "$EVIDENCE_DIR/02-after.png"

B. 需要登入後截圖（Playwright CLI 無法自動登入時）：

bash

node -e "
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('STAGING_URL/login');
  await page.fill('#email', 'demo.counselor@example.com');
  await page.fill('#password', 'demo123');
  await page.click('button[type=\"submit\"]');
  await page.waitForURL('**/dashboard**');
  // navigate to bug page...
  await page.screenshot({ path: '.claude/evidence/issue-{N}/02-after.png', fullPage: true });
  await browser.close();
})();
"

C. 純 MCP Chrome（如果 Playwright 環境沒裝）：用 MCP Chrome 截圖，在 issue comment 中文字描述截圖內容。不是最佳方案，但總比沒截圖好。

Step 4b: 截圖驗證（MANDATORY — 不可跳過）

每張截圖存檔後，必須用 Read tool 打開確認內容：

code

# 用 Read tool 打開截圖（Claude 是 multimodal，可以看圖）
Read(.claude/evidence/issue-{N}/01-before.png)
Read(.claude/evidence/issue-{N}/02-after.png)

驗證清單：

• 截圖顯示的是目標頁面（不是登入頁、loading spinner、空白頁）
• 截圖內容與 bug 相關（能看到問題區域）
• BEFORE 截圖能看到 bug 存在的證據
• AFTER 截圖能看到 bug 已修復的證據
• 如果 staging 已修復 → 去 production 截 BEFORE

HARD STOP: 如果截圖是 loading screen / 登入頁 / 空白頁 → 刪除重截，不可提交垃圾截圖。

Playwright CLI 注意事項：

•npx playwright screenshot 無法處理需要登入的頁面 → 會截到「檢查認證狀態...」
•需要登入的頁面必須用方式 B（Playwright login script）或方式 C（MCP Chrome）
•截完一律用 Read tool 確認內容

Step 5: Push + 完整記錄到 GitHub Issue

bash

REPO="Youngger9765/career-creator"
BRANCH=$(git branch --show-current)

# Commit + push evidence（在 feature branch 上，不影響 staging）
git add .claude/evidence/issue-{N}/
git commit -m "evidence(#${N}): add quick-verify screenshots"
git push origin "$BRANCH"

Issue Comment 必須包含完整過程（不是只貼結論）：

bash

gh issue comment {N} --body "$(cat <<'COMMENT_EOF'
## Quick Verify — Issue #{N}

### 1. 重現過程
- **環境**：staging / localhost:3000
- **操作步驟**：
  1. 登入 demo.counselor@example.com
  2. 進入房間 → 選擇 [遊戲名稱]
  3. [具體操作...]
- **觀察結果**：[描述看到什麼]

#### BEFORE 截圖
![before](https://raw.githubusercontent.com/REPO/BRANCH/.claude/evidence/issue-{N}/01-before.png)
<!-- 如果 fix 已在 staging 則寫：fix 已部署，bug 無法重現（已修復），無 BEFORE -->

### 2. 根因分析
- **為什麼出錯**：[簡述根因]
- **相關檔案**：`path/to/file.ts:line`
- **影響範圍**：[哪些功能受影響]

### 3. 修復內容
- **PR**：#XX（或「尚未修復」）
- **改了什麼**：[一句話描述修改]
- **Branch**：`fix/issue-{N}-xxx`

### 4. 驗證結果
- **驗證環境**：staging（URL: xxx）/ localhost:3000
- **驗證方式**：MCP Chrome / Playwright
- **結果**：Bug 已修復 ✅ / Bug 仍存在 ❌ / 無法重現 ⚠️

#### AFTER 截圖
![after](https://raw.githubusercontent.com/REPO/BRANCH/.claude/evidence/issue-{N}/02-after.png)

### 5. 結論
- [ ] Bug 確認修復，可關閉（待用戶確認）
- [ ] Bug 仍存在，需進一步調查
- [ ] 非 Bug（QA 文檔 / spec 問題）
- [ ] 無法重現，標記 cannot-reproduce
COMMENT_EOF
)"

重點：

•evidence 存在 feature branch（如 evidence/issue-{N} 或 fix/issue-{N}-*），不會汙染 staging
•GitHub raw URL 只要 branch 存在就能顯示圖片
•Comment 模板中的 REPO、BRANCH、{N} 需替換為實際值
•即使是「非 Bug」或「無法重現」，也必須記錄完整過程

Decision: 需要進一步驗證嗎？

完成 quick-verify 後，判斷是否需要跑 frontend-bug-verification（Worktree + Playwright）：

情況	需要 Phase 2？
Fix 在 staging，MCP Chrome 確認修復	❌ 不需要
簡單視覺 bug（數量、顏色、文字）	❌ 不需要
需要 BEFORE/AFTER 並排比對	✅ 需要
需要雙瀏覽器同步測試	✅ 需要
Fix 還沒部署，需要 localhost 驗證	✅ 需要
用戶要求 worktree mode	✅ 需要

如果不需要 Phase 2 → 回報用戶，結束。如果需要 → 告知用戶，建議跑 /frontend-bug-verification {N}。

Lessons Learned

•Issue #14 反省：花 10 分鐘讀 code，用戶 30 秒看到 bug。先開瀏覽器。
•Issue #15：MCP Chrome 一看就知道不是 bug（QA 文檔寫錯）。
•Issue #17：PR 已 merged，MCP Chrome 看 staging 數卡片就好，不需要 14 步。
•Issue #25：如果先用 MCP Chrome 看，立刻發現無法重現，不會做 speculative fix。