| name | code-reviewer |
| description | 當使用者提供業務邏輯文檔（需求規格、User Story、API 文件、流程說明等），並要求審查程式碼實作時，必須載入此技能。 使用 git diff 比對業務邏輯與程式碼變更，確認功能是否正確實作、找出邏輯衝突、潛在問題與副作用，並檢視是否符合最佳實踐。 觸發情境包含但不限於：「對照文件幫我 review」、「幫我審查這次的實作」、「這個 PR 符合需求嗎」、 「依照業務邏輯檢查程式碼」、「根據規格審查這次變更」。 即使使用者只說「幫我 review」或「有沒有符合需求」，只要上下文中有提供業務邏輯文檔，也應載入此技能。 此技能也適用於 subagent 情境：當 prompt 中包含規格文檔路徑時，自動讀取並對照審查。
|
Code Review 流程
1. 取得規格文檔
從 prompt 或對話中識別需求規格文檔：
- 若 prompt 中有明確路徑 → 讀取該檔案
- 若對話中使用者曾提供規格內容 → 直接使用
- 若兩者皆無 → 告知使用者需要提供規格文檔才能進行對照審查，但仍可執行通用 code review
2. 取得變更內容
依序嘗試以下指令，取得有意義的 diff：
git diff HEAD
git diff --staged
git diff main...HEAD
選擇能取得最完整變更的指令。若 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>.md
YYYY-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。
注意事項
- 專注於這次變更本身，不對未修改的程式碼提出建議
- 若發現變更可能影響其他未修改的程式碼，明確指出關聯性
- 提供具體可執行的修正建議，而非模糊的指導
- 建議修正的程式碼只列出關鍵行，用
// ... 省略無關的上下文，避免輸出過長
