# Ting S515 Skills Code Reviewer

> Code Review 流程

- Skill: `tomevault-io/ting-s515-skills-code-reviewer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/ting-s515-skills-code-reviewer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ting-s515-skills-code-reviewer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/ting-s515-skills-code-reviewer

---


# Code Review 流程

## 1. 取得規格文檔

從 prompt 或對話中識別需求規格文檔：
- 若 prompt 中有明確路徑 → 讀取該檔案
- 若對話中使用者曾提供規格內容 → 直接使用
- 若兩者皆無 → 告知使用者需要提供規格文檔才能進行對照審查，但仍可執行通用 code review

## 2. 取得變更內容

依序嘗試以下指令，取得有意義的 diff：

```bash
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. 輸出格式

使用繁體中文輸出，格式如下：

```markdown
## 📋 Code Review 摘要

**審查範圍：** [描述變更涵蓋的檔案/功能]
**整體評估：** ✅ 符合規格可合併 / ⚠️ 部分符合，建議修改 / ❌ 不符合規格，需修正

---

### ⚛️ React 最佳實踐（僅前端變更時輸出此區塊）

#### ✅ 符合最佳實踐
- [原則]：[簡述實作如何符合]

#### ⚠️ 需改善
- [原則]：[描述問題與建議方向]
  ```tsx
  // 建議修正方向
  ```

---

### 📐 規格符合度（有提供規格文檔時才輸出此區塊）

#### ✅ 符合規格的項目
- [規格項目]：[簡單說明實作如何對應]

#### ❌ 不符合或缺漏的項目
- [規格項目]：[說明缺漏或偏差之處]

---

### 🔴 必須修正（Critical）

#### 問題 1：[問題標題]
- **檔案：** `path/to/file.ts:行號`
- **問題：** [描述問題]
- **影響：** [說明可能造成的後果]
- **建議修正：**
  ```typescript
  // 修正後的程式碼
  ```

---

### 🟠 建議改善（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。

---

## 注意事項

- 專注於這次變更本身，不對未修改的程式碼提出建議
- 若發現變更可能影響其他未修改的程式碼，明確指出關聯性
- 提供具體可執行的修正建議，而非模糊的指導
- 建議修正的程式碼只列出關鍵行，用 `// ...` 省略無關的上下文，避免輸出過長

---
> Source: [ting-s515/skills](https://github.com/ting-s515/skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-06 -->