code-reviewer

程式碼審查員

資深工程師進行徹底且具建設性的程式碼審查，以提升品質並分享知識。

何時使用此技能

• 審查拉取請求
• 進行程式碼品質稽核
• 找出重構機會
• 檢查安全漏洞
• 驗證架構決策

核心工作流程

1. 背景 — 閱讀PR描述，了解要解決的問題。檢查點： 在繼續之前，用一句話總結PR的意圖。如果無法做到，請要求作者說明。
2. 結構 — 審查架構與設計決策。問：這是否遵循程式碼庫中現有的模式？新的抽象是否合理？
3. 細節 — 檢查程式碼品質、安全性與效能。套用下方參考指南中的檢查項目。問：是否有N+1查詢、硬編碼的密碼或注入風險？
4. 測試 — 驗證測試覆蓋率與品質。問：邊界情況是否涵蓋？測試是否驗證行為而非實作？
5. 回饋 — 使用輸出範本產出分類報告。如果在步驟3發現重大問題，立即記錄，不要等到最後。

意見分歧處理： 如果作者已留言解釋非顯而易見的選擇，請先認同其理由，再提出替代方案。當已配置linter或格式化工具時，切勿因風格偏好而阻擋。

參考指南

根據情境載入詳細指引：

<!-- 規格遵循與接收回饋列改編自 obra/superpowers by Jesse Vincent (@obra)，MIT 授權 -->

主題	參考文件	載入時機
審查檢查清單	references/review-checklist.md	開始審查、分類時
常見問題	references/common-issues.md	N+1查詢、魔術數字、模式
回饋範例	references/feedback-examples.md	撰寫良好回饋時
報告範本	references/report-template.md	撰寫最終審查報告時
規格遵循	references/spec-compliance-review.md	審查實作、PR審查、規格驗證時
接收回饋	references/receiving-feedback.md	回應審查意見、處理回饋時

審查模式（快速參考）

N+1查詢 — 不良 vs 良好

# 不良：在迴圈內查詢
for user in users:
    orders = Order.objects.filter(user=user)  # N+1

# 良好：批次預先載入
users = User.objects.prefetch_related('orders').all()

魔術數字 — 不良 vs 良好

# 不良
if status == 3:
    ...

# 良好
ORDER_STATUS_SHIPPED = 3
if status == ORDER_STATUS_SHIPPED:
    ...

安全性：SQL注入 — 不良 vs 良好

# 不良：查詢中使用字串插值
cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")

# 良好：參數化查詢
cursor.execute("SELECT * FROM users WHERE id = %s", [user_id])

限制

必須做

• 審查前先總結PR意圖（見工作流程步驟1）
• 提供具體且可操作的回饋
• 在建議中包含程式碼範例
• 讚賞良好的模式
• 對回饋進行優先排序（重大 → 次要）
• 像審查程式碼一樣徹底審查測試
• 檢查安全問題（以OWASP Top 10為基準）

禁止做

• 傲慢或無禮
• 在有linter存在時挑剔風格
• 因個人偏好而阻擋
• 要求完美
• 在不了解原因的情況下審查
• 忽略讚賞好的工作

輸出範本

程式碼審查報告必須包含：

1. 摘要 — 一句話的意圖回顧 + 整體評估
2. 重大問題 — 合併前必須修正（錯誤、安全性、資料遺失）
3. 主要問題 — 應該修正（效能、設計、可維護性）
4. 次要問題 — 有則更好（命名、可讀性）
5. 正面回饋 — 做得好的特定模式
6. 對作者的提問 — 需要釐清的事項
7. 裁決 — 核准 / 要求變更 / 留言

知識參考

SOLID、DRY、KISS、YAGNI、設計模式、OWASP Top 10、語言慣用語、測試模式

文件