當 AI 代理（AI agent）開始幫團隊改檔、跑測試、開拉取請求（pull request，PR），程式碼審查（code review）的第一個任務會變成「這個 PR 能不能進入人工審查」。審查者不必一開始就逐行看差異（diff）；先用任務、範圍、測試與風險把 PR 分流，才能避免把時間花在方向錯誤的修改上。
這篇給正在導入 Codex、GitHub Copilot、Claude Code、Cursor 或其他 AI 程式代理（AI coding agent）的工程團隊。讀完後，你可以把 AI PR 分成三種處理：證據完整就進人工審查；任務偏掉或測試不足就退回 agent 重做；碰到權限、付款、資料庫、資安或合約行為，就升級給程式碼擁有者或資安審查者。
先用 10 分鐘分流 AI PR
AI PR 的風險常出現在合併前很早的位置：任務理解錯、改太多檔案、測試只跑表面、或為了讓流程通過而放寬限制。先做分流，可以避免審查者被大量程式細節拖住。
| 看到的訊號 | 處理路線 | 審查者要做的事 |
|---|---|---|
| 任務來源清楚、差異範圍合理、測試證據完整、沒有高風險檔案 | 進人工審查 | 照一般 code review 看設計、可讀性、邊界案例與團隊慣例。 |
| PR 說明很空、改到不相關檔案、測試只寫「passed」、驗收條件沒有對應修改 | 退回 agent 或提交者重做 | 要求補上信任摘要、縮小範圍、重跑相關測試，必要時重開較小 PR。 |
| 觸及身分驗證、權限、付款、帳務、資料庫遷移、密鑰、外部網路、部署設定 | 升級擁有者或資安審查 | 指派程式碼擁有者（code owner）、資安或平台負責人，要求明確批准、回滾方案與稽核紀錄。 |
如果 10 分鐘分流都無法判斷，先補可審查的上下文：issue、驗收條件、測試命令與風險說明。上下文補齊後，再進入逐行審查。
五層 AI PR 審查流程
把 AI PR 當成一個可驗收的交付包；它包含檔案差異，也包含任務、測試、風險與責任紀錄。建議從外到內檢查：任務、差異、測試、安全、維護。
| 層級 | 要確認的問題 | 通過標準 |
|---|---|---|
| 任務對齊 | PR 是否直接解決原始 issue？驗收條件有沒有逐項對應？ | PR 說明能說清楚需求、非目標修改與未完成項目。 |
| 差異範圍 | 修改檔案是否必要？是否混入格式化、重構或無關命名？ | 每個檔案都有理由；大範圍變更被拆小或有擁有者同意。 |
| 測試證據 | 跑了哪些測試、格式檢查（lint）與型別檢查（type check）？新測試能否抓到原本 bug？ | 測試命令、結果、未跑原因與失敗處理都寫在 PR 內。 |
| 安全權限 | 是否放寬權限、驗證、輸入處理、網路或檔案存取？ | 高風險邏輯有資深審查者；沒有把安全檢查改成可選。 |
| 維護責任 | 是否符合既有架構、命名、錯誤處理與除錯方式？ | 修改後的程式碼仍能由團隊維護，未來回滾與追蹤不會變困難。 |
這個順序有一個好處：前兩層失敗時，後面不用浪費時間逐行評論。任務與範圍先穩住，測試和安全才有意義。
任務對齊：先比對 issue、計畫與差異
AI agent 會根據 prompt、程式碼庫（repository）脈絡、錯誤訊息與測試結果推理。它可能做出可執行的修改，卻解錯需求或擴大範圍。
審查者可以先問四件事：
- 原始 issue 或 ticket 的驗收條件是什麼？
- PR 說明是否逐項說明哪些條件已完成？
- 差異是否只碰必要檔案？
- 有沒有順手重構、改格式、改命名或修改測試期待值？
常見退回訊號包括：把 bug 修成另一個抽象層問題、將整個檔案格式化、增加大型 helper、改掉 public API、或把失敗測試改成通過。遇到這些情況，請要求 agent 重新提交較小的修改，並在 prompt 中明確列出禁止範圍。
差異範圍：把檔案分成三種風險
AI PR 最容易讓審查者疲勞的地方，是差異量突然變大。大 PR 仍可能合理，但要有清楚理由。
| 檔案類型 | 範例 | 審查方式 |
|---|---|---|
| 預期內檔案 | 這次 bug、功能或測試直接相關的程式與測試檔 | 正常審查，確認邏輯、邊界案例與可讀性。 |
| 可疑檔案 | 格式化、共用輔助函式（helper）、看似順手調整的相鄰模組 | 要求說明為何需要改；理由不足就退回或拆 PR。 |
| 高風險檔案 | 權限、付款、資料庫遷移（migration）、部署、密鑰（secret）、稽核、資料結構（schema）、外部網路 | 指派程式碼擁有者（code owner）；要求測試、回滾、批准紀錄與安全檢查。 |
如果 PR 混入太多可疑檔案，先不要逐行留言。請提交者把無關格式化、重構與功能修改拆開，讓審查成本回到可控範圍。
測試證據：不要只看「測試通過」
AI 工具很會在 PR 說明寫「tests passed」。審查者要看的是哪些測試、為何足夠、哪些沒有跑。
最低測試證據應包含：
- 已執行命令與結果摘要。
- 這些命令如何對應本次變更。
- 新增或修改的測試，以及它會在 bug 存在時失敗的理由。
- 未執行測試與原因，例如環境限制、外部服務、時間成本。
- 失敗測試如何處理；若略過，誰批准。
修 bug 時，先看有沒有能重現 bug 的測試；做新功能時，先看驗收條件是否都有對應測試。若 AI 只跑單一路徑（happy path）、用 mock 避開核心行為、刪掉不穩定測試（flaky test）卻沒有理由，這個 PR 需要退回補測試證據。
安全與權限：找出「為了通過而放寬」的改動
AI PR 的安全問題常藏在看似方便的修補裡。它可能把檢查改成可選、吞掉錯誤、放寬允許清單（allowlist）、拉長逾時時間（timeout），或把使用者輸入推近命令列（shell）、SQL、HTML、URL、檔案路徑（file path）。
高風險審查請特別看：
- 身分驗證（authentication）、授權（authorization）、權限（permission）或角色檢查（role check）是否被改動。
- 付款（payment）、帳務（billing）、配額（quota）或稽核紀錄（audit log）是否被繞過或弱化。
- 密鑰（secret）是否出現在程式、log、測試 fixture 或 PR 討論中。
- 新增依賴、外部網路、檔案系統權限或命令執行是否必要。
- 輸入驗證（validation）、清理（sanitization）、速率限制（rate limit）、CORS、CSRF 或內容安全政策（content security policy）是否變寬。
- 資料庫遷移（migration）、資料結構（schema）或資料修復腳本是否有備份、回滾與人工批准。
Claude Code 的安全文件提醒，使用者仍要審查建議的程式與命令，並為批准動作負責。這個原則也適用於其他代理：工具可以先找風險，批准權要留在團隊流程裡。若團隊要把權限、沙盒與稽核一起設計，可以延伸看 AI Agent 安全新共識。
要求每個 AI PR 附上信任摘要
把下面這段放進 PR 範本（template），或要求 agent 在開 PR 前填好。目標是讓審查者快速知道 AI 做過什麼、沒有做什麼、哪裡需要人工判斷。
## AI PR 信任摘要
### 任務來源
- issue / ticket：
- 目標：
- 驗收條件：
- 明確不處理的範圍：
### 修改範圍
- 修改檔案：
- 檢查過但未修改的檔案：
- 可能影響的 API / schema / 設定：
- 高風險區域：
### 測試證據
- 已執行命令：
- 新增或修改測試：
- 未執行測試與原因：
- 需要審查者手動驗證的情境：
### 風險與限制
- 主要假設：
- 需要程式碼擁有者或資安審查者確認：
- 回滾方式：
- 後續追蹤項目：信任摘要的價值，是把 agent 的行為軌跡轉成可審查證據，讓審查者不必從差異裡逆向猜測每一步原因。
Copilot、Codex、Claude Code 在審查裡各自適合做什麼
工具審查可以當第二雙眼睛，但不要讓工具取代批准人。比較穩的做法，是把它們放在不同位置：
| 工具 / 機制 | 適合放的位置 | 團隊仍要補的判斷 |
|---|---|---|
| GitHub Copilot 程式碼審查（code review） | GitHub PR、整合開發環境（IDE）或支援環境中的自動/手動審查；可搭配全庫或特定路徑的自訂指令 | 它能提出回饋與建議修改（suggested changes），但團隊要決定哪些建議符合產品、架構與風險承擔。 |
| OpenAI Codex 的 GitHub 程式碼審查（code review） | 在 PR 留 @codex review 或設定自動審查，要求它聚焦嚴重問題、測試缺口或安全路徑 | Codex 審查是高訊號檢查層；合併前仍要看 issue、測試證據與擁有者批准。 |
| Claude Code 權限與沙盒設定 | 本機或雲端執行修改前，限制可讀寫路徑、命令與工具權限 | 權限設定能減少越界操作；使用者仍需審核提議命令與產出差異。 |
| PR 範本 / CODEOWNERS / 持續整合（CI） | 把人工責任、測試與高風險路徑固定在流程裡 | 這些規則要由團隊維護，並定期更新 agent 指令與檢查清單。 |
GitHub 官方文件說明，Copilot code review 可以審 PR 並提供可套用的建議修改。OpenAI Codex 文件則把 GitHub code review 定位為會檢查 PR 差異（pull request diff）、遵循程式碼庫指引（repo guidance）、發出標準 GitHub review 的流程。這些能力很適合用來補審查者的盲點，但請把「可合併」的決定留給負責該系統的人。
團隊流程：從 issue 到合併的 7 步
如果團隊已經有 AI 程式代理（AI coding agent），建議把 code review 往前移，不要等 PR 開出來才補上下文。
- Issue 先寫驗收條件與禁止範圍：包含不該碰的檔案、必跑測試、高風險功能、回滾要求。
- 要求 agent 先提出計畫：列出預計修改檔案、測試策略與風險；人類先批准計畫再讓它改。
- 讓 agent 小步提交：能拆成兩個 PR 就拆；重構、格式化、功能修改分開。
- PR 說明必填信任摘要：缺任務、測試或風險說明時，不進人工審查。
- 持續整合（CI）與靜態檢查先跑完：格式檢查（lint）、型別檢查（type check）、單元測試（unit test）、安全掃描、結構檢查（schema check）依專案需要設定。
- 工具審查補第二輪：Copilot、Codex 或其他工具聚焦測試缺口、安全路徑與可維護性。
- 人類擁有者做最後批准：確認業務行為、架構取捨、高風險檔案與回滾方式。
這套流程不會讓每個 PR 變慢。相反地，它會讓不合格的 AI PR 更早退回，讓審查者把時間留給值得合併的修改。
一個可直接套用的情境
假設團隊要修客服後台的訂單狀態 bug，AI agent 開了一個 PR。審查者可以這樣處理：
- 讀者情境：產品工程師負責後台訂單頁，最近讓 Codex 或 Claude Code 協助修 bug。
- 交給 AI 的任務：只修正狀態轉換錯誤，禁止修改付款流程、權限判斷與資料庫 schema。
- 預期輸出：小範圍 diff、能重現 bug 的測試、PR 信任摘要、未碰高風險檔案的說明。
- 驗證方式：跑訂單狀態單元測試（unit test）、相關整合測試，手動確認兩個邊界狀態；檢查身分驗證、付款與帳務檔案沒有差異。
- 風險與非適合情況：如果 agent 改到付款、權限或資料庫遷移，這已超出普通 bugfix PR，應升級擁有者審查並要求拆分。
這種情境的價值，是把 AI 限制在可驗收任務裡。任務越清楚，審查者越能分辨是程式細節需要修，還是整個 PR 方向需要退回。
AI PR 審查清單（Review Checklist）
任務與範圍
- PR 是否直接對應 issue / ticket？
- 驗收條件是否逐項對應程式或測試？
- PR 是否明確說明不處理的範圍？
- 有沒有無關重構、格式化或命名調整？
- 是否需要拆成更小 PR？
差異與架構
- 每個修改檔案是否都有理由？
- 是否改到公開程式介面（public API）、資料結構（schema）、設定檔（config）、資料庫遷移（migration）或部署設定？
- 是否新增依賴、工具權限、外部服務或網路存取？
- 是否符合既有命名、錯誤處理與模組邊界？
- 回滾方式是否清楚？
測試與驗證
- 是否有重現 bug 或覆蓋驗收條件的測試？
- 是否跑過相關測試、格式檢查（lint）、型別檢查（type check）或安全掃描？
- 未跑測試的原因是否可信？
- 新測試是否測使用者可觀察行為，而非只看實作細節（implementation detail）？
- 失敗測試或 flaky test 是否被清楚處理？
安全與資料
- 是否放寬身分驗證、授權、權限或角色檢查？
- 是否碰到密鑰（secret）、權杖（token）、憑證、log 或稽核軌跡（audit trail）？
- 是否降低輸入驗證、清理、速率限制或其他輸入限制？
- 是否讓使用者輸入更接近命令列（shell）、SQL、HTML、URL 或檔案路徑（file path）？
- 是否需要資安審查者或法規/隱私負責人確認？
合併前決策
- PR 是否有足夠信任摘要？
- 工具審查提出的高風險建議是否已處理或明確拒絕？
- 程式碼擁有者是否批准高風險檔案？
- 產品行為、監控、回滾與後續追蹤是否清楚？
- 若明天需要解釋這個合併，PR 內是否有足夠紀錄？
與 Mason 其他 AI coding 文章怎麼搭配
如果團隊還在建立完整流程，可以照這個順序讀：
- 想把任務從需求一路接到 PR：看 AI Coding Agent 工作流實戰。
- 想寫更穩的 agent 指令：看 AI Coding Agent Prompt 模板。
- 想設定 Copilot review 與 AGENTS.md：看 GitHub Copilot code review 指南。
- 想比較 Codex、Claude Code、Antigravity 的適用任務：看 Claude Code vs Codex vs Antigravity。
- 想做企業級評估：看 企業導入 AI coding agent 評估清單。
AI PR 的好處是交付速度變快；代價是審查者要更早要求證據、界定權限、留下責任紀錄。把信任摘要、五層檢查與升級規則固定下來，AI 程式代理（AI coding agent）才會變成團隊生產力，並降低新的漏審風險。
資料來源
- GitHub Docs：About GitHub Copilot code review
- GitHub Docs：Using GitHub Copilot code review
- GitHub Docs：Using custom instructions to unlock the power of Copilot code review
- OpenAI Developers：Codex code review in GitHub
- OpenAI Developers：Codex workflows
- Claude Code Docs：Security
- arXiv：AIDev：Studying AI Coding Agents on GitHub
- arXiv：Comparing AI Coding Agents：A Task-Stratified Analysis of Pull Request Acceptance