---
name: cognitive-review
description: "認知負擔 Code Review 工具。用認知負擔視角進行程式碼審查。用於: (1) 程式碼品質評估, (2) 命名品質檢查, (3) 複雜度熱點識別, (4) 重構建議"
---

# 認知負擔 Code Review 工具

## 核心理念

> 好的程式碼不需要讀者額外的認知努力就能理解

Code Review 的目標不只是找出錯誤，更重要的是確保程式碼對未來的閱讀者友善。

---

## 審查維度

### 1. 變數狀態追蹤

**檢查問題**：這段程式碼需要閱讀者同時記住幾個變數的狀態？

| 變數數 | 評估 | 建議 |
|--------|------|------|
| 1-3 | 優良 | 維持 |
| 4-5 | 可接受 | 考慮提取函式 |
| > 5 | 需重構 | 拆分為更小的函式 |

### 2. 呼叫層級追蹤

**檢查問題**：理解這段程式碼需要追蹤幾層呼叫？

| 層級 | 評估 | 建議 |
|------|------|------|
| 1-2 | 優良 | 維持 |
| 3 | 可接受 | 考慮扁平化 |
| > 3 | 需重構 | 提取中間函式或使用組合 |

### 3. 命名品質

**檢查問題**：不看實作，能從名稱理解意圖嗎？

| 問題類型 | 範例 | 改善建議 |
|---------|------|---------|
| 縮寫不明 | `btn`, `mgr` | `button`, `manager` |
| 含義模糊 | `data`, `info` | 具體化：`userData`, `bookInfo` |
| 動作不清 | `handle()`, `process()` | `validateInput()`, `calculateTotal()` |
| 過長冗餘 | `getTheUserDataFromDatabase` | `fetchUser` |

### 4. 條件分支

**檢查問題**：需要考慮幾條執行路徑？

| 分支數 | 評估 | 建議 |
|--------|------|------|
| 1-2 | 優良 | 維持 |
| 3-4 | 可接受 | 考慮策略模式或早期返回 |
| > 4 | 需重構 | 使用策略模式或狀態模式 |

### 5. 函式長度

**檢查問題**：這個函式做了幾件事？

| 行數 | 評估 | 建議 |
|------|------|------|
| 5-10 | 優良 | 維持 |
| 11-20 | 可接受 | 考慮拆分 |
| > 20 | 需重構 | 必須拆分 |

### 6. 參數數量

**檢查問題**：呼叫者需要記住幾個參數的順序和意義？

| 參數數 | 評估 | 建議 |
|--------|------|------|
| 0-2 | 優良 | 維持 |
| 3 | 可接受 | 考慮參數物件 |
| > 3 | 需重構 | 使用參數物件或建造者模式 |

---

## 審查清單

### 函式層級

- [ ] 函式長度 <= 20 行
- [ ] 參數數量 <= 3
- [ ] 巢狀深度 <= 3
- [ ] 區域變數數 < 5
- [ ] 函式名稱是動詞片語
- [ ] 函式只做一件事

### 類別層級

- [ ] 類別方法數 <= 12
- [ ] 公開方法數 <= 5
- [ ] 類別依賴數 <= 5
- [ ] 類別名稱是名詞
- [ ] 單一責任明確

### 命名層級

- [ ] 無縮寫或僅使用業界通用縮寫
- [ ] 變數名稱是名詞或名詞片語
- [ ] 布林變數是 is/has/can 開頭
- [ ] 常數名稱全大寫底線分隔
- [ ] 不使用 data/info/value 等模糊詞

---

## 認知負擔熱點識別

### 常見熱點

| 熱點類型 | 識別方法 | 影響 |
|---------|---------|------|
| 長函式 | > 20 行 | 難以一次理解 |
| 深巢狀 | > 3 層縮排 | 上下文難追蹤 |
| 多參數 | > 3 個參數 | 呼叫時容易出錯 |
| 副作用 | 修改外部狀態 | 行為不可預測 |
| 隱藏依賴 | 內部 new 物件 | 難以測試和理解 |

### 熱點優先級

| 優先級 | 類型 | 處理方式 |
|--------|------|---------|
| P0 | 副作用 | 立即修復 |
| P1 | 深巢狀 | 本次 PR 修復 |
| P2 | 長函式 | 建立技術債 Ticket |
| P3 | 多參數 | 視情況處理 |

---

## 審查報告格式

```markdown
## 認知負擔 Code Review 報告

### 檔案: {檔案路徑}

### 整體評估

| 維度 | 評分 | 說明 |
|------|------|------|
| 變數管理 | {1-5} | {說明} |
| 呼叫層級 | {1-5} | {說明} |
| 命名品質 | {1-5} | {說明} |
| 函式設計 | {1-5} | {說明} |
| **總評** | **{1-5}** | **{說明}** |

### 熱點清單

| 行號 | 類型 | 問題 | 建議 | 優先級 |
|------|------|------|------|--------|
| {行} | {類型} | {問題} | {建議} | {P0-P3} |

### 命名問題

| 原名 | 問題 | 建議名稱 |
|------|------|---------|
| {原名} | {問題} | {建議} |

### 重構建議

1. **{建議標題}**
   - 位置: {行號範圍}
   - 問題: {問題描述}
   - 方案: {重構方案}
   - 預期效果: {效果描述}

### 優點

- {優點1}
- {優點2}

### 結論

- **可以合併**: {是/否/需修改後}
- **必須修改**: {列表}
- **建議修改**: {列表}
```

---

## 使用方式

### 審查單一檔案

```bash
/cognitive-review {檔案路徑}
```

### 審查 PR 變更

```bash
/cognitive-review pr {PR 編號}
```

### 快速掃描

```bash
/cognitive-review scan {目錄}
```

---

## 常見問題模式

### 模式 1：函式過長

**識別**：函式超過 20 行

**常見原因**：
- 混合多個責任
- 缺乏抽象層

**改善方法**：
1. 識別獨立的邏輯區塊
2. 提取為私有方法
3. 命名要說明「做什麼」

### 模式 2：深層巢狀

**識別**：超過 3 層縮排

**常見原因**：
- 多層條件判斷
- 迴圈內的條件

**改善方法**：
1. 使用早期返回（Guard Clause）
2. 提取內層邏輯為函式
3. 考慮策略模式

### 模式 3：模糊命名

**識別**：使用 data, info, value, result 等詞

**常見原因**：
- 趕時間隨意命名
- 不確定用途

**改善方法**：
1. 問「這個變數存放什麼？」
2. 用具體名詞回答
3. 加入領域詞彙

### 模式 4：隱藏副作用

**識別**：函式名稱是查詢，但會修改狀態

**常見原因**：
- 「順便」修改狀態
- 缺乏命令-查詢分離

**改善方法**：
1. 分離查詢和命令
2. 命名反映副作用
3. 減少副作用範圍

---

## 相關文件

- [認知負擔量化標準]($CLAUDE_PROJECT_DIR/.claude/skills/cognitive-load-assessment/thresholds.md)
- [認知負擔設計方法論]($CLAUDE_PROJECT_DIR/.claude/methodologies/cognitive-load-design-methodology.md)
- [自然語言程式設計方法論]($CLAUDE_PROJECT_DIR/.claude/methodologies/natural-language-programming-methodology.md)
- [程式碼品質門檻方法論]($CLAUDE_PROJECT_DIR/.claude/methodologies/code-smell-quality-gate-methodology.md)

---

**Last Updated**: 2026-01-23
**Version**: 1.0.0