Code Reviewer

本 skill 提供一個系統化的方法來進行 Code Review。 重點在於 審查流程 與 品質維度，而非特定技術的模式。

範疇

使用此 skill 來：

• 使用結構化流程進行系統性的 Code Review
• 從多個維度評估程式碼 (正確性、安全性、可維護性)
• 提供清晰、可行的建議，給出建設性回饋
• 根據品質標準決定是否準備好批准 (Approve)

不適用於

• 特定技術的模式 (請參考對應的 Jutsu plugins)
• 詳細的實作指導 (請參考特定領域的 agents)

審查流程概觀

Phase 1: 審查前準備

開始 review 前，先收集上下文

1. 理解變更內容:

   # 審查 diff
   git diff <base-branch>...HEAD
   
   # 檢查變更範圍
   git diff --stat <base-branch>...HEAD
   

2. 識別相關上下文:

   # 在程式碼庫中尋找類似的模式
   grep -r "similar_pattern" .
   

3. 驗證業務背景:

   • 是否有相關的 issue/ticket？審查需求。
   • 影響到哪個領域 (domain)？
   • 對使用者有什麼影響？

Phase 2: 系統性審查

從以下維度進行審查

1. 正確性 (Correctness)

• 它是否解決了所述的問題？
• 商業邏輯是否符合領域規則？
• 邊界情況 (edge cases) 是否被妥善處理？
• 測試是否驗證了預期行為？

如何檢查正確性

• 先閱讀測試，以理解預期行為。
• 追蹤變更中的程式碼路徑。
• 驗證錯誤情境是否被涵蓋。
• 與需求交叉比對。

2. 安全性 (Safety)

• 是否遵循了授權/認證模式？
• API 或契約 (contracts) 是否有破壞性變更 (breaking changes)？
• 是否可能洩漏敏感資料？
• 資料操作是否安全？
• 是否存在潛在的競爭條件 (race conditions) 或資料完整性問題？

如何檢查安全性

• 驗證操作的存取控制。
• 對 API 變更執行相容性檢查。
• 檢查是否有適當的輸入驗證。
• 審查交易 (transaction) 的邊界。
• 驗證輸入的淨化 (sanitization)。

3. 可維護性 (Maintainability)

• 是否遵循了現有的程式碼庫模式？
• 程式碼是否可讀且易於理解？
• 複雜的部分是否有文件記錄？
• 是否遵循了童子軍原則 (Boy Scout Rule)？ (讓程式碼比你發現時更好)
• 命名是否清晰且一致？

如何檢查可維護性

• 與程式碼庫中的類似程式碼進行比較。
• 驗證複雜邏輯的文件。
• 檢查是否有魔法數字 (magic numbers) 和寫死的數值。
• 確保命名慣例一致。
• 尋找被註解掉的程式碼 (anti-pattern)。

4. 可測試性 (Testability)

• 新功能是否有測試？
• 測試是否涵蓋了邊界情況和錯誤情境？
• 測試是否清晰且可維護？
• 測試資料的設定是否適當？

如何檢查可測試性

• 審查變更程式碼的測試覆蓋率。
• 驗證 happy path 和 sad path 都被測試到。
• 確保測試是確定性的 (deterministic) 且清晰的。
• 檢查測試隔離是否做得妥當。

5. 效能 (Performance)

• 是否有明顯的效能問題？
• 資料庫查詢是否有效率？
• 高成本的操作是否已適當優化？
• 資源是否被妥善管理？

如何檢查效能

• 識別 N+1 query 模式。
• 檢查查詢是否缺少索引。
• 審查資源的分配與清理。
• 驗證是否使用了適當的資料結構。

6. 標準遵循 (Standards Compliance)

• 是否遵循了特定語言的最佳實踐？
• 是否通過了所有的驗證檢查？
• 是否有 linting 或型別錯誤？
• 是否遵循了約定的編碼標準？

如何檢查標準遵循

• 執行驗證套件。
• 檢查是否違反標準模式。
• 驗證沒有繞過品質閘門 (quality gates)。

7. 程式碼風格 (Coding Style)

若有發現 makefile skill，則檢查是否有程式碼風格驗證的 target，若有則執行，並驗證 git status 是否為 clean。

Phase 3: 信心度評分

對所有發現的問題進行信心度評分

每個發現的問題都必須包含一個 信心度分數 (0-100)，用以表示你對此問題為真實問題的確定程度：

關鍵過濾規則：只回報 信心度 ≥80% 的問題。較低信心度的發現會製造噪音，應予以省略。

信心度評分指南

高信心度 (90-100) – 回報這些：

• 驗證失敗 (linting, tests, types)
• 安全漏洞 (SQL injection, XSS, auth bypass)
• 有明確重現步驟的正確性 bug
• 破壞性的 API 變更
• 違反已文件化的團隊標準

中高信心度 (80-89) – 回報這些：

• 新功能缺少測試
• 錯誤處理的缺口
• 效能問題 (N+1 queries, missing indexes)
• 有清晰模式可循的可維護性問題
• 違反童子軍原則

中度信心度 (60-79) – 不要回報：

• 沒有明確程式碼庫先例的風格偏好
• 推測性的效能擔憂
• 沒有明顯好處的替代方案

低信心度 (<60) – 不要回報：

• 個人意見
• 沒有具體影響的「可以更好」建議
• 沒有證據的理論性邊界情況

偽陽性過濾 (False Positive Filtering)

關鍵：應用以下過濾器以避免回報非問題的項目：

不要回報：

• ❌ 此變更未引入的既有問題 (檢查 git blame)
• ❌ 已由 linters/formatters 處理的問題
• ❌ 程式碼中有明確的 lint-ignore 註解 (尊重開發者的決定)
• ❌ 沒有文件化標準的風格偏好
• ❌ 沒有證據或重現方式的理論性 bug
• ❌ 沒有明確好處的「可以使用…」建議
• ❌ 不影響品質的吹毛求疵 (nitpicks)

回報前需驗證：

• ✅ 執行 git diff 確認問題在變更的行內
• ✅ 檢查自動化工具是否已捕捉此問題
• ✅ 對照已文件化的專案標準 (CLAUDE.md, CONTRIBUTING.md 等)
• ✅ 確認問題確實影響到正確性、安全性或可維護性

偽陽性 vs. 真實問題範例：

❌ 偽陽性：「這個函式可以使用 TypeScript generics 以獲得更好的型別安全」(信心度：60%，風格偏好，無文件化標準)

✅ 真實問題：「services/payment.ts:42 的 processPayment 函式在沒有交易保護的情況下執行資料庫操作，若操作中途出錯，可能導致資料不一致。」(信心度：90%，違反文件化模式，有明確影響)

Phase 4: 回饋與決策

提供結構化回饋

1. 總結: 高層次的評估
2. 優點: 做得好的地方 (正面強化)
3. 問題: 按嚴重性組織，並附上 信心度分數：
   • 嚴重 (Critical) (信心度 ≥90): 阻擋批准 (安全性、正確性、破壞性變更)
   • 重要 (Important) (信心度 ≥80): 應該解決 (可維護性、最佳實踐)
4. 可行的下一步: 附上 file:line 參考的具體變更建議
5. 決策: 批准 (Approve)、請求變更 (Request Changes) 或需要討論 (Needs Discussion)

注意：建議/錦上添花的項目被刻意省略。只專注於高信心度、可行的回饋。

批准標準

✅ 何時批准 (Approve)

• 所有驗證檢查都通過 (linting, tests, types, etc.)
• 商業邏輯正確且完整
• 遵循了安全性與授權模式
• 沒有破壞性變更 (或已妥善協調)
• 程式碼遵循現有模式
• 複雜邏輯有清晰的文件
• 測試涵蓋了 happy path、邊界情況和錯誤情境
• 變更符合需求
• 程式碼可維護且清晰
• 應用了童子軍原則 (程式碼被改善，而非劣化)

🔄 何時請求變更 (Request Changes)

• 嚴重問題：安全漏洞、正確性 bug、破壞性變更
• 重要問題：違反模式、缺少測試、程式碼不清晰
• 驗證失敗未被解決
• 商業邏輯與需求不符
• 錯誤處理不足

💬 何時需要討論 (Needs Discussion)

• 架構上的考量
• 需求不清晰
• 需要權衡取捨的決策
• 偏離模式需要合理解釋
• 效能影響不確定

常見的 Review 陷阱

Reviewer 經常忽略

1. 授權繞過: 操作沒有適當的存取控制
2. 破壞性變更: 未檢查相容性
3. 錯誤處理缺口: 只 review happy path
4. 測試品質: 測試存在，但未實際測試邊界情況
5. 領域邏輯錯誤: 未理解商業規則
6. 被註解掉的程式碼: 留下無用程式碼而非移除
7. 魔法數字: 未命名的不明常數
8. 過於聰明的程式碼: 明明簡單可行卻寫得複雜
9. 違反童子軍原則: 讓程式碼變得更糟，而非更好

紅燈 (絕不批准)

以下情況永遠需要修改

• ❌ 被註解掉的程式碼 → 移除它 (git 會保留歷史)
• ❌ 程式碼中的秘密或憑證 → 使用安全的設定方式
• ❌ 沒有相容性驗證的破壞性變更
• ❌ 被註解掉或跳過的測試 → 修復程式碼，而非測試
• ❌ 被忽略的驗證失敗 → 必須全部通過
• ❌ 新功能沒有測試 → 測試是必要的
• ❌ 寫死的商業邏輯 → 應為可設定的
• ❌ 缺少錯誤處理 → 必須處理邊界情況
• ❌ 明顯的安全漏洞 → 必須立即修復

與開發工作流程的整合

Code Review 適用於 Phase 2: 實作

實作 → 驗證套件 → Code Review → 批准 → 合併 (Merge)
(自動化檢查)   (此 skill)      (人工)

Review 在驗證之後進行

1. 開發者執行驗證套件
2. 所有自動化檢查必須通過
3. 應用 Code Review skill 進行品質評估
4. 識別並修復問題
5. 修復後重新驗證
6. 人工 review 並批准合併

Review 不能替代驗證。 兩者都是必要的。

輸出格式

將 review 回饋結構化如下

Review 總結

對變更及其品質的簡要整體評估。

優點

• ✅ 做得好的地方 (正面強化)
• ✅ 遵循了好的模式
• ✅ 特別好的實作

問題

注意：只回報信心度 ≥80% 的問題。所有發現都包含信心度分數。

🔴 嚴重 (阻擋批准)

[問題標題] – file/path.ts:42 – 信心度: 95%

• 問題: 清晰描述問題所在
• 影響: 為何此問題嚴重 (安全性、正確性、破壞性變更)
• 修復: 具體可行的步驟

🟡 重要 (應解決)

[問題標題] – file/path.ts:89 – 信心度: 85%

• 問題: 描述可維護性/品質問題
• 影響: 這如何影響程式碼品質
• 建議: 推薦的改善方法

驗證狀態

• 所有自動化檢查已通過
• API 相容性已驗證 (如適用)
• 測試已涵蓋邊界情況
• 文件已更新

決策

[批准 / 請求變更 / 需要討論]

下一步行動

1. 附上 file:line 參考的具體可行步驟
2. 需重新執行的驗證指令
3. 可參考的模式

建設性回饋原則

提供回饋時

1. 具體: 指出確切的行數，而非模糊的區域
2. 解釋原因: 不只說「這樣是錯的」，要解釋其影響
3. 提供方向: 建議方法或模式
4. 平衡批評與讚美: 指出做得好的地方
5. 劃分問題優先級: 嚴重 vs. 重要 vs. 建議
6. 尊重: 程式碼不是人
7. 假設對方有能力: 提出問題，而非指責
8. 教導，而非僅是糾正: 幫助開發者成長

建設性回饋範例

✅ 好: 「在 services/payment_service:45，沒有交易保護的付款處理可能在操作中途出錯時導致資料不一致。請將操作包在一個 transaction 中以確保原子性。可以參考資料庫設計中的 ACID 原則。」

❌ 不好: 「這裡要用 transaction。」

品質哲學

Code Review 確保

• 正確性: 解決了實際問題
• 安全性: 保護資料並遵循安全模式
• 可維護性: 未來的開發者可以理解和修改
• 一致性: 遵循既定模式
• 品質: 達到標準

記住

• Review 是關於程式碼品質，而非個人批評
• 目標是改善程式碼和開發者技能
• 在徹底與務實之間取得平衡
• 完美不是標準；達到品質門檻的「足夠好」即可
• 童子軍原則：讓程式碼比你發現時更好

與現有 Skills 的整合

可搭配使用

• makefile: 了解 Makefile 的使用方法