2025 iThome 鐵人賽

DAY 28

Software Development

AI 驅動的 Code Review：MCP 與 n8n 自動化實踐系列第 28 篇

[Day 28] AI Code Review 實戰:Prompt 從理論到實踐之路

17th鐵人賽

tom_yukuan

2025-10-02 00:00:50

48 瀏覽

分享至

[Day 28] AI Code Review 實戰:Prompt 從理論到實踐之路

前言

你是否遇過這樣的困擾:

AI Code Review 總是把所有問題都標記為「高風險」?
忽略真正重要的問題,卻對命名風格斤斤計較?

在 Day 27 中,我們學習了官方的 Prompt 最佳實踐。今天,我將分享如何將這些理論應用到實際的 AI Code Review 場景,從最初版本的「每個檔案都是 High」,逐步優化到能精準識別問題等級的 Prompt。

初版 Prompt 的三大問題

在優化前,我的 Prompt 面臨以下問題:

問題 1: 等級失準 - 全部都是 High

現象: AI 將所有問題都標記為高風險,失去篩選意義

原因: 缺少明確的等級定義與判斷標準

當每個檔案都被標記為 high 時,團隊成員無法分辨哪些問題需要立即處理,哪些可以排入待辦清單。這導致真正的安全漏洞淹沒在一堆命名建議中。

問題 2: 輸出格式不穩定

現象: 有時輸出 Markdown,有時輸出 JSON,還夾雜說明文字

原因: 沒有強制規範輸出格式的邊界

自動化流程需要穩定的 JSON 結構,但 AI 經常在 JSON 前後加上「以下是分析結果」、「希望這些建議有幫助」等額外文字,導致解析失敗。

問題 3: 過度關注小問題

現象: 在命名、註解等細節上花太多篇幅,忽略關鍵邏輯問題

原因: 缺少「先重後輕」的評估流程設計

AI 容易被表面問題吸引,例如花三行說明變數命名不符合慣例,卻一筆帶過未處理的 nil 指標問題。

優化策略:如何應用官方 Best Practice

基於官方文件的建議,我設計了四大優化策略:

策略 1: 角色與任務定義

官方原則: 給予 AI 明確的角色與上下文

我的實踐:

請你扮演一位資深軟體工程師,針對程式碼進行全面性的 Code Review。

💡 設計考量:

不用「你是一個 AI 助手」這種泛泛角色
用「資深軟體工程師」建立專業視角
強調「全面性」確保不遺漏檢查項目

策略 2: 結構化評估流程

官方原則: 使用 step-by-step 思考提升推理品質

我的實踐:

在評估每個檔案時,請遵循以下結構化步驟:
1. 先逐個面向分析問題,並列出證據
2. 綜合所有問題,決定 severity 等級
3. 只在有明確證據時提升 severity,避免過度評估

💡 設計考量:

先分析再判斷: 避免 AI 直覺式評級
要求列出證據: 提高判斷的可追溯性
強調「明確證據」: 對抗過度評估的傾向

流程視覺化:

┌─────────────┐
│  輸入程式碼  │
└──────┬──────┘
       │
       ▼
┌─────────────────────┐
│ 步驟1:逐項分析      │
│ ✅邏輯 🧹慣例 🔒安全│
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ 步驟2:綜合判斷      │
│ 評估整體嚴重程度    │
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ 步驟3:輸出結果      │
│ JSON格式 + 繁中註解 │
└─────────────────────┘

策略 3: 等級定義與範例

官方原則: 使用具體範例校準 AI 的判斷標準

我的實踐 - 五大評估面向:

1. ✅ 程式邏輯是否正確、是否有潛在錯誤或邊界條件未處理
2. 🧹 是否符合的慣用寫法,例如錯誤處理、命名風格、簡潔性
3. 🔒 是否有安全性問題,例如硬編碼、未處理的錯誤、資源洩漏等
4. 🚀 是否有效能瓶頸,例如不必要的記憶體分配、重複運算、goroutine 使用不當
5. 📚 是否具備良好的可讀性與可維護性,包括註解、結構清晰度、模組化程度

我的實踐 - Severity 等級定義:

severity 等級的詳細定義(必須嚴格遵守):

- high(高風險): 問題可能導致系統崩潰、安全漏洞、資料洩漏、嚴重效能衰退,
  或在生產環境造成重大損失。
  例如:未處理的 nil 指標、SQL 注入風險、無限迴圈。

- medium(中風險): 問題可能引起偶發錯誤、非最佳實踐,但不立即危險。
  例如:未優化的迴圈、缺少錯誤檢查、輕微資源浪費。

- low(低風險): 小問題,如命名不一致、缺少註解、多餘空白,但不影響功能或效能。

- no problem(無問題): 不用輸出到 JSON,所有面向皆符合最佳實踐,無任何可改進點
  或者單元測試的 error 寫底線也是可以,放到 no problem
  例如: req, _ := http.NewRequest("GET", "/ping", nil)

💡 設計考量:

每個等級都給出「後果」+「範例」
用「必須嚴格遵守」強化約束力
特別說明 no problem 不輸出,減少雜訊

我的實踐 - 正反面範例:

無問題案例:

func add(a, b int) int { 
    return a + b 
} // 簡單加法,無問題

分析:

邏輯正確、無錯誤
慣用寫法符合
無安全問題
效能佳
可讀性高

結論: severity: no problem(不輸出到 JSON)

高風險案例:

func connectDB() { 
    db, _ = sql.Open("mysql", "user:pass@tcp(host)/db") 
} // 硬編碼密碼

分析:

邏輯正確,但存在嚴重安全問題(硬編碼憑證)
其他面向 OK

結論: severity: high(高風險,因為安全漏洞)

輸出:

{
  "issues_found": ["硬編碼憑證"],
  "comment": "檔案中存在硬編碼資料庫憑證的安全漏洞,建議使用環境變數或秘密管理工具。"
}

策略 4: 嚴格輸出格式

官方原則: 使用 XML 標籤或 JSON schema 約束輸出

我的實踐:

你的回覆必須嚴格遵守以下結構,且不得包含標題與 JSON 塊以外的任何文字:

1. 先輸出標題:GitLab Discussion Request
2. 然後立即輸出以 ```json 包裹的 JSON

JSON 格式規範:
- 每個檔案最多一個討論
- 討論行對應該檔案的第一個變更行
- comment 必須包含該檔案所有重要問題的綜合評論,使用繁體中文
- issues_found 為陣列,每項為短字串描述主要問題,不可用段落文字
- severity 分為四個等級:high、medium、low、no problem
- 只在 JSON 回應中輸出 severity 為 high、medium、low 的檔案
- 如果檔案評估為 no problem,則不要在 gitlab_discussions 陣列中包含該檔案

JSON Schema 定義:

{
  "gitlab_discussions": [
    {
      "file_path": "<檔案完整路徑>",
      "comment": "<針對整個檔案的重要問題綜合評論,繁體中文>",
      "severity": "high|medium|low",
      "issues_found": ["短字串描述主要問題"],
      "position": {
        "base_sha": "<base sha>",
        "head_sha": "<head commit sha>",
        "start_sha": "<start commit sha>",
        "position_type": "text",
        "new_path": "<檔案完整路徑>",
        "old_path": "<檔案完整路徑>",
        "new_line": null or 數字,
        "old_line": null or 數字
      }
    }
  ]
}

💡 設計考量:

用「不得包含...以外的任何文字」強制邊界
明確每個欄位的型態與限制
用「必須」、「不可」等強硬用詞
重複強調「只輸出有問題的檔案」

實戰技巧與注意事項

💡 技巧 1: 如果 AI 仍然過度評級

可以嘗試:

在範例中加入更多 "no problem" 案例
在 severity 定義前加上「必須嚴格遵守」、「這是最重要的規則」
在系統提示中加入「寧可漏報也不要誤報」的原則

💡 技巧 2: 如果輸出格式仍不穩定

可以嘗試:

用三個連續的「不得」強調:「不得包含...」、「不得添加...」、「不得輸出...」
在 Prompt 最後重複一次格式要求
使用 JSON schema 驗證,解析失敗時重新生成

💡 技巧 3: 如果 comment 太籠統

可以嘗試:

要求「必須包含行號」
要求「必須給出具體改善方案」
提供好的 comment 範例

⚠️ 注意事項

不同語言需要調整評估標準
- Go: 強調 goroutine 洩漏、channel 誤用
- JavaScript: 強調 async/await、promise 處理
- Python: 強調 GIL、記憶體管理
團隊風格需要客製化
- 有些團隊接受底線忽略錯誤 _, err := ...
- 有些團隊要求所有錯誤必須處理
- 需要在 Prompt 中明確團隊慣例
定期檢視與調整
- 每兩週檢視誤判案例
- 將常見誤判加入反面範例
- 持續優化 severity 定義