用 Claude Code 設計 AI 程式碼審查機制：以 Payload CMS 為例

用 AI 寫程式碼的時候，有一個容易被忽略的問題：AI 很擅長把功能做出來，但它不一定了解你用的工具有哪些「該注意但沒注意就會出事」的地方。

每個開源框架都有自己的一套使用建議。有些寫在官方文件的安全性章節，有些藏在效能調校的頁面，有些是社群踩過坑之後整理出來的。這些建議通常不影響功能是否能跑，但會影響上線之後會不會出問題 — 資料被未授權的人看到、頁面越來越慢、資料庫改版時資料不見了。

問題是，這些建議散落在不同地方，就算是有經驗的開發者也不一定每次都記得。AI 更不會主動幫你對照這些清單。

我們團隊一直有在使用 Claude Code 的 Command、Agent、Skill 三層架構來擴充開發流程，剛好可以用來解決這個問題：把框架的使用建議整理成結構化的檢查清單，讓 AI 寫完程式碼之後，自動根據這份清單逐項檢查。

這篇文章分享我們怎麼設計這套機制。我們用 Payload CMS（一個 Node.js 的開源後端框架）作為實際案例，但整套設計方法可以套用到任何框架或工具。

第一步：搞清楚你用的工具有哪些「該注意的事」

第一件要做的事不是寫程式，而是好好讀一遍你用的框架的官方文件。特別是跟上線部署、安全性、效能相關的章節。大部分成熟的開源工具都會把這些注意事項寫出來，只是散落在不同頁面，需要自己整理。

以 Payload CMS 為例，我們花了一些時間把官方文件翻過一輪，整理出三個需要特別注意的面向：

安全性 — Payload 在伺服器端提供了一組內部 API，方便開發者直接操作資料庫。但這組 API 有一個特性：預設不會檢查使用者的權限（官方文件有明確說明）。如果開發者沒有手動開啟權限檢查，任何人都可能透過這組 API 讀到不該看到的資料。另外，官方在 Preventing Abuse 和 Deployment 頁面分別列出了防暴力破解、跨站請求偽造防護、查詢深度限制等上線前該設定的項目。

效能 — Payload 在查詢資料時，可以自動帶出關聯的資料（例如查文章時順便帶出作者資訊）。這個功能很方便，但每多帶一層關聯，就多一輪資料庫查詢。官方文件（Depth、Select、Indexes）建議開發者明確控制要帶幾層、只取需要的欄位、對常查詢的欄位建立索引。開發時資料少感覺不出差異，上線後資料量一大就會明顯變慢。

資料庫變更安全 — 開發過程中經常需要修改資料結構（加欄位、改名稱、刪欄位）。Payload 處理欄位改名的方式比較特別：它不是直接改名，而是先把舊欄位刪掉再建一個新的（Migrations 文件）。這代表舊欄位裡的資料會直接消失。官方建議的做法是分階段處理：先加新欄位、把資料搬過去、確認沒問題、最後才刪舊欄位。

每個框架會有不同的注意事項。重點是從官方文件出發，有系統地整理，而不是等出了問題才回頭找原因。

第二步：決定審查的粒度和觸發時機

找出風險維度之後，下一個決定是：要做幾個審查指令？什麼時候觸發？

我們一開始的直覺是做一個大指令，把所有檢查項目塞在一起。但實際用了幾次之後發現兩個問題：第一，每次都跑全部檢查太慢也太浪費 token；第二，migration 的風險等級遠高於效能問題，混在一起報告時容易忽略真正危險的項目。

最後我們拆成兩類，共五個指令：

日常開發用 — commit 前跑：

• /payload-check：自動偵測改了哪些檔案，只跑需要的審查
• /payload-review：單獨跑安全性審查
• /payload-perf：單獨跑效能審查
• /payload-migrate：單獨跑 migration 審查

定期健檢用 — 每週跑：

• /payload-audit：三個維度同時掃描整個 codebase

拆開的好處是日常開發不會被完整審查拖慢。改了一個 hook 就只跑安全性和效能審查，不需要等 migration 審查跑完。/payload-check 負責自動判斷該跑哪些，開發者不用記。

觸發時機我們選在 commit 之前。原因很實際：commit 前發現問題可以直接改，改完一起 commit，git history 乾淨。如果 commit 之後才跑，發現問題還要再改再 commit，多出一堆 fix commit。

第三步：用三層架構把知識和流程分開

這是整個設計中最關鍵的決定。Claude Code 提供三種機制：Command、Agent、Skill。

層級	機制	放什麼
Command	.claude/commands/*.md	入口點。接收使用者指令，決定啟動哪個 Agent
Agent	.claude/agents/*.md	執行者。定義審查流程：收集 diff → 讀取知識 → 逐項檢查 → 產出報告
Skill	.claude/skills/*/SKILL.md	知識庫。完整的 checklist、正確 / 錯誤程式碼範例、官方文件對應

為什麼要分三層？因為知識和流程的更新頻率不同。

Skill 裡的 checklist 會隨著框架版本更新而變（Payload v3 和 v4 的最佳實踐不一樣），但審查流程（收集 diff → 讀知識 → 檢查 → 報告）基本不會變。如果把 checklist 直接寫在 Agent 裡面，每次更新 checklist 都要同時改 Agent，改錯了連流程都壞掉。

分開之後，更新 checklist 只需要改 Skill 檔案，Agent 和 Command 完全不用動。

Command：保持精簡

Command 只需要一句話說明用途，加上指定啟動哪個 Agent。以 /payload-review 為例：

Run a Payload CMS SaaS security review on the current git diff.

Launch the `payload-saas-reviewer` agent to execute the review.

不要在 Command 裡寫具體的檢查步驟。Command 是入口，不是說明書。

Agent：定義流程，不存知識

Agent 定義審查的執行流程和輸出格式，但具體要檢查什麼則從 Skill 讀取。

## Workflow

1. Gather context — Run `git diff --staged` and `git diff`.
2. Load knowledge — Read `.claude/skills/payload-saas-review/SKILL.md`.
3. Identify scope — Determine which file types changed.
4. Read surrounding code — Never review in isolation.
5. Apply checklist — Work through each category in SKILL.md, CRITICAL first.
6. Report findings — Only report issues with >80% confidence.

關鍵是第 2 步：Agent 被指示去讀 Skill 檔案。這樣 Skill 更新了，Agent 下次執行自動就會用新的 checklist。

Agent 裡還有一個重要的設計：Noise Filter。我們要求 Agent 只報告信心度超過 80% 的問題，同類問題要合併（「3 個 collection 缺少 tenant filter」而不是 3 個獨立項目）。沒有這個過濾，審查報告會充斥大量低信心度的噪音，開發者很快就會忽略所有警告。

Skill：完整的知識庫

Skill 是整套機制的核心，內容最多也最重要。一份好的 Skill 檔案需要包含：

1. 分級的 Checklist

按嚴重程度分級：CRITICAL（必須封鎖合併）、HIGH（合併前修復）、MEDIUM（後續 PR 處理）、LOW（記錄備忘）。

不分級的 checklist 等於沒有 checklist — 開發者不知道哪些問題要優先處理。

2. 正確和錯誤的程式碼範例

每個檢查項目都配一組「錯誤寫法 → 正確寫法」的程式碼對照。光是描述規則不夠，Agent 需要具體的 pattern 才能準確辨識程式碼中的問題。

以 Payload 的 depth 控制為例：

// ❌ 沒有設定 depth，使用預設值，觸發不必要的關聯查詢
const posts = await payload.find({
  collection: 'posts',
})

// ✅ 明確設定最低必要的 depth，搭配 select 只取需要的欄位
const posts = await payload.find({
  collection: 'posts',
  depth: 1,
  select: { title: true, slug: true, category: true },
})

3. 官方文件對應

每條規則標註出處，例如「根據 Preventing Abuse 文件，maxLoginAttempts 必須設定」。這讓開發者可以自己去查原始文件，也讓 Agent 的建議更有說服力。

第四步：設計整合指令和全 Codebase 審計

日常開發有三個獨立的審查指令，但每次都要想「這次該跑哪個」很煩。所以我們做了 /payload-check — 它看 git diff 改了哪些檔案，自動決定該啟動哪些 Agent。

改了 migrations/ 或 collection 欄位定義 → 啟動 migration Agent。改了 payload.find() 相關的程式碼 → 啟動效能 Agent。改了 access control 或 auth 邏輯 → 啟動安全 Agent。多個維度同時觸發就並行跑。

另外一個問題是：diff 審查只看「這次改了什麼」，不會抓到已經存在的問題。三個月前寫的 collection 沒加 index，上週部署時忘記設定 maxLoginAttempts，這些不會出現在任何一次 diff 裡面。

所以我們做了 /payload-audit，同時啟動三個 Agent 掃描整個 codebase，產出一份按嚴重程度排序的完整報告。這個指令的 token 消耗較高（大約是單一 diff 審查的 5-10 倍），不建議每天跑，每週一次或上線前跑比較合理。

最終的開發流程：

寫完功能
    ↓
/payload-check     ← 自動偵測，只跑需要的審查
    ↓
有問題 → 修完再跑一次
沒問題 ↓
  git commit → push

每週再跑一次 /payload-audit 做全面健檢。

第五步：根據專案類型設計你自己的 Checklist

到目前為止，我們的範例都是 Payload CMS 的 SaaS 平台，安全審查重點放在 tenant 隔離和計費邏輯。但同樣的三層架構可以適用於任何專案類型。

你需要做的是：根據你的專案類型，設計對應的 Skill 檔案。Agent 和 Command 的結構幾乎不需要改，因為審查流程是通用的（收集變更 → 讀知識 → 逐項檢查 → 產出報告），只有知識庫的內容需要替換。

以下是幾種不同專案類型的 checklist 方向，供你參考。

電商網站

安全性的重點從 tenant 隔離轉移到交易安全：

• 訂單存取控制 — 買家只能查看自己的訂單，API 層級是否有做 user.id === order.customer 的驗證
• 價格信任邊界 — 結帳時的價格是從資料庫讀的還是前端傳來的？前端傳來的價格不能直接信任
• 庫存 Race Condition — 兩個人同時購買最後一件商品，有沒有用 transaction 或 optimistic locking 處理
• 付款 Webhook Idempotency — 金流通知重送時不能重複建立訂單或重複扣庫存

效能的重點在商品查詢和購物車：

• 商品列表查詢 — 有沒有對分類、價格範圍、上架狀態加 index
• 購物車計算 — 是每次都從 DB 撈完整商品資料，還是只取價格和庫存
• 圖片處理 — 商品圖片有沒有做 resize 和 CDN 快取

內容管理網站

安全性聚焦在發布權限和公開 API：

• 多層審核 — 編輯、審核者、管理員的權限邊界是否清楚
• 草稿洩漏 — 未發布的草稿有沒有透過 API 曝光
• 公開 API 的 Rate Limiting — 沒登入的請求有沒有做頻率限制
• 檔案上傳 — 有沒有限制大小、格式、儲存路徑

效能重點在內容查詢和快取：

• 公開頁面的快取 — 首頁、文章列表這類不常變動的頁面有沒有做快取
• Rich Text 處理 — Lexical JSON 是在伺服器端轉 HTML 還是丟給前端處理
• SEO 欄位 — sitemap 產生是即時運算還是定期快取

多語系網站

額外需要關注的維度：

• 翻譯完整性 — 主語言有的欄位，其他語言是否也有對應內容
• Locale Fallback — 缺少翻譯時的降級邏輯是否正確
• URL 結構 — hreflang 標籤和實際路由是否對應

設計 Checklist 的原則

不管是哪種專案類型，設計 checklist 時有幾個原則：

1. 從官方文件出發，不要靠直覺。每個框架的 production / security / performance 章節通常就有 80% 的答案
2. 按嚴重程度分級。不分級的 checklist 就是一堆平等的待辦事項，開發者不知道哪些真的危險
3. 附上程式碼範例。Agent 需要具體的 pattern 來辨識問題，光靠文字描述不夠精準
4. 只放 AI 容易犯的錯。人類開發者會犯的低級錯誤（拼錯變數名）不需要放進來，那是 linter 的工作

完整的檔案結構

最後整理一下完整的檔案結構，方便你照著建：

.claude/
├── commands/
│   ├── payload-check.md      # 入口：自動偵測 + 啟動對應 Agent
│   ├── payload-review.md     # 入口：啟動安全 Agent
│   ├── payload-perf.md       # 入口：啟動效能 Agent
│   ├── payload-migrate.md    # 入口：啟動 migration Agent
│   └── payload-audit.md      # 入口：三個 Agent 並行掃全 codebase
├── agents/
│   ├── payload-saas-reviewer.md         # 安全審查流程
│   ├── payload-performance-reviewer.md  # 效能審查流程
│   └── payload-migration-reviewer.md    # Migration 審查流程
└── skills/
    ├── payload-saas-review/
    │   └── SKILL.md           # 安全知識庫（checklist + 範例）
    ├── payload-performance-review/
    │   └── SKILL.md           # 效能知識庫
    └── payload-migration-review/
        └── SKILL.md           # Migration 知識庫

如果你要替換成自己的框架，把 payload 換成你的框架名稱，修改 Skill 裡的 checklist 和程式碼範例就可以了。Agent 的 workflow 和 Command 的入口邏輯基本上可以直接複用。

設計完之後的感想

這套機制上線大約兩週，我們的感受是：它不會取代人工 code review，但確實補上了一個盲區。AI 寫程式碼的速度很快，但速度帶來的風險是容易略過框架特有的注意事項。這些注意事項寫在官方文件裡，但分散在各個頁面，就算是人類開發者也不一定每次都記得。

把這些知識整理成結構化的 checklist，讓 AI 在產出程式碼之後自己檢查一遍，比起每次人工逐項確認高效得多。發現的問題在 commit 前就修掉，不會帶到生產環境才爆炸。

如果你也在用 AI 輔助開發，不管是什麼框架，花幾個小時把官方文件的最佳實踐整理成 Skill 檔案，設計對應的 Agent 和 Command，長期來看絕對值得。