PR 三階段品質審查 Pipeline

用途

用三個 sub-agent 從設計、實作、可用性三個角度系統審查 PR，每一階段都輸出明確的 PASS / WARN / FAIL 結論，讓你在合併前有多道把關而不只是走馬看花。

何時用

• 適合：重要功能 PR、涉及 API 設計或資料模型改動、或在高風險系統（金流、資安、核心演算法）上做審查時。
• 不要用：小改動（修錯字、調整 log 訊息、更新版本號），三階段 pipeline 對這類 PR 是殺雞用牛刀，直接單次 review 即可。

Prompt

/ultrareview {{PR_URL}}

啟動三階段審查 pipeline，依序派出三個 reviewer，每個 reviewer 完成後輸出結論才繼續下一個：

**plan-reviewer（第一階段：設計層）**
審查：API 契約設計、資料模型一致性、架構決策是否合理、有無過度設計或設計不足
輸出：PASS / WARN / FAIL + 具體建議清單

**code-reviewer（第二階段：實作層）**
前提：plan-reviewer 達到 PASS 或 WARN 才繼續
審查：實作是否符合設計、程式可讀性、測試覆蓋率、coding style 一致性
輸出：PASS / WARN / FAIL + 具體建議清單

**verify-reviewer（第三階段：可用性層）**
前提：code-reviewer 達到 PASS 或 WARN 才繼續
審查：實際執行測試、edge case 處理、可觀測性（logging / metrics）、rollback 計畫
輸出：PASS / WARN / FAIL + 具體建議清單

最後輸出三階段彙整表：
| 階段 | 結論 | 關鍵風險 | 建議動作 |

範例 / 變體

• 填好變數：PR_URL 填 https://github.com/your-org/your-repo/pull/142。
• 變體（只跑設計層）：移除 code-reviewer 和 verify-reviewer，只保留 plan-reviewer，適合設計評審會議前的快速確認。
• 變體（指定審查重點）：在 plan-reviewer 後加「特別關注：這個 PR 改動了計費邏輯，請確認金額精度是否符合現有標準」，把高風險點明確交代給 AI。

🎯 範例輸出（實測）

在 Claude Code 跑這句、PR_URL 填「https://github.com/cloud-f1/invoice-api/pull/42」（一個新增 ECPay 發票 API 整合的 PR）的結果：

點開看 AI 實際輸出

plan-reviewer（第一階段：設計層）

WARN

具體建議：

• 新增的 POST /invoices endpoint 回傳 invoice_id 但沒有對應的 GET /invoices/{id} 查詢端點，客戶端無法確認開立結果，API 契約不完整
• InvoiceRequest schema 的 tax_type 欄位接受 int（1/2/3），建議改成 Enum 並暴露 OpenAPI 描述，降低呼叫方錯誤
• 發票開立是不可逆操作，缺少冪等鍵（idempotency key）設計，webhook 重試時可能重複開立

---

code-reviewer（第二階段：實作層）

前提：plan-reviewer 結論為 WARN，繼續執行。

WARN

具體建議：

• calc_invoice_tax() 有型別標注但缺少 docstring，遷移規格書裡的截斷行為說明沒有跟進程式碼
• sign_payload() 的金鑰從 os.environ 取，但沒有 startup 驗證，服務啟動時若 env var 缺失會等到第一次呼叫才爆，建議在 lifespan 裡做 early-fail 檢查
• 測試覆蓋率 64%（CI badge），CurrencyConverter 模組無任何測試

---

verify-reviewer（第三階段：可用性層）

前提：code-reviewer 結論為 WARN，繼續執行。

FAIL

具體建議：

• Edge case：invoice_amt = 0 未測試，目前程式碼會呼叫 ECPay API 開立 $0 發票（ECPay 回 error），需加入業務驗證層阻擋
• Logging 不足：成功開立只 log invoice_created，缺少 invoice_number（後續查詢需要），線上問題難以追蹤
• 無 rollback 計畫文件，若 ECPay API 連線超時，訂單狀態與發票狀態可能不一致

---

三階段彙整表：

階段	結論	關鍵風險	建議動作
設計層	WARN	缺冪等鍵設計	合併前補上冪等鍵文件
實作層	WARN	Startup 無 early-fail	本次 PR 修補
可用性層	FAIL	$0 發票未防護 + Log 不足	必須修復才能合併

💡 實測心得：verify-reviewer 的 FAIL 通常比 WARN 更有說服力——實測發現「$0 發票被直接送出去」這個 edge case 是 AI 在最後一階段才抓到的，靠一般 review 很容易漏掉。三階段 pipeline 的摩擦成本確實比單次 review 高，建議只用在金流、資安等高風險模組。

延伸

重點來了：三階段的最大價值不是審查得更嚴，而是把「設計問題」和「實作問題」分開抓——很多 PR 設計沒問題但實作有細節疏漏，或反過來設計根本方向錯了但程式碼寫得很漂亮。分開看才不會互相遮蔽。如果你的 PR review 流程裡還沒有獨立的設計層審查，這個 pipeline 是個很值得試試的起點。