Journal
AI 協作系列｜第 3 篇：交付檢查，不只是 code review
承接 第 0 篇 的脈絡。
Code Review 的問題不是規則太少
做 code review 最直覺的做法，是給 Agent 一份清單：命名有沒有符合規範、有沒有未使用的 import、error handling 完不完整……
這個做法有效，但有一個核心問題：清單讓 Agent 變成了核對機器，而不是在做判斷。
「未使用的 import」命中了，它就回報一個問題。但「未使用」不一定是問題——有些 import 是在動態引用、有些是框架 convention、有些是外部 consumer 在使用。機械性地核對規則，會產生大量誤報，然後你要花時間把誤報一個一個解釋掉。
更糟的情況是 Agent 直接把「發現了 pattern」等同於「需要修改」。一個小修改，被順帶重構成一場架構調整。
所以這套框架想解決的不是「給更多規則」，而是改變 Agent 處理 review 的方式。
核心原則：後果決定 severity
這個框架的設計原則只有一句話：
後果決定 severity，不是 pattern 本身。
同樣是「缺少 error handling」，後果可能差很多：
- 付款 timeout 沒有處理 → 使用者重試一次，變成兩筆扣款 → Must Fix
- 搜尋結果載入失敗沒有顯示錯誤訊息 → 使用者看到空畫面 → Should Review
- 開發環境的 debug page 顯示 stack trace → 不影響任何人 → 忽略
三個都是「缺少 error handling」，但嚴重程度完全不同。如果 Agent 只核對「有沒有 error handling」，三個都會被回報為問題；如果 Agent 先判斷後果，才能做出正確的分類。
把這個原則放在框架最前面，是在告訴 Agent：規則是參考，後果是依據。
三層分類
有了這個原則，找到的問題可以分三類：
Must Fix：有明確的 correctness、security 或資料完整性問題，合併後存在實質風險。這層的問題值得停下來修，不修不合併。
Should Review：有 code smell、潛在風險或設計取捨，但需要依 context 判斷後果。這層的問題要回報、給建議，但不主動修，因為最後的決定是人的。
Project Convention：沒有對錯，只要求專案內一致。命名格式、import 排序、檔案歸屬——對照 project 的規範跑，不符合就指出來。
三層分類的重要性不只是整理，而是讓 Agent 知道：Must Fix 要說清楚後果，Should Review 要給判斷材料，Convention 要說清楚違反了哪條規範。 每一層的 evidence 要求不一樣。
為什麼不是 husky + CI 就夠了
Lint、typecheck、build、test——這些交給 husky hook 和 CI pipeline 自動跑，完全夠。它們速度快、結果可重現、不需要 Agent 介入。
Agent 能做、自動化做不到的是判斷型的審查：
- 這個 state 放在這個層級合理嗎？
- 這個 API 的 error response 有沒有把需要的資訊給到 client？
- 這份 migration 在 production data volume 下執行會不會 lock 太久？
- 這個 feature 的 spec 只有 happy path，non-happy path 有沒有被遺漏？
這些問題有的需要讀整個 context、有的需要對系統有理解、有的需要推理後果。這是 Agent 的適合場景，不是 shell script 的適合場景。
所以這套框架的設計是：shell 負責的讓 shell 做，Agent 負責做不到的部分。
動態載入，不是全部塞進去
一個完整的 review 框架可以有很多規則——Frontend 的狀態管理、Backend 的 API 設計、資料庫的 migration 安全性、CI/CD 的 artifact 完整性——全部都有意義，全部都值得檢查。
但如果這次改動只有一個按鈕的樣式，把資料庫 migration 的規則也塞進 context 裡，是在浪費空間，而且可能讓 Agent 在不相關的地方找問題。
解法是依 changed files 偵測 context，只載入相關的規則。
框架的設計是這樣的：
- 先看這次改了哪些檔案
- 偵測 context——有
.tsx就載入 Frontend 規則、有 migration 檔案就載入 DB 規則、有.github/workflows就載入 CI/CD 規則 - 在每個 context 裡再做 capability detection——有
useEffect才跑 React effect 規則、有dangerouslySetInnerHTML才跑 HTML injection 規則 - 只 review changed files，不掃整個 repo；但若改動影響到 consumer（API schema 改了，前端型別也需要確認），追蹤到 affected code
這樣規則庫可以很大，但單次 Agent context 保持精簡。
四個面向
最後決定這個框架覆蓋的四個面向：
Application：Frontend（React state、async states、user interaction）和 Backend（API contract、external dependency、service contract）。這是傳統 code review 的範圍。
Data：Database 和 migration。Schema 正確性、migration 安全性、生產環境資料量下的風險、concurrent write 的 integrity。這是很多 code review 工具碰不到的地方，但出事的後果往往最嚴重。
Runtime：Infrastructure 和 deployment。Docker image、environment config、network exposure、secrets、IAM、health check、deployment strategy。程式碼沒問題，但放上去跑不起來，這個面向負責抓這類問題。
Delivery：CI/CD pipeline 本身。Trigger correctness、quality gates、artifact integrity、secrets in pipeline、deployment protection。這層回答的問題是：從 commit 到 production 的流程，有沒有守住品質和安全？
這四個面向加在一起，才算是「系統交付」的完整檢查，而不只是「code 寫得好不好」。
最重要的一件事沒有辦法寫進規則
說到最後，有一件事我認為是這套框架能不能真正有用的關鍵，但它沒辦法被寫成規則。
Agent 要知道什麼時候不要動。
一個 review skill 很容易變成「每次 review 完就順帶重構一輪」的工具——因為 Agent 找到了很多可以改的地方，就全改了。這不是 review，是在改動範圍不受控的前提下做修改。
所以框架裡明確寫了 fix policy：Must Fix 要說清楚後果，等人確認再修；Should Review 只回報，不主動修；Convention 的機械性整理可以自動，結構性調整要確認。
「不是找到了就改」這件事，比找到問題更重要。
本文是系列的第 3 篇。第 4 篇 說 AI 協作開發的複雜度問題。