cognitive-load-assessment

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

SKILL.md

GitHub

認知負擔評估與審查工具

核心理念

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

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

使用方式

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

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

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


與其他方法論的關係

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

使用方式

評估任務複雜度

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

程式碼品質評估

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

相關文件


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