Claude Code 團隊怎麼做 Code Review
開場
(untitled opening) · 副標副標先把問題丟出來：agent 寫 code 的量這麼大，review 要怎麼跟上？團隊的答案是，在覆蓋率和審查深度都夠了之後，改成追求「人花最少的 review 時間，而且回退和事故不能因此變多」。
"the minimum amount of human review time that doesn't raise reverts or incidents" 在不讓回退或事故變多的前提下，把人的 review 時間壓到最低。
背景數字：Claude Code 自己的 code 大約九成是 Claude 寫的。6 月到 9 月，合併的 PR 數量翻倍以上，需要 revert 的比例反而降了四成多。
作者強調 review 沒有被拿掉，是大部分的「讀 code」移給了機器。整套流程以人的時間為優化目標，並讓出問題時能輕鬆撤回。
重新想 review 的目的
Rethinking the purpose of code reviewagent 讓改動量暴增。Anthropic 的 monorepo 從 5 月每天約 2,500 個改動，到 9 月變成每天 3 萬以上。Claude Code 雖然有自己的 repo，壓力也差不多，一行一行人工看已經不可能。
作者把 review 拆成兩個工作：
- 在出貨前找到並修好問題。
- 讓團隊對 codebase 有共同的理解。
這篇主要談第一個，第二個留到後面的「共享脈絡」再講。
關鍵的觀念轉換是：「有沒有人讀過這段 code」只是個粗略的替代指標。真正該問的是這次改動可能出什麼錯，以及該由哪一道檢查（自動或人工）來抓。
"'did a human read the code?' is an imprecise proxy" 「有沒有人看過 code」只是一個不精確的替代指標。
review 因此從流程最後的一道關卡，變成寫的過程中就一直在跑的檢查，作者比喻成「邊寫邊跑的拼字檢查」。多數改動在人看到之前，Claude 已經審過也修過，人的注意力就能留給更高層的問題。
稀缺的是人的時間與注意力
The scarce resource: human time and attention人的注意力應該花在只有人能解決的問題上，而新穎的工作還多得很。
作者提醒，人的時間有兩塊：花在 review 的時間，和事後修爛 code 的時間。只砍前面那塊，成本會原封不動跑到後面那塊。
"Cutting the first doesn't help if the time just shows up in the second." 如果省下的時間只是跑到修 bug 那頭，砍 review 時間就沒有意義。
目標設定：大多數 PR 合併時最多只有一個人參與，那個人可以就是作者本人，而且回退和事故不能增加。
追蹤的指標：
- 每個 PR 需要幾個人 approve（看中位數和 p95）。
- 人留了幾則 comment。
- PR 卡在等人的時間。
回退率和事故率則當護欄。這兩個數字一往上走，就代表人的時間沒有真的省下來。
一個改動的旅程
The life of a change一個改動從作者的電腦出發，要經過好幾層 review 才會到使用者手上。
逐層拆解
Layer by layer最底下是快速回退，上面疊六層檢查。
1. 別人看之前，先自己驗過
The work is verified before anyone else looks現在大部分的 review 在 PR 還沒開之前就做了。Claude 會跑測試、build，或做截圖比對，並把輸出秀出來，不是只說一句「完成了」。接著另開一個乾淨 context 的 subagent 重看一次 diff。
工程師還會跑內部的 skill：抓 bug、精簡 diff、做端到端檢查。UI 改動會對照設計規範。文中引用 Boris Cherny 的看法：驗證「大概是最重要的事」。
reviewer 一再標出同一類問題時，就回到源頭去修，做法有三種：改 skill、加 lint 規則，或改指示檔。
CLAUDE.md：寫專案是什麼、慣例、什麼不做。要短，細節指向其他文件。REVIEW.md：由 code owner 寫。好的版本會：- 說明在這個區域「出錯」長什麼樣子。例如文件出錯就是內容說謊，設定出錯就是導錯路。
- 限制雞毛蒜皮建議的數量。
- 列出不用看的路徑。
- 要求附檔案和行號當證據，不能只憑名字猜。
2. 每個 PR 都跑 AI review
AI review on every pull request每個 PR 都由 Claude 審：把 diff 放回整個 repo 的脈絡，再對照 PR 說明裡寫的意圖。如果是修 bug，它會追是不是修到根因。這個功能已在 Team／Enterprise 方案正式提供，本機也能用 /code-review。
內部 PR 收到「有實質內容的 review comment」的比例，從 research preview 前的 16% 升到 54%。大 PR 通常會有 finding，小 PR 常常乾淨通過。管理員可以為每個 repo 選 Quick、Standard 或 Deep 三種深度。
運作方式：
- 多個 agent 同時找 bug。
- 另一組 agent 對每筆 finding 投票，確認是真的才留下。
- 只關於風格的 finding 直接丟掉。
留下來的照嚴重度排序，標成 Important、Nit 或 Pre-existing。最後一種代表原本就存在的問題，不會看起來像作者的錯。
"Every finding has to be answered." 每一筆 finding 都必須回應：要嘛修掉，要嘛附理由關掉。
3. 可以擋 merge 的安全 review
Security review that can block另外有一道獨立的自動安全 review。只要它的 finding 還開著，PR 就不能合併。之後的 commit 修掉問題，finding 會自動清掉。外部團隊可以用開源的 GitHub Action 或 /security-review 拿到同樣的能力。
4. 會擋 merge 的自動檢查
Automated checks that blocklint、型別檢查、各平台的測試、build。一個典型的 CLI PR 會跑幾十項檢查。PR 模板會問兩件事：這次怎麼測的？要怎麼回退？發起改動的人要簽名負責。
5. 人工簽核依風險分級
Human approval, scaled by risk不同改動風險不同，review 的力道也不同：
| 風險 | 例子 | 需要幾個人 approve |
|---|---|---|
| 低 | 文件、文案、內部功能、藏在 flag 後面的新增改動 | 自動檢查和安全檢查都綠了就不用人 |
| 中 | 一般產品改動；快取、自動更新、system prompt 這類敏感區 | 1 人 |
| 高 | 風險最高的 code，加上規定一定要兩人的路徑 | 2 人 |
分級規則：
- 級別由分類器依「改了什麼」決定，不看是誰改的。第二個分類器會判斷要不要額外拉一個人進來，有些路徑則永遠要人看。
- 只有受信任的作者能走輕量路徑。agent 的 approve 永遠不能算成人的 approve。
- 指揮 agent 做這個改動的人，算是必要的 reviewer 之一。
- approve 只對某一個 commit 有效，之後再推新的 commit 要重新簽。
6. Merge queue、feature flag、逐步釋出
Merge queue, flags and a gradual releasemerge queue 會把改動套到最新的 main 上，重跑一次檢查，避免「各自沒問題、合起來壞掉」的情況。新功能先藏在 flag 後面，只開給 Anthropic 員工。發版也是先到 latest 頻道，再到 stable。
7. 快速發現、快速回退
Fast detection, fast rollbackflag 不用重新部署就能關掉。團隊有每週輪替的值班。事故檢討時問的是「這個問題本來該被哪一層擋下來」。
作者也承認不足：發現問題目前還靠作者、值班和儀表板。當回退或事故數字變差時，自動把簽核收緊的斷路器還沒做。
文中引用一位同事的話：放慢速度確實會降低錯誤率，但主要只是因為什麼都做得比較少。團隊的選擇是：
"We'd rather get faster at noticing and fixing problems." 我們寧可在發現和修正問題上變得更快。
怎麼讓 reviewer 越來越好
How we make the reviewer betterreviewer 的品質靠一個持續的回饋迴圈提升。過去造成事故或被 revert 的 PR，經專家確認後收進評測集，reviewer 每天對這份題庫跑一次。
噪音怎麼量：
- 看作者怎麼處理每則 comment：修了、說它錯、說是故意的、說不相關。
- 拿已知乾淨的 PR 去跑 reviewer，看會不會亂報。
優先順序是先抓到真 bug，其次才是減少來回輪數。
"It's easy to catch more bugs if you don't mind flagging a lot of non-bugs." 如果不在乎誤報一堆不是 bug 的東西，要抓到更多 bug 很容易。
作者是 agent 的時候，噪音特別貴。人看到雞毛蒜皮的建議會直接略過，agent 會真的去改，於是多一個 commit、多一輪 review。
收斂問題：曾有一個 CLI 的 PR 一晚來回了五十多輪。用 git blame 一查，被標出來的 code 約 59% 在第一輪就已經在了。換句話說，後面幾輪大多只是陸續挖出舊 bug。
團隊原本預設每個 PR 跑很多輪，現在把「幾輪才通過」和抓到率（recall）一起追蹤。對策有四個：
- 輪數上限：超過三輪，reviewer 會請作者退一步，重新想做法。
- 前幾輪之後只看新的 diff。
- 點出整「類」bug，讓作者一次修完所有同類位置。
- 已經報過的不再重複報。
"Review has to converge." review 一定要能收斂。
review agent 也會每晚對既有的 code 跑一次。
| 指標 | 改善前 | 改善後 |
|---|---|---|
| 一輪 review 加修正就通過 | 65% | 78% |
| 要五輪以上 | 8.9% | 1.5% |
| 平均要幾次 review 才通過 | 2.08 | 1.32 |
人留在哪些環節
Where humans stay in the loop為了例行的小錯把資深工程師拉進來，成本遠高於自動 review。所以人的角色轉向需要判斷的事：
- 這東西到底該不該做：方向、品味、範圍。
- 高風險的 code：計費、自動更新、CI 設定。
- 之後會被別人照抄的架構。
- 判讀證據：測試輸出、跑過的指令、截圖、finding。要說得出這些檢查會漏掉什麼，說不出來就該要求真的 review，不要快速放行。
- 為結果負責。
"A person is accountable for every change that ships, whoever typed it." 不管是誰打的字，每個出貨的改動都有一個人要負責。
團隊怎麼共享脈絡
Sharing context across the team這裡回到 review 的第二個工作：散播理解。如果 diff 都交給機器讀，人就需要別的方式認識 codebase。
團隊沒有正式流程。工程師想了解某一塊，就請 Claude 針對那一小段 code 寫說明。花幾分鐘就好，而且反映的是 code 現在的樣子。有些人會請 Claude 做小型的視覺化網頁，照自己習慣的方式學一個模組。
作者認為這比讀一堆瑣碎的 diff 學得更多。另外，公開的 Slack 頻道讓大家看得到彼此在做什麼。
誰合進去，誰負責
"You land it, you own it"團隊的慣例：你合進去的東西壞了，通常由你來修，因為你最有脈絡。作者特別說明這不是究責：
"It isn't blame." 這不是在怪誰。
能這樣運作，是因為有幾個前提：
- 改動維持小。
- 一切都能撤回。
- 影響範圍決定要多嚴格。
- 回歸問題能很快浮現。
- 不究責的文化。
責任也透過公開頻道分擔，任何人都能接手一條討論或給意見。
需要轉向的時候
When we change directionagent 讓「開始做」變得很便宜，所以有些 PR 本來就不該合。這時隊友通常會問為什麼要這樣做，或建議更簡單的路。
關掉一個 PR 不會覺得可惜，因為 code 寫起來本來就快。不同的方向應該在討論串早期就提出，不要等 PR 都寫完了，才用擋 merge 的 comment 表達。
怎麼套用到你的團隊
How you can adopt this process作者說大部分元件現在就拿得到，並分四段給出檢查清單：
PR 之前
- 在簡短的
CLAUDE.md裡告訴 agent 有哪些檢查可以跑。 - 本機跑
/code-review和/security-review。 - 加一份
REVIEW.md。
每個 PR
- 必過的 CI，PR 模板要有「測試、風險、怎麼回退」三欄。
- 加 AI reviewer。
- 加安全 review，所有討論串解決才能合。
- review 力道配合風險，並限制輪數。
簽核
- 寫下依改動內容（不是依作者）分的風險等級。
- 輕量路徑只開給受信任的作者。
- 敏感路徑用 CODEOWNERS 和分支保護。
- 機器人的 approve 永遠不能取代必要的人工 approve。
合併與之後
- merge queue、feature flag、分階段釋出、一步回退。
- 把事故變成評測題。
- 量人的時間，並用回退和事故率當護欄。
接下來的方向
Where this is going對外推出的 Code Review 仍把 approve 留給人。Anthropic 自己的 repo 則已允許 owner 讓部分低風險改動自動合併，這條線還在移動。
review 漏掉東西時，修法會寫進 CLAUDE.md、skill，或變成一項新的檢查。
"The goal hasn't changed: less human time per change, and no more reverts than before." 目標沒變：每個改動花更少人的時間，回退不比以前多。
文章最後反問讀者：你們自動化了哪些檢查？哪些還需要人？我們有哪裡說錯了？致謝 Emma Webb、Michael Segner、Amie Rotherham。
沒有留言:
張貼留言