review

name	review
description	L1 internal review with auto-detection, design comparison, and Gate escalation path
allowed-tools	Read, Edit, Glob, Grep, Bash

L1 內部 Review

執行內部 Review checklist 並記錄到開發計畫書第 10 節。支援自動偵測步驟類型。

使用方式

/review [review-type] [target]

參數

• $0: Review 類型（auto / code / spec / design / function）
• $ARGUMENTS: 完整參數
• 若 $0 為 auto 或省略，自動偵測當前步驟

步驟自動偵測

當 review-type 為 auto 或未指定時：

1. 讀取 proposal/sprint*-dev-plan.md（最新的開發計畫書）
2. 找到第 10 節「執行紀錄」中最近完成的任務
3. 根據任務類型判斷步驟：
   • 含 design / 架構 / API 設計 → 步驟 = 設計 → Review: 對規範
   • 含 mockup / UI / 圖稿 → 步驟 = UI 圖稿 → Review: 對設計稿
   • 含 backend / API / route / service → 步驟 = 實作（後端）→ Review: 對程式碼 + 對規範
   • 含 frontend / component / view / page → 步驟 = 實作（前端）→ Review: 對程式碼 + 對設計稿 + 對規範
   • 含 test / e2e / spec → 步驟 = 測試 → Review: 對功能 + 對規範
   • 含 doc / 文件 → 步驟 = 文件 → Review: 對規範
4. 輸出偵測結果，確認後執行

Review Checklist

對程式碼（code）

• 無 bug 或邏輯錯誤
• 錯誤處理完整（外部呼叫有 try-catch）
• 無硬編碼機密資訊
• 命名有意義且符合規範（snake/camel/Pascal 分層）
• 無死碼（註解掉的程式碼、未使用的 import）
• 單一職責原則
• TypeScript 型別正確（無 any）
• 文件已同步更新（.knowledge/ + CLAUDE.md 索引）

對規範（spec）

• 實作與 API 規範文件一致（api-design.md）
• 實作與 data model 文件一致（data-model.md）
• 實作與 feature spec 一致（feature-spec.md）
• 命名轉換正確（DB snake → API snake → 前端 camel）

對設計稿（design）

• 佈局結構一致（元件位置、大小、間距）
• 色彩一致（使用設計稿色系，未自行選色）
• 動畫一致（時長、easing 與設計稿規格相符）
• 狀態切換完整（設計稿定義的每個 UI 狀態都已實作）
• 響應式一致（桌面版和手機版都與設計稿一致）
• 文案一致（按鈕文字、placeholder、空狀態文案）

L1 比對方式：同時開啟設計稿 HTML/截圖和實際畫面，逐項確認。UI 不一致 = Blocker。

對功能（function）

• 端到端功能正常
• 效能達標
• 驗收標準全部滿足
• 無 Critical/High 等級 Bug

對文件正確性（doc-integrity）

檢查 dev-plan 和 .tasks/ 檔案的格式與內容一致性。 觸發時機：每次 /review 時自動附加執行，不需手動指定。

dev-plan 檢查

• 第 10 節存在且包含三個子表格（任務完成紀錄、Review 紀錄、Gate 紀錄）
• Gate 紀錄的決策值符合規範（✅ 通過 / ❌ 駁回 / ⚠️ 附條件通過，不可用純文字或英文）
• 日期格式為 YYYY-MM-DD
• 第 6 節任務表與 .tasks/ 目錄的任務數量一致

task 文件檢查（逐一掃描 .tasks/sprint-{N}/*.md）

• metadata 表必要欄位齊全：ID、狀態、Sprint、建立時間、開始時間、完工時間
• 狀態值為合法英文值（created / assigned / in_progress / in_review / done / blocked / rejected）
• 事件紀錄區塊（## 事件紀錄）存在且至少有一筆紀錄
• 事件紀錄 timestamp 格式為 ISO 8601（YYYY-MM-DDTHH:mm:ss.sssZ）
• 狀態為 done 的任務，驗收標準全部打勾（- [x]，無殘留 - [ ]）
• 狀態為 in_progress 以上的任務，開始時間 不得為 —
• 狀態為 done / in_review 的任務，完工時間 不得為 —

執行步驟

1. 偵測或確認 review type（若為 auto 則執行自動偵測）
2. 根據步驟類型選擇 review 組合（可能多種）
3. 自動附加「對文件正確性」檢查 — 每次 review 必定執行 doc-integrity checklist
4. 逐項檢查每個 checklist，標記 ✅ 或 ❌ 並說明
5. 統計結果：
   • 🔴 Blocker: {count}
   • 🟠 Major: {count}
   • 🟡 Minor: {count}
6. 判定：0 Blocker + 0 Major = 通過

結果記錄

在 dev-plan 第 10 節「Review 紀錄」表格，找到對應步驟行並更新：

格式規範（系統解析依賴）

欄位	格式	說明
Review 步驟	自由文字	如「UI 圖稿 Review」「實作 Review」
日期	YYYY-MM-DD	如 2026-03-27
結果	通過 或 不通過	嚴格使用這兩個值
Review 文件連結	自由文字	Blocker:{n} Major:{n} Minor:{n} — {摘要}

| {步驟名} Review | {YYYY-MM-DD} | {通過/不通過} | Blocker:{n} Major:{n} Minor:{n} — {摘要} |

Gate 升級路徑

Review 通過後，建議下一步：

完成的步驟	建議提交	指令
設計	—	進入下一步驟
UI 圖稿	G1 圖稿審核	/gate-record G1
實作（後端/前端）	G2 程式碼審查	/gate-record G2
測試	G3 測試驗收	/gate-record G3
文件	G4 文件審查	/gate-record G4

提交前確認：前置 Gate 已通過、開發計畫書第 10 節已記錄。