# Cognitive Load Assessment

> 認知負擔評估與審查工具。作為決策樹、代理人、Code Review 的基本參考標準。用於: (1) 任務複雜度評估, (2) 代理人升級判斷, (3) 任務拆分建議, (4) 程式碼品質審查與熱點識別

- Skill: `tarrragon/cognitive-load-assessment` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add tarrragon/cognitive-load-assessment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tarrragon/cognitive-load-assessment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tarrragon (https://skillmd.com/u/tarrragon)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tarrragon/cognitive-load-assessment

---


# 認知負擔評估與審查工具

## 核心理念

> **所有程式碼設計原則的終極目標：降低閱讀者的認知負擔**

認知負擔是指閱讀者在理解程式碼時需要**同時記住**的資訊量。當認知負擔超過人類工作記憶的容量（約 7 個項目），理解和維護程式碼就會變得困難。

---

## 量化標準快速參考

### 任務複雜度閾值

| 指標 | 低複雜度 | 中複雜度 | 高複雜度（需拆分） |
|------|---------|---------|------------------|
| 變數狀態數 | 1-3 | 4-5 | > 5 |
| 修改檔案數 | 1-3 | 4-5 | > 5 |
| 架構層級數 | 1 | 2 | > 2 |
| 依賴模組數 | 0-1 | 2-3 | > 3 |
| 呼叫追蹤層 | 1-2 | 3 | > 3 |

### 代理人升級閾值

| 指標 | 閾值 | 行動 |
|------|------|------|
| 需追蹤概念數 | > 7 | 升級到 PM |
| 無法 5 分鐘理解 | 是 | 升級到 PM |
| 跨 2+ 架構層 | 是 | 請求拆分或協作 |

### 並行派發判斷

| 條件 | 可並行 | 需序列 |
|------|--------|--------|
| 架構層級 | 同一層 | 跨層 |
| 邏輯依賴 | 無 | 有 |
| 操作類型 | 重命名/格式化 | 設計變更 |

---

## 認知負擔的來源

### 1. 變數狀態追蹤

每個變數都是閱讀者需要「記住」的項目：

| 情況 | 認知負擔 | 建議 |
|------|---------|------|
| 變數數 <= 3 | 低 | 維持 |
| 變數數 4-5 | 中 | 考慮重構 |
| 變數數 > 5 | 高 | 必須拆分 |

### 2. 呼叫層級追蹤

追蹤呼叫鏈需要「堆疊」記憶：

| 層級 | 認知負擔 | 建議 |
|------|---------|------|
| 1-2 層 | 低 | 維持 |
| 3 層 | 中 | 考慮扁平化 |
| > 3 層 | 高 | 必須重構 |

### 3. 命名品質

不佳的命名增加「翻譯」負擔：

| 問題 | 範例 | 解決 |
|------|------|------|
| 縮寫不明 | `btn`, `mgr`, `idx` | `button`, `manager`, `index` |
| 含義模糊 | `data`, `info`, `value` | 具體化：`userData`, `bookInfo` |
| 型別前綴 | `strName`, `intCount` | 直接用 `name`, `count` |

### 4. 條件分支複雜度

每個分支都是需要考慮的「路徑」：

| 分支數 | 認知負擔 | 建議 |
|--------|---------|------|
| 1-2 | 低 | 維持 |
| 3-4 | 中 | 考慮策略模式 |
| > 4 | 高 | 必須重構 |

---

## 降低認知負擔的原則

### 原則 1：單一責任

> 一個函式只做一件事，讓讀者只需理解一個概念

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

### 原則 2：自說明命名

> 名稱本身就是文件，讓讀者不需要額外資訊

檢查問題：「不看實作，能從名稱理解功能嗎？」

### 原則 3：避免副作用

> 函式的行為應該可預測，讓讀者不需要追蹤隱藏狀態

檢查問題：「這個函式有沒有修改輸入以外的東西？」

### 原則 4：扁平化結構

> 減少巢狀，讓讀者不需要追蹤深層上下文

檢查問題：「最深的巢狀層級是多少？（應 <= 3）」

### 原則 5：資訊就近原則

> 相關的資訊應該放在一起，讓讀者不需要跳轉尋找

檢查問題：「理解這段程式碼需要跳到幾個地方？」

---

## 自我檢查清單

### 任務開始前

- [ ] 我需要同時記住多少個概念？（應 < 7）
- [ ] 我需要閱讀多少個檔案才能完成？（應 < 5）
- [ ] 我能用一句話說明這個任務嗎？
- [ ] 5 分鐘後我還記得任務目標嗎？

### 程式碼撰寫時

- [ ] 這個函式需要追蹤幾個變數？（應 < 5）
- [ ] 讀者能在當下理解這段程式碼嗎？
- [ ] 函式名稱說明「做什麼」而非「怎麼做」？
- [ ] 巢狀層級是否超過 3 層？

### Code Review 時

- [ ] 函式長度 <= 20 行
- [ ] 參數數量 <= 3
- [ ] 巢狀深度 <= 3
- [ ] 區域變數數 < 5
- [ ] 函式名稱是動詞片語，函式只做一件事
- [ ] 類別方法數 <= 12，公開方法數 <= 5
- [ ] 命名無縮寫或僅使用業界通用縮寫
- [ ] 布林變數是 is/has/can 開頭
- [ ] 不使用 data/info/value 等模糊詞
- [ ] 新程式碼是否增加了模組的複雜度？
- [ ] 有沒有更簡單的方式達成同樣目的？

---

## Code Review 模式

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

### 審查維度

| 維度 | 檢查問題 |
|------|---------|
| 變數狀態追蹤 | 這段程式碼需要閱讀者同時記住幾個變數的狀態？ |
| 呼叫層級追蹤 | 理解這段程式碼需要追蹤幾層呼叫？ |
| 命名品質 | 不看實作，能從名稱理解意圖嗎？ |
| 條件分支 | 需要考慮幾條執行路徑？ |
| 函式長度 | 這個函式做了幾件事？ |
| 參數數量 | 呼叫者需要記住幾個參數的順序和意義？ |

### 熱點識別

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

### 使用方式

```bash
# 審查單一檔案
/cognitive-load-assessment review {檔案路徑}

# 快速掃描目錄
/cognitive-load-assessment scan {目錄}
```

詳細報告模板：`references/review-report-template.md`
常見問題模式：`references/common-review-patterns.md`

---

## 與其他方法論的關係

| 方法論 | 認知負擔視角 |
|--------|-------------|
| DRY | 減少重複 = 減少需要記憶的版本 |
| SOLID | 每個原則都在降低特定類型的認知負擔 |
| Clean Code | 可讀性 = 低認知負擔 |
| 自然語言程式設計 | 讓程式碼像閱讀文章一樣自然 |

---

## 使用方式

### 評估任務複雜度

```bash
/cognitive-load-assessment assess-task "{任務描述}"
```

### 程式碼品質評估

```bash
/cognitive-load-assessment assess-code {檔案路徑}
```

---

## 相關文件

- [認知負擔量化標準](./thresholds.md) - 詳細閾值參考
- [Code Review 報告模板](./references/review-report-template.md) - 完整審查報告格式
- [常見 Review 問題模式](./references/common-review-patterns.md) - 熱點識別和改善方法
- [認知負擔設計方法論](.claude/methodologies/cognitive-load-design-methodology.md) - 完整理論基礎
- [自然語言程式設計方法論](.claude/methodologies/natural-language-programming-methodology.md) - 命名最佳實踐
- [任務拆分指南](.claude/pm-rules/task-splitting.md) - 拆分方法

---

版本紀錄在同目錄的 `CHANGELOG.md`。