先決定你現在是要學，還是要在專案裡做
網站負責解釋與分發工作包；真正的 Repository 掃描、缺口判斷與文件產出交給 Coding Agent。
SDLC 實作課 · 交付物練習
先理解這份文件替你消除什麼不確定
把 review 從個人品味變成可重現流程
每個 reviewer 看不同的東西，品質起伏大。Checklist 把「最低必看項目」標準化：正確性、安全、可觀測性、可回滾，剩下交給人類判斷。
誰負責、交給誰
主責： Dev Lead 維護
協作： Security、SRE、QA 各補一個維度
下游收件： 全體 Reviewer
何時值得做
必要時機： 中大型團隊、跨團隊 PR、敏感模組
不需要時： 兩人團隊、強信任實驗專案
常見誤用： 變成形式填表；把 lint 能做的事放進來
- 01讀大綱
- 02看案例
- 03填素材
- 04貼提示詞
- 05對照驗收
Anatomy · 文件解剖
輕量版先回答 5 個核心章節
章節名稱可以因團隊調整，但每一段要求的判斷不能被省略。先讀問題，再看格式。
- 01
Executive Summary
範本必要章節
3-5 行，reviewer 30 秒看完。內容：總 finding 數、must_block 數、最危險的 1-2 條
- 02
Dimension Coverage
範本必要章節
7 象限全列，沒 finding 也要寫「已檢視，無 finding」。輕量版可合併 a11y 為 N/A 並寫原因
- 05
Findings
範本必要章節
輕量版只列 must_block + should_fix，nit 省略。每條附 file:line + suggested_fix + source
- 09
Risks（top 3）
範本必要章節
只列 top 3，每條含「失效模式 + Mitigation + Owner」三件
- 12
Confidence & Sources & TODO
範本必要章節
把已確認的內容、判斷依據與仍待補充的資訊清楚分開。
Study · 對照學習
同一份交付物，先練核心，再看完整深度
輕量範本適合第一次練習與 MVP；完整範本保留跨職能交棒需要的細節。兩者都要求未知事項保持可見。
30 分鐘內先完成核心章節。
---
doc_type: "code-review-checklist"
variant: "light"
status: "draft"
owner: "<your-name>"
last_updated: "YYYY-MM-DD"
upstream:
required: ["git-diff", "coding-standard"]
optional: ["existing-checklist"]
---
# Code Review Checklist: <PR-or-module-name>
**Status:** Draft v0.X · **Owner:** <Dev Lead name> · **Last updated:** YYYY-MM-DD
> [!IMPORTANT]
> **AI 填寫規則：** 本範本 5 段（編號 1, 2, 5, 9, 12），全部必填——刻意沿用完整版的章節編號讓兩版可對照。每個 finding 行內加 `（依據：diff path:line / standard §X）`；每 finding 帶 `[H]/[M]/[L]` confidence badge；缺資料寫 `_TODO: 需要 XXX_` 不編造；輕量版只列 must_block 與 should_fix，nit 可省略。
---
## 1. Executive Summary
<!-- ai-fill: 3-5 行，reviewer 30 秒看完。內容：總 finding 數、must_block 數、最危險的 1-2 條 -->
<3-5 行說明>
> **TL;DR:** <一句話：這個 PR 該不該擋下、為什麼>
---
## 2. Dimension Coverage
<!-- ai-rule: 7 象限全列，沒 finding 也要寫「已檢視，無 finding」。輕量版可合併 a11y 為 N/A 並寫原因 -->
| Dimension | Status | Finding count | Confidence |
|---|---|---|---|
| Correctness | covered | 2 | **[H]** |
| Readability | covered | 1 | **[H]** |
| Perf | covered | 0 (已檢視) | **[M]** |
| Security | covered | 1 | **[H]** |
| Test | covered | 1 | **[H]** |
| Observability | covered | 0 (已檢視) | **[M]** |
| A11y | N/A (backend-only PR) | 0 | **[H]** |
---
## 5. Findings
<!-- ai-rule: 輕量版只列 must_block + should_fix，nit 省略。每條附 file:line + suggested_fix + source -->
### F-001 · Severity **must_block** · **[H]**
- **File:line:** `<path>:<line>`
- **Dimension:** security
- **Evidence:** `<code snippet 或 standard §X>`
- **Suggested fix:** <一句話>
- **Source:** diff §XX + standard §YY
### F-002 · Severity **should_fix** · **[M]**
- ...
---
## 9. Risks（top 3）
<!-- ai-rule: 只列 top 3，每條含「失效模式 + Mitigation + Owner」三件 -->
> **R1:** <風險描述> — **Mitigation:** <如何降低> — **Owner:** <誰負責>
>
> **R2:** ...
>
> **R3:** ...
---
## 12. Confidence & Sources & TODO
- **整份 checklist 最低 confidence 項：** <列出所有 [L] 與 [M] finding>
- **Fabricated assumptions（推測但 input 未明說）：**
- <假設 1>
- **Highest-value next input:** <e.g. SLO 監控設定 / production incident 史>
### TODO（缺資料）
- _TODO: 需要 perf benchmark 確認 F-003 是否升級_
---
> [!CAUTION]
> **輸出前 AI 自檢：**
> - [ ] 5 段 H2 章節齊全（編號 1, 2, 5, 9, 12，刻意不連號）
> - [ ] 每個 finding 帶 inline `[H/M/L]` badge + `file:line` + suggested_fix
> - [ ] Dimension Coverage 7 象限全列，N/A 須寫原因
> - [ ] Findings 至少分 must_block / should_fix 兩級
> - [ ] Risks 每條格式：失效模式 + Mitigation + Owner
> - [ ] 無 YAML / JSON schema 輸出（checklist 是給人讀的 markdown）Practice · 換你試做
先用自己的話交代素材，不需要先學會工程術語
確定的就寫，不確定的留白。下一步要做的是請 Agent 找缺口，不是讓它替你猜一套合理答案。
可以先留白；複製提示詞後再到 Coding Agent 裡補充。
AI Practice · 手動三步
先問、再寫、最後審，不把整條流程鎖死
每一步都是獨立工作包。你可以停下補資料、修改限制或重做某一步，不需要服從固定的 Agent 接力流程。
只找阻擋文件成立的未知
先補會改變範圍、判斷或驗收結果的資訊，不急著寫文件。
我要製作「Code Review Checklist」。先不要產出文件。
請根據我的素材，找出會影響這份文件正確性或可執行性的未知事項，一次最多問 5 題。
每題請包含：
1. 問題
2. 為什麼現在必須知道
3. 它會影響哪個章節或決定
已經回答的事不要重問；可以延後的事標成「待決策」；不要替我猜答案。
本文件的核心章節：Executive Summary、Dimension Coverage、Findings、Risks（top 3）、Confidence & Sources & TODO複製後，請在標示位置貼上自己的素材。
Review · 自己驗收
文件存在，不代表下一個角色真的能使用
逐條檢查 Agent 的輸出。人類負責需求、限制與驗收，也必須能說明重要結論從哪裡來。
帶著這份文件，繼續到「Unit Test · 單元測試」
下一張卡會接住新的決策問題；不用一次把整條 SDLC 全做完。