代碼審查 Skill
⛔ 原則：不是「勾清單」，是「逐行質疑」。最嚴苛標準，分數可為負。
使用時機
- 任務標記完成前
- PR 合併前
- 用戶要求 review 時
評分標準（可為負分，嚴苛版）
預設扣分制，沒證據證明沒問題就扣分。
基礎分：100 分，逐項扣分，無下限
| 類別 | 扣分項目 | 扣分 |
|---|---|---|
| 基礎檢查失敗 | ||
| typecheck 失敗（每個錯誤） | -20 | |
| lint 錯誤（每個錯誤） | -10 | |
| lint 警告（每個警告） | -5 | |
| 測試失敗（每個失敗） | -30 | |
使用 any（每處） | -15 | |
使用 @ts-ignore（每處） | -20 | |
使用 as unknown as（每處） | -15 | |
| 生存測試失敗 | ||
| Log 無上下文 | -10 | |
| 敏感資料洩漏 (Log) | -50 | |
| N+1 查詢 | -30 | |
| 多步驟寫入無 Transaction | -40 | |
| 巢狀深度 > 3 | -10 | |
| 沒引用需求文件證明意圖 | -20 | |
| 架構違規 | ||
| UI 直接呼叫 DB (Logic in UI) | -30 | |
| 繞過 Service Layer | -30 | |
| God Function (職責不清) | -20 | |
| 測試品質差 | ||
| 測試實作細節而非行為 | -20 | |
| Mock 濫用 (沒測到東西) | -20 | |
| 斷言無效 (e.g. expect(true).toBe(true)) | -20 | |
| 反模式 (Anti-Patterns) | ||
| 殭屍代碼 (註解掉的代碼塊) | -10 | |
| 過度設計 (YAGNI) | -10 | |
| 重複造輪子 (未使用現有 helper) | -10 | |
| 致命缺陷 | ||
| 安全漏洞（SQL注入、XSS） | -50 |
...（省略中間內容，保持原有 Step 7）...
7.4 惡魔辯護（Anti-Laziness）
- 攻擊測試：只要能想到一種讓這段代碼崩潰的方法，就必須提出。
- 證據強制：必須引用需求文件的具體段落證明代碼意圖，沒引用扣 20 分。
Step 8：架構與反模式檢查（Architecture Guardrails）
防止代碼腐爛，從源頭擋住爛設計：
8.1 架構防護
- Logic/UI 分離：
- ❌ 在 .tsx 中直接寫 SQL/Supabase query -> 扣 30 分 - ✅ 必須封裝在 src/services/ 或 api/
- 分層原則：
- ❌ 前端跳過 BFF/API 直接打資料庫（除非特定 RLS 場景） -> 扣 30 分 - ❌ God Function（一個函數做驗證+DB+通知+計算） -> 扣 20 分（應拆分）
8.2 測試品質審計（Test Semantic Audit）
- 有效測試：
- ❌ expect(true).toBe(true) 或只測 toBeDefined() -> 扣 20 分 - ❌ 測試充滿 mock，根本沒測到邏輯 -> 扣 20 分
- 行為驗證：
- ❌ 測試實作細節（如 toHaveBeenCalledWith 內部私有函數） -> 扣 20 分
8.3 拒絕反模式（Anti-Patterns）
- 殭屍代碼 (Zombie Code)：
- ❌ 提交包含大段被註解掉的代碼 -> 扣 10 分
- 重複造輪子：
- ❌ 專案已有 formatDate 卻自己重寫 -> 扣 10 分
- 過度設計 (YAGNI)：
- ❌ 寫了「未來可能會用到」但現在沒用的參數/函數 -> 扣 10 分
審查報告格式（必須輸出）
| | 硬編碼密鑰/Token | -50 | | | 資料遺失風險（事務不完整） | -40 | | | 競態條件 | -40 | | | 函數名稱與實作不符 | -30 | | 嚴重缺陷 | | | | | 未處理 Supabase/API error | -20 | | | 邊界值未處理（null/undefined） | -15 | | | 空陣列未處理 | -15 | | | 隱式假設未驗證 | -15 | | 中等缺陷 | | | | | 錯誤訊息顯示技術細節給用戶 | -10 | | | 缺少 console.error 日誌 | -10 | | | 魔術數字未抽成常數 | -5 | | | 函數超過 50 行 | -5 | | | 複雜邏輯無註解 | -5 | | 輕微缺陷 | | | | | 命名不清楚 | -3 | | | 可抽成 helper 但沒抽 | -3 | | | 未使用的 import/變數 | -2 |
分數等級
| 分數 | 等級 | 結論 |
|---|---|---|
| 90-100 | 🟢 優秀 | 可合併 |
| 80-89 | 🟡 良好 | 修正後可合併 |
| 60-79 | 🟠 需改進 | 必須修正 |
| 0-59 | 🔴 不合格 | 重寫 |
| <0 | ⛔ 災難 | 拒絕，需嚴肅檢討 |
Step 1：理解意圖
對每個函數/API，回答：
| 問題 | 你的答案 |
|---|---|
| 這段代碼要解決什麼問題？ | |
| 對應工單的哪個需求？ | |
| 它在系統中扮演什麼角色？ |
如果答不出來，先讀需求文件。
Step 2：追蹤資料流
輸入來源 → [這段代碼] → 輸出去向
↓ ↓ ↓
可能的值？ 如何轉換？ 誰使用？檢查：
- 輸入可能是 null/undefined 嗎？
- 輸入可能是空陣列嗎？
- 輸入可能超出預期範圍嗎？
Step 3：質疑假設
列出所有隱式假設，逐一驗證：
| 假設 | 成立嗎？ | 不成立會怎樣？ |
|---|---|---|
| 資料庫一定成功回應 | ||
| 陣列一定有元素 | ||
| 用戶一定已登入 | ||
| ID 一定存在 |
Step 4：模擬極端
4.1 邊界值
| 輸入 | 預期 | 實際 | 有處理？ |
|---|---|---|---|
| null | ✅/❌ | ||
| undefined | ✅/❌ | ||
| "" | ✅/❌ | ||
| [] | ✅/❌ | ||
| 負數 | ✅/❌ |
4.2 併發
兩個請求同時呼叫，會發生什麼？4.3 中途失敗
執行到第 N 行失敗，系統狀態會壞掉嗎？Step 5：名稱 vs 實作對照
拆解函數名稱，逐一驗證：
| 名稱片段 | 承諾 | 實作有做到？ |
|---|---|---|
| ✅/❌ | ||
| ✅/❌ | ||
| ✅/❌ |
任何 ❌ 直接 -30 分。
Step 6：檢查可維護性
| 問題 | 答案 |
|---|---|
| 六個月後有人看得懂嗎？ | |
| 有沒有魔術數字需要抽成常數？ | |
| 有沒有複雜邏輯需要加註解？ | |
| 改動這裡會影響哪些地方？ | |
| 有沒有重複代碼可以抽成 helper？ |
Step 7：生產環境生存測試（Survival Test）
用最嚴苛的標準檢視這段代碼在生產環境的表現：
7.1 可觀測性（Observability）
- Log 有上下文嗎？
- ❌ console.error('Failed') -> 扣 10 分 - ✅ console.error('Failed', {caseId, error})
- 敏感資料洩漏？
- ❌ console.log(userObject) -> 扣 50 分 - ❌ 印出 password / token / secret -> 扣 50 分
7.2 事務完整性（Data Integrity）
- 多步驟寫入有用 Transaction 嗎？
- ❌ await A; await B; (中間失敗資料會不一致) -> 扣 40 分 - ✅ 使用 Supabase RPC 或單一原子操作
7.3 效能地雷
- N+1 查詢？
- ❌ items.map(async item => await db.get(item.id)) -> 扣 30 分 - ✅ db.in('id', ids)
- 複雜度炸彈？
- ❌ 巢狀深度 > 3 層 (if {for {if {...}}}) -> 扣 10 分
7.4 惡魔辯護（Anti-Laziness）
- 攻擊測試：只要能想到一種讓這段代碼崩潰的方法，就必須提出。
- 證據強制：必須引用需求文件的具體段落證明代碼意圖，沒引用扣 20 分。
審查報告格式（必須輸出）
# 代碼審查報告
## 評分：XX/100 🟢/🟡/🟠/🔴/⛔
## 審查檔案
- `path/to/file.ts`
## 基礎檢查
- typecheck: ✅/❌ (X 錯誤)
- lint: ✅/❌ (X 錯誤, X 警告)
- test: ✅/❌ (X 失敗)
- any 使用: X 處
- @ts-ignore: X 處
## 扣分明細
| 扣分 | 原因 | 位置 |
| -------- | -------- | ---- |
| -XX | [原因] | L123 |
| -XX | [原因] | L456 |
| **總計** | **-XXX** | |
## 問題清單
### ⛔ 致命
1. ...
### 嚴重
1. ...
### 🟡 建議
1. ...
## 結論
[能不能合併，為什麼]執行原則
- ✅ 必須跑完全部流程，即使基礎檢查失敗
- ✅ 必須列出所有問題，不可遺漏
- ✅ 必須給出總分，讓用戶知道這次實作幾分
- ✅ 問題列在對話框，不要亂改或新增檔案
- ✅ 每一步驟都要在對話框上即時呈現，不可隱瞞
- ✅ Agent 連審核都偷懶幫我記在第一行：若未遵守上述原則，必須在報告開頭自我揭露。
🛑 強制暫停機制 (Mandatory Checkpoints)
為了確保審查品質，Agent 必須在以下階段結束時呼叫 notify_user 暫停執行，等待用戶確認：
Checkpoint A：基礎檢查結束後
- 動作：回報基礎檢查（Lint/Test/Typecheck）的執行結果與目前扣分。
- 目的：讓用戶決定在基礎設施不穩定的情況下，是否仍要進行深度審查。
Checkpoint B：邏輯與假設分析後 (Step 4 結束)
- 動作：回報 Step 1~4 的分析結果（意圖、假設、邊界模擬）。
- 目的：確認 Agent 對代碼意圖的理解正確，糾正錯誤的假設。
Checkpoint C：發現致命問題時 (FATAL Trigger)
- 條件：這是一次性的觸發。只要審查過程中發現任何 -50 分 的項目（如 SQL 注入、個資洩漏）。
- 動作：立即暫停，不用等到最後。
- 目的：致命錯誤可能導致後續審查無意義，優先修復。
禁止事項
- ❌ 沒跑基礎檢查就開始審查
- ❌ 發現問題但略過不報告
- ❌ 跳過任何 Step
- ❌ 不給分數
- ❌ 分數虛高（沒證據就給高分）
- ❌ 用「應該沒問題」當結論
- ❌ 只報告部分問題