代碼審查 Skill

⛔ 原則：不是「勾清單」，是「逐行質疑」。最嚴苛標準，分數可為負。

使用時機

• 任務標記完成前
• PR 合併前
• 用戶要求 review 時

評分標準（可為負分，嚴苛版）

預設扣分制，沒證據證明沒問題就扣分。

基礎分：100 分，逐項扣分，無下限

…（省略中間內容，保持原有 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 |

分數等級

Step 1：理解意圖

對每個函數/API，回答：

如果答不出來，先讀需求文件。

Step 2：追蹤資料流

輸入來源 → [這段代碼] → 輸出去向
    ↓              ↓           ↓
 可能的值？    如何轉換？    誰使用？

檢查：

• 輸入可能是 null/undefined 嗎？
• 輸入可能是空陣列嗎？
• 輸入可能超出預期範圍嗎？

Step 3：質疑假設

列出所有隱式假設，逐一驗證：

Step 4：模擬極端

4.1 邊界值

4.2 併發

兩個請求同時呼叫，會發生什麼？

4.3 中途失敗

執行到第 N 行失敗，系統狀態會壞掉嗎？

Step 5：名稱 vs 實作對照

拆解函數名稱，逐一驗證：

任何 ❌ 直接 -30 分。

Step 6：檢查可維護性

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
• ❌ 不給分數
• ❌ 分數虛高（沒證據就給高分）
• ❌ 用「應該沒問題」當結論
• ❌ 只報告部分問題