tomevault-io Code Reviewer
本 skill 提供一個系統化的方法來進行 Code Review。 重點在於 審查流程 與 品質維度，而非特定技術的模式。
範疇
使用此 skill 來：
- 使用結構化流程進行系統性的 Code Review
- 從多個維度評估程式碼 (正確性、安全性、可維護性)
- 提供清晰、可行的建議，給出建設性回饋
- 根據品質標準決定是否準備好批准 (Approve)
不適用於
- 特定技術的模式 (請參考對應的 Jutsu plugins)
- 詳細的實作指導 (請參考特定領域的 agents)
審查流程概觀
Phase 1: 審查前準備
開始 review 前，先收集上下文
理解變更內容:
# 審查 diff git diff <base-branch>...HEAD # 檢查變更範圍 git diff --stat <base-branch>...HEAD識別相關上下文:
# 在程式碼庫中尋找類似的模式 grep -r "similar_pattern" .驗證業務背景:
- 是否有相關的 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)，用以表示你對此問題為真實問題的確定程度：
| 分數 | 信心度等級 | 使用時機 |
|---|---|---|
| 100 | 絕對確定 | 客觀事實：linter 錯誤、型別錯誤、測試失敗、安全漏洞 |
| 90 | 非常高 | 明確違反已記載的標準、明顯的正確性 bug |
| 80 | 高 | 模式違規、缺少錯誤處理、可維護性問題 |
| 70 | 中度 | 需要更多上下文的潛在問題、可能的邊界情況 |
| 60 | 有些 | 有問題的模式、與程式碼庫先例有關的風格問題 |
| 50 | 不確定 | 沒有明確先例的潛在改進 |
| <50 | 低 | 推測性的擔憂、個人偏好 |
關鍵過濾規則：只回報 信心度 ≥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: 回饋與決策
提供結構化回饋
- 總結: 高層次的評估
- 優點: 做得好的地方 (正面強化)
- 問題: 按嚴重性組織，並附上 信心度分數：
- 嚴重 (Critical) (信心度 ≥90): 阻擋批准 (安全性、正確性、破壞性變更)
- 重要 (Important) (信心度 ≥80): 應該解決 (可維護性、最佳實踐)
- 可行的下一步: 附上
file:line參考的具體變更建議 - 決策: 批准 (Approve)、請求變更 (Request Changes) 或需要討論 (Needs Discussion)
注意：建議/錦上添花的項目被刻意省略。只專注於高信心度、可行的回饋。
批准標準
✅ 何時批准 (Approve)
- 所有驗證檢查都通過 (linting, tests, types, etc.)
- 商業邏輯正確且完整
- 遵循了安全性與授權模式
- 沒有破壞性變更 (或已妥善協調)
- 程式碼遵循現有模式
- 複雜邏輯有清晰的文件
- 測試涵蓋了 happy path、邊界情況和錯誤情境
- 變更符合需求
- 程式碼可維護且清晰
- 應用了童子軍原則 (程式碼被改善，而非劣化)
🔄 何時請求變更 (Request Changes)
- 嚴重問題：安全漏洞、正確性 bug、破壞性變更
- 重要問題：違反模式、缺少測試、程式碼不清晰
- 驗證失敗未被解決
- 商業邏輯與需求不符
- 錯誤處理不足
💬 何時需要討論 (Needs Discussion)
- 架構上的考量
- 需求不清晰
- 需要權衡取捨的決策
- 偏離模式需要合理解釋
- 效能影響不確定
常見的 Review 陷阱
Reviewer 經常忽略
- 授權繞過: 操作沒有適當的存取控制
- 破壞性變更: 未檢查相容性
- 錯誤處理缺口: 只 review happy path
- 測試品質: 測試存在，但未實際測試邊界情況
- 領域邏輯錯誤: 未理解商業規則
- 被註解掉的程式碼: 留下無用程式碼而非移除
- 魔法數字: 未命名的不明常數
- 過於聰明的程式碼: 明明簡單可行卻寫得複雜
- 違反童子軍原則: 讓程式碼變得更糟，而非更好
紅燈 (絕不批准)
以下情況永遠需要修改
- ❌ 被註解掉的程式碼 → 移除它 (git 會保留歷史)
- ❌ 程式碼中的秘密或憑證 → 使用安全的設定方式
- ❌ 沒有相容性驗證的破壞性變更
- ❌ 被註解掉或跳過的測試 → 修復程式碼，而非測試
- ❌ 被忽略的驗證失敗 → 必須全部通過
- ❌ 新功能沒有測試 → 測試是必要的
- ❌ 寫死的商業邏輯 → 應為可設定的
- ❌ 缺少錯誤處理 → 必須處理邊界情況
- ❌ 明顯的安全漏洞 → 必須立即修復
與開發工作流程的整合
Code Review 適用於 Phase 2: 實作
實作 → 驗證套件 → Code Review → 批准 → 合併 (Merge)
(自動化檢查) (此 skill) (人工)
Review 在驗證之後進行
- 開發者執行驗證套件
- 所有自動化檢查必須通過
- 應用 Code Review skill 進行品質評估
- 識別並修復問題
- 修復後重新驗證
- 人工 review 並批准合併
Review 不能替代驗證。 兩者都是必要的。
輸出格式
將 review 回饋結構化如下
Review 總結
對變更及其品質的簡要整體評估。
優點
- ✅ 做得好的地方 (正面強化)
- ✅ 遵循了好的模式
- ✅ 特別好的實作
問題
注意：只回報信心度 ≥80% 的問題。所有發現都包含信心度分數。
🔴 嚴重 (阻擋批准)
[問題標題] - file/path.ts:42 - 信心度: 95%
- 問題: 清晰描述問題所在
- 影響: 為何此問題嚴重 (安全性、正確性、破壞性變更)
- 修復: 具體可行的步驟
🟡 重要 (應解決)
[問題標題] - file/path.ts:89 - 信心度: 85%
- 問題: 描述可維護性/品質問題
- 影響: 這如何影響程式碼品質
- 建議: 推薦的改善方法
驗證狀態
- 所有自動化檢查已通過
- API 相容性已驗證 (如適用)
- 測試已涵蓋邊界情況
- 文件已更新
決策
[批准 / 請求變更 / 需要討論]
下一步行動
- 附上
file:line參考的具體可行步驟 - 需重新執行的驗證指令
- 可參考的模式
建設性回饋原則
提供回饋時
- 具體: 指出確切的行數，而非模糊的區域
- 解釋原因: 不只說「這樣是錯的」，要解釋其影響
- 提供方向: 建議方法或模式
- 平衡批評與讚美: 指出做得好的地方
- 劃分問題優先級: 嚴重 vs. 重要 vs. 建議
- 尊重: 程式碼不是人
- 假設對方有能力: 提出問題，而非指責
- 教導，而非僅是糾正: 幫助開發者成長
建設性回饋範例
✅ 好: 「在 services/payment_service:45，沒有交易保護的付款處理可能在操作中途出錯時導致資料不一致。請將操作包在一個 transaction 中以確保原子性。可以參考資料庫設計中的 ACID 原則。」
❌ 不好: 「這裡要用 transaction。」
品質哲學
Code Review 確保
- 正確性: 解決了實際問題
- 安全性: 保護資料並遵循安全模式
- 可維護性: 未來的開發者可以理解和修改
- 一致性: 遵循既定模式
- 品質: 達到標準
記住
- Review 是關於程式碼品質，而非個人批評
- 目標是改善程式碼和開發者技能
- 在徹底與務實之間取得平衡
- 完美不是標準；達到品質門檻的「足夠好」即可
- 童子軍原則：讓程式碼比你發現時更好
與現有 Skills 的整合
可搭配使用
makefile: 了解 Makefile 的使用方法
Converted and distributed by TomeVault — claim your Tome and manage your conversions.