Claude-skill-registry cognitive-load

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

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/cognitive-load-assessment" ~/.claude/skills/majiayu000-claude-skill-registry-cognitive-load && rm -rf "$T"

manifest: skills/data/cognitive-load-assessment/SKILL.md

認知負擔評估工具

核心理念

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

認知負擔是指閱讀者在理解程式碼時需要同時記住的資訊量。當認知負擔超過人類工作記憶的容量（約 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 時

新程式碼是否增加了模組的複雜度？
有沒有更簡單的方式達成同樣目的？
命名是否清晰自說明？
是否需要額外註解才能理解？（應該不需要）

與其他方法論的關係

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

使用方式

評估任務複雜度

# 在開始任務前，快速評估
# 回答以下問題：

1. 這個任務需要修改幾個檔案？
2. 需要追蹤幾個變數狀態？
3. 跨越幾個架構層級？
4. 依賴幾個其他模組？

# 如果任一項超過閾值，考慮拆分任務

程式碼品質評估

# 在 Code Review 時，檢查：

1. 函式長度（應 5-15 行）
2. 參數數量（應 <= 3）
3. 巢狀深度（應 <= 3）
4. 變數數量（應 < 5）