Agent skill

cognitive-load-assessment

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

View SKILL.md on GitHub Repository
Stars 1
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/tarrragon/claude/tree/main/skills/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 時

  • 函式長度 <= 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 {檔案路徑}

相關文件

  • 認知負擔量化標準 - 詳細閾值參考
  • Code Review 報告模板 - 完整審查報告格式
  • 常見 Review 問題模式 - 熱點識別和改善方法
  • 認知負擔設計方法論 - 完整理論基礎
  • 自然語言程式設計方法論 - 命名最佳實踐
  • 任務拆分指南 - 拆分方法

Last Updated: 2026-03-02 Version: 2.0.0 - 合併 cognitive-load-review，新增 Code Review 模式和 references/

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

tarrragon/claude

skill-design-guide

Use this skill when creating a new skill, updating an existing skill's YAML frontmatter, or reviewing skill quality. Provides the official Anthropic skill specification, frontmatter rules, description writing best practices, progressive disclosure architecture, and common pitfalls to avoid. Triggers include: creating skills, skill review, frontmatter validation, SKILL.md writing.

1 0
Explore
tarrragon/claude

test-async-guardian

Flutter/Dart 測試異步資源管理守護者。用於：(1) 診斷測試卡住問題，(2) 審查測試程式碼中的異步資源清理，(3) 提供 tearDown 最佳實踐，(4) 掃描潛在的資源洩漏風險。觸發場景：測試卡住、撰寫新測試、Code Review 測試程式碼、執行 flutter test 前自動掃描。

1 0
Explore
tarrragon/claude

agent-team

Agent Teams 協作派發指南。Use when: (1) Agent A 的發現會改變 Agent B 正在進行的工作, (2) 用戶要求使用 team/swarm, (3) 多代理人需即時協商共用介面或 API 契約。涵蓋 team 建立、Ticket-Task 橋接、teammate 入職、生命週期管理。

1 0
Explore
tarrragon/claude

tdd

TDD 全流程指導工具。Use for: (1) 開始新功能的 TDD 流程（Phase 0-4）, (2) 推進到下一個 TDD 階段, (3) Phase 1 SOLID 原則驅動功能拆分分析, (4) 查看當前 TDD 進度和階段狀態, (5) 評估是否需要 Phase 4 重構以及 3b 拆分評估。Use when: 開始新功能開發、進入任何 TDD Phase、需要 SOLID 拆分指導、需要確認當前所在 TDD 階段、需要做 Phase 4 豁免判斷時。

1 0
Explore
tarrragon/claude

branch-worktree-guardian

Branch Worktree Guardian - Git 分支和 Worktree 管理工具。Use for: (1) 新開發需求時建立隔離分支, (2) 使用 worktree 機制避免分支衝突, (3) 驗證當前工作分支正確性, (4) 預防在錯誤分支上開發

1 0
Explore
tarrragon/claude

design-decision-framework

多方案評估決策框架。用於面臨 3+ 技術方案時的結構化評估、架構決策時的系統化分析，防止衝動決策和技術債務累積。Use for: 技術方案選擇、重大架構決策、高風險技術選型

1 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results