RFC: PR Review 評分制改革 — 告別過度嚴格的 Agent Review

[the3mi]

現況問題：PR #191 的真實案例

Before（目前的問題）

PR #191 feat: add interactive setup command

一個 feature，最後累積了：

• chaodu-agent 發了 4 輪 review
• 總共 ~20 個問題（含大量 NIT / cosmetic）
• PR AUTHOR 一直更新、一直刷新 comment thread

核心症狀

症狀	說明
Comment 碎片化	4 個 separate threads，author 要不斷刷新
Blocking vs Non-Blocking 沒有分開	trailing comma、box drawing 常數都占一個 comment
Reviewer 在內部討論	working_dir 拆成 Option A/B/C 來回 3 層
數量當 KPI	20 個問題，但真正的 blocking 只有 2-3 個
NIT 占用 comment	cosmetic 問題 block 了 PR merge

---

建議改革方向

1. Prompt 改革 — 基於 Google Code Review Guide

採用 Google 官方 11 個維度，review 時只專注：

維度	Priority	評分
Design	🔴 High	1-10
Functionality	🔴 High	1-10
Complexity	🔴 High	1-10
Tests	🔴 High	1-10
Consistency	🟡 Medium	1-10
Documentation	🟡 Medium	1-10
Style / Naming / Comments	🟢 NIT only	不評分，統一用 "Nit:" 標記

核心原則：

• Blocking 上限 3 個，超過 → 拆成 follow-up PR
• 一個 PR 只留 1 個 review comment，一次看完統一回
• NIT 全寫在一起，不 block merge
• 分數 ≥ 7 + blocking < 3 → 建議 merge

2. Threshold 共識

✅ >= 7 分 + blocking <= 3 → 建議 Merge
⚠️ 5-6 分 或 blocking > 3 → 修完再 merge
❌ < 5 分 → 需大改

---

預期效果（After）

同一個 PR #191，新的 Review 會變成：

## PR Review Report
**Overall Score: 7.5/10 → ✅ 建議 Merge（修完 blocking）**

### 🔴 Blocking（2個）
1. TOML injection 風險 — 用 toml crate serialize 取代字串替換
2. working_dir 對 claude/codex agent 會指向錯誤目錄

### 🟡 Non-Blocking（統一一次）
- 建議加 --output flag 支援自訂路徑（nice to have）

### 🟢 Nits（不 block merge）
- Nit: trailing comma
- Nit: box drawing 用常數取代 hardcoded string

---

下一步

• 團隊確認這 2 個改革方向
• 將新的 Review Prompt 落地到各 Agent 的 system prompt
• 建立 threshold 共識並文件化

---

參考：Google Code Review Guide — https://google.github.io/eng-practices/review/reviewer/looking-for.html

[github-actions]

⚠️ Could not detect an issue template. Please make sure this issue was created using one of the available templates and that the corresponding label (bug, feature, documentation, guidance) is present.

Available templates: Bug Report, Feature Request, Documentation, Guidance