repo-code-review

name	repo-code-review
description	對指定的程式碼檔案或目錄進行審查，找出潛在的錯誤、提出重構建議。當使用者要 review code、找 bug、提出 refactor 建議時使用。

程式碼審查 (Code Review) 工作流程

本技能旨在標準化程式碼審查的流程，確保全面且一致地評估程式碼品質。

何時使用此技能

• 使用者要求審查程式碼（「請幫我 review 這個檔案」）
• 使用者尋求潛在的 bug 和問題（「這段程式碼有什麼問題嗎？」）
• 使用者要求重構建議（「這個函式可以怎麼改進？」）
• 使用者想了解程式碼的品質和最佳實踐遵循情況

工具需求

• filesystem.read: 讀取程式碼檔案內容
• filesystem.list: 列出目錄中的檔案
• filesystem.grep: 快速掃描特定的程式碼模式（可選）
• filesystem.patch: 生成修改建議（需要先徵求使用者同意）

審查工作流程

步驟 1: 確認審查範圍

使用 filesystem.list 或 filesystem.read 工具，確認使用者指定的路徑是單一檔案還是目錄。

檢查清單:

• 確認路徑存在且可讀取
• 如果是目錄，列出所有程式碼檔案（.py, .js, .ts, .go, .java, .cpp 等）
• 與使用者確認審查的具體範圍和優先級

步驟 2: 靜態分析與通用問題掃描

使用 filesystem.grep 工具，對目標檔案進行快速掃描，尋找已知的程式碼壞味道 (code smells)：

掃描清單:

• TODO: 或 FIXME: 註解（未完成的工作）
• pass 關鍵字（空的實作）
• 被棄用的函式呼叫
• 過於複雜的函式（過多的 if/else 或 for 迴圈）
• 重複的程式碼段落
• 過長的函式或類別（超過 200 行）

步驟 3: 深入分析業務邏輯與程式碼結構

仔細閱讀程式碼，從以下幾個角度進行分析：

可讀性審查:

• 變數和函式命名是否清晰且遵循命名慣例？
• 程式碼是否有適當的註解和文件字串？
• 程式碼結構是否邏輯清晰、易於理解？
• 是否有過度複雜的表達式可以簡化？

效率與效能審查:

• 是否有明顯的效能瓶頸？
• 是否有不必要的重複計算或迴圈？
• 資料結構的選擇是否合適？
• 是否有可以優化的演算法？

錯誤處理與健壯性審查:

• 是否有妥善處理潛在的例外情況？
• 是否有檢查輸入參數的有效性？
• 是否有適當的日誌記錄和除錯資訊？
• 邊界條件是否被正確處理？

安全性審查:

• 是否有潛在的安全漏洞（如 SQL 注入、跨站腳本等）？
• 敏感資訊（密碼、API 金鑰）是否被正確保護？
• 是否有適當的輸入驗證和清理？
• 權限檢查是否完整？

最佳實踐審查:

• 程式碼是否遵循專案的編碼風格指南？
• 是否使用了適當的設計模式？
• 是否有單元測試覆蓋？
• 是否遵循 DRY（Don't Repeat Yourself）原則？

步驟 4: 撰寫審查報告

將所有發現的問題和建議，整理成一份清晰的報告。每一條建議都必須包含明確的檔案路徑和行號，方便使用者定位。

報告格式範例:

# 程式碼審查報告

## 檔案: `src/utils/helpers.py`

### 🔴 關鍵問題 (Critical)
- **[行 42]**: 此處的 `try...except` 區塊捕捉了所有例外 (`except Exception:`)，但沒有記錄錯誤日誌，可能導致問題難以追蹤。
  - **建議**: 使用 `logging.exception()` 記錄詳細的錯誤資訊。

### 🟡 建議改進 (Suggestions)
- **[行 25]**: 變數 `d` 的命名不清晰，建議改為 `user_data` 以增加可讀性。
- **[行 58-65]**: 這段程式碼可以提取為一個獨立的函式 `validate_email()`，以提高可重用性。

### 🟢 優點 (Strengths)
- 程式碼結構清晰，註解充分。
- 適當的錯誤處理和邊界檢查。

## 總體評分
- 可讀性: ⭐⭐⭐⭐
- 效能: ⭐⭐⭐
- 安全性: ⭐⭐⭐⭐
- 可維護性: ⭐⭐⭐⭐

步驟 5 (可選): 生成修改建議

如果使用者在審查後請求修改建議，你可以根據分析結果，生成一個 diff 或 patch 格式的文字區塊。

重要: 不要直接呼叫 filesystem.patch 工具。你應先將 patch 內容以文字形式提供給使用者，並明確詢問「您是否同意套用以上修改？」，在獲得使用者明確許可後，才能執行寫入操作。

Patch 格式範例:

--- a/src/utils/helpers.py
+++ b/src/utils/helpers.py
@@ -22,7 +22,7 @@
 
 def process_data(raw_data):
-    d = json.loads(raw_data)
+    user_data = json.loads(raw_data)
     # 處理資料...
     return result

最佳實踐

1. 保持客觀和建設性: 審查應該是為了改進程式碼品質，而不是批評開發者。
2. 優先級排序: 將問題分為關鍵、重要和建議，幫助開發者優先處理。
3. 提供具體建議: 不要只指出問題，還要提供改進的方案。
4. 考慮上下文: 理解程式碼的業務背景和約束條件，避免不切實際的建議。
5. 一致性: 確保審查標準在所有檔案中保持一致。

常見的程式碼問題清單

• 未處理的例外情況
• 硬編碼的值（應使用常數或設定）
• 過長的函式或類別
• 缺乏單元測試
• 不清晰的變數命名
• 重複的程式碼
• 過度複雜的邏輯
• 缺乏文件和註解
• 不適當的資料結構選擇
• 潛在的安全漏洞