代碼審查 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 處

扣分明細

問題清單

⛔ 致命

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

• ❌ 不給分數

• ❌ 分數虛高（沒證據就給高分）

• ❌ 用「應該沒問題」當結論

• ❌ 只報告部分問題