tomevault-io Code Review 流程
1. 取得規格文檔
從 prompt 或對話中識別需求規格文檔：
- 若 prompt 中有明確路徑 → 讀取該檔案
- 若對話中使用者曾提供規格內容 → 直接使用
- 若兩者皆無 → 告知使用者需要提供規格文檔才能進行對照審查，但仍可執行通用 code review
2. 取得變更內容
依序嘗試以下指令，取得有意義的 diff：
git diff HEAD # 包含已暫存與未暫存的所有變更
git diff --staged # 僅已暫存（即將提交）的變更
git diff main...HEAD # 與主分支的完整差異（適用於 feature branch）
選擇能取得最完整變更的指令。若 diff 為空，告知使用者並停止。
3. 前端檔案 React 最佳實踐審查（優先於規格審查）
分析 diff 中是否包含前端 React 相關檔案：
判斷前端檔案的條件（符合任一即視為前端變更）：
- 副檔名為
.tsx、.jsx - 副檔名為
.ts、.js，且路徑包含components?/、hooks?/、contexts?/、pages/或views/
若包含前端檔案，必須先載入並執行 react-design skill，依照其原則對 diff 進行審查。
審查完成後，將結果整理為「React 最佳實踐」區塊，再繼續進行後續的規格審查。
4. 對照規格審查（有提供規格文檔時必做）
逐項比對規格文檔的功能需求與實際 diff：
- 規格中要求的功能，實作是否完整？
- 規格中定義的 API / 資料結構，實作是否一致？
- 規格中描述的邊界條件與錯誤處理，是否有涵蓋？
- 是否有實作規格以外的功能（over-engineering 或偏離需求）？
5. 通用程式碼審查
🔴 邏輯衝突與錯誤（最高優先）
- 條件判斷邏輯是否正確（邊界條件）
- 資料流是否完整，有無遺漏的狀態更新
- 非同步操作的順序與錯誤處理
- 型別不匹配或隱性型別轉換
🟠 潛在風險
- 安全漏洞（XSS、SQL Injection、Command Injection 等）
- 效能問題（N+1 查詢、記憶體洩漏）
- 邊界情況是否處理
🟡 程式碼品質
- 命名是否清晰表達意圖
- 函數/元件職責是否單一
- 是否有未使用的變數或 import
🔵 型別安全
- 不安全的型別斷言（如
as any、強制 cast、非空斷言!）是否合理 - 型別縮窄是否完整（union / discriminated union 是否覆蓋所有分支）
- 序列化邊界（API request/response、JSON.parse、外部資料）是否有驗證或型別守衛
- 泛型參數是否被正確約束，避免退化為
unknown或any
⚪ 註解類問題（測試/開發階段保留）
- 是否有
TODO、FIXME、XXX、暫時性偵錯註解未清除 - 是否有被註解掉的程式碼（dead code as comments）
- 是否有暫時保留的診斷/偏差說明註解，需在進入正式實作前處理
註解類問題不直接判定為缺陷，因為測試或開發階段可能刻意保留； 統一歸入輸出格式中的「使用者自行決定」區塊，由使用者依目前階段判斷是否清除。
6. 輸出格式
使用繁體中文輸出，格式如下：
## 📋 Code Review 摘要
**審查範圍：** [描述變更涵蓋的檔案/功能]
**整體評估：** ✅ 符合規格可合併 / ⚠️ 部分符合，建議修改 / ❌ 不符合規格，需修正
---
### ⚛️ React 最佳實踐（僅前端變更時輸出此區塊）
#### ✅ 符合最佳實踐
- [原則]：[簡述實作如何符合]
#### ⚠️ 需改善
- [原則]：[描述問題與建議方向]
```tsx
// 建議修正方向
📐 規格符合度（有提供規格文檔時才輸出此區塊）
✅ 符合規格的項目
- [規格項目]：[簡單說明實作如何對應]
❌ 不符合或缺漏的項目
- [規格項目]：[說明缺漏或偏差之處]
🔴 必須修正（Critical）
問題 1：[問題標題]
- 檔案：
path/to/file.ts:行號 - 問題： [描述問題]
- 影響： [說明可能造成的後果]
- 建議修正：
// 修正後的程式碼
🟠 建議改善（Warning）
[同上格式]
⚪ 使用者自行決定（註解類問題）
問題 1：[問題標題]
- 檔案：
path/to/file.ts:行號 - 問題： [說明註解為何可能造成維護混淆，例如 TODO 未追蹤、被註解掉的程式碼、暫時偵錯註解]
- 影響： [說明此問題是否只影響正式化前的程式碼品質]
- 建議： [若目前為測試/開發階段可保留；若進入正式實作應移除或改寫]
7. 輸出存檔（必做）
完成 Code Review 後，除了在對話中輸出「## 📋 Code Review 摘要」以外，必須將該摘要的原始內容獨立存檔成一份 Markdown 文件，便於後續追蹤與分享。
存檔規則
- 存放位置： 專案根目錄下的
docs/code-review-report資料夾（若不存在則自動建立） - 檔名格式：
code-review-YYYY-MM-DD-<feature-slug>.mdYYYY-MM-DD為本機今日日期<feature-slug>為本次審查所對照規格文檔的檔名 slug（取規格檔名去掉副檔名、轉成 kebab-case）- 範例：
- 規格
docs/spec/login.md→docs/code-review-report/code-review-2026-05-17-login.md - 規格
docs/specs/user-profile.md→docs/code-review-report/code-review-2026-05-17-user-profile.md - 規格
docs/PRD-Checkout Flow.md→docs/code-review-report/code-review-2026-05-17-checkout-flow.md
- 規格
- 內容範圍： 檔案最上方為 H1 輪數標題（見「輪數判斷與標題」），其下為與對話輸出的「## 📋 Code Review 摘要」完全一致的內容，包含所有子區塊（React 最佳實踐 / 規格符合度 / 必須修正 / 建議改善 / 使用者自行決定等），不可省略、改寫或濃縮
- 不另加額外章節： 除了 H1 輪數標題之外，不要在檔案中再加入「審查時間」、「審查者」等對話中沒有的欄位；以原始內容為準
規格 slug 推導規則
- 取規格文檔的檔名主體（去掉路徑與副檔名）
- 全部轉小寫，空白與底線一律改為
- - 連續多個
-合併為一個，前後-去除 - 僅保留英數字與
-；非 ASCII 字元（如中文）以 transliteration 失敗時 fallback 為英文摘要詞
沒有規格文檔時的 fallback
- 若使用者沒有提供規格文檔（純通用 code review），改以 git diff 中本次主要實作的功能作為
<feature-slug>：- 閱讀 diff，歸納本次變更實際在做的事情（例如「新增登入流程」、「修正購物車數量計算」、「重構訂單匯出邏輯」）
- 將該功能描述濃縮為簡短英文 slug（kebab-case、僅英數與
-），例如：- 新增登入流程 →
login-flow - 修正購物車數量計算 →
fix-cart-quantity - 重構訂單匯出邏輯 →
refactor-order-export
- 新增登入流程 →
- 保持簡潔（建議 2~4 個單字內），讓檔名一眼就能辨識審查對象
- 若 diff 過於發散難以歸納單一功能，才 fallback 為
general
重複審查的覆蓋規則
- 若同一天、同一規格的審查再次執行（檔名完全相同），直接完全覆蓋整份檔案內容
- 不需要保留舊紀錄、不需要追加 changelog 區塊、不需要備份舊版；每次審查都是當下狀態的快照
- 不同功能（slug 不同）或不同日期會自然產生不同檔名，互不干擾
- 雖然檔案內容會被覆蓋，但輪數必須依照「輪數判斷與標題」遞增，讓使用者一眼看出這份檔案累積審查過幾次
輪數判斷與標題
寫檔前，必須先用 Read 工具讀取目標路徑（即步驟一推導出的最終檔名），依結果決定本輪輪數：
- 檔案不存在 → 視為第 1 輪
- 檔案存在 → 用 regex
第\s*(\d+)\s*輪從檔案開頭抓出舊輪數，新輪數 = 舊輪數 + 1 - 檔案存在但抓不到輪數（例如歷史檔尚未套用此規則）→ 視為第 1 輪
判斷完成後，在檔案最上方加入 H1 標題（位於所有內容之前），格式固定為：
# Code Review 紀錄 — YYYY-MM-DD（第 N 輪）
YYYY-MM-DD與檔名中的日期一致（本機今日日期）N為上面推導出的輪數，使用阿拉伯數字- H1 標題下方空一行，再接原本的
## 📋 Code Review 摘要與其後所有內容（內容本身不因輪數而改變）
設計動機：subagent 是 cold start，無法靠記憶判斷「現在是第幾輪」；唯一可靠的線索就是現存檔案。 透過「讀檔 → 解析 → +1」的固定流程，把輪數變成可重現的行為，而非依賴模型自發補上。
執行時機
- 在對話中輸出「## 📋 Code Review 摘要」之後立即執行寫檔
- 寫檔完成後，在回覆中以一行簡短訊息告知使用者檔案路徑，例如：
📁 已存檔：docs/code-review-report/code-review-2026-05-17-login.md
設計動機：按功能切分檔名是為了避免「同日多功能審查互相覆蓋」（規格檔名越具體越好， 像
README這種通用名應改找更具體的來源）；同功能同日直接覆蓋則是因為同一審查週期 只有最新結論才有效，歷史變化請依賴 git history，不要在檔內自行追加 changelog。
注意事項
- 專注於這次變更本身，不對未修改的程式碼提出建議
- 若發現變更可能影響其他未修改的程式碼，明確指出關聯性
- 提供具體可執行的修正建議，而非模糊的指導
- 建議修正的程式碼只列出關鍵行，用
// ...省略無關的上下文，避免輸出過長
Source: ting-s515/skills — distributed by TomeVault.