1# 高認知負擔的程式碼
2def process(d):
3    r = []
4    for i in d:
5        if i[0] > 0 and i[1] != "" and len(i) >= 3:
6            t = i[0] * 2 + len(i[1])
7            if t > 10:
8                r.append((i[2], t))
9    return sorted(r, key=lambda x: x[1], reverse=True)

1Clean Code 的真正目標是：讓程式碼能被人類輕鬆理解

 1# 高認知負擔：需要記住 data 經歷了什麼轉換
 2data = get_raw_data()
 3data = filter_invalid(data)
 4data = normalize(data)
 5data = enrich(data)
 6result = aggregate(data)
 7
 8# 低認知負擔：每步都有清晰的命名
 9raw_data = get_raw_data()
10valid_data = filter_invalid(raw_data)
11normalized_data = normalize(valid_data)
12enriched_data = enrich(normalized_data)
13result = aggregate(enriched_data)

 1# 高認知負擔：temp 到底是什麼？
 2temp = user_input.strip()
 3temp = temp.lower()
 4temp = temp.replace(" ", "_")
 5temp = re.sub(r'[^a-z_]', '', temp)
 6
 7# 低認知負擔：每個變數都說明自己是什麼
 8trimmed_input = user_input.strip()
 9lowercase_input = trimmed_input.lower()
10underscored_input = lowercase_input.replace(" ", "_")
11clean_identifier = re.sub(r'[^a-z_]', '', underscored_input)

 1# 高認知負擔：process() 會修改什麼？
 2class DataProcessor:
 3    def process(self):
 4        self._validate()      # 可能修改 self.errors?
 5        self._transform()     # 可能修改 self.data?
 6        self._save()          # 可能修改 self.saved?
 7
 8# 低認知負擔：回傳值明確說明結果
 9class DataProcessor:
10    def process(self) -> ProcessResult:
11        errors = self._validate(self.data)
12        if errors:
13            return ProcessResult(success=False, errors=errors)
14
15        transformed = self._transform(self.data)
16        save_result = self._save(transformed)
17        return ProcessResult(success=True, saved_path=save_result)

1# 高認知負擔：需要跳到 MAGIC_VALUE 的定義
2if score > MAGIC_VALUE:
3    return "pass"
4
5# 低認知負擔：直接說明意圖
6PASSING_SCORE_THRESHOLD = 60
7if score > PASSING_SCORE_THRESHOLD:
8    return "pass"

 1# 不好：需要記住 user 是什麼
 2def process(user):
 3    if user[0] and user[1] > 18:
 4        return user[2]
 5
 6# 好：當下就能理解
 7def get_adult_user_name(user: User) -> Optional[str]:
 8    if user.is_active and user.age > 18:
 9        return user.name
10    return None

1# 不好：需要註解才能理解
2# 檢查用戶是否有權限
3if u.r >= 3 and u.s == 'a':
4    pass
5
6# 好：程式碼本身就是說明
7if user.role_level >= ADMIN_LEVEL and user.status == UserStatus.ACTIVE:
8    pass

 1# 不好：get 通常不應該修改狀態
 2def get_user_count(self):
 3    self._refresh_cache()  # 意外的副作用！
 4    return len(self._users)
 5
 6# 好：get 只做讀取
 7def get_user_count(self) -> int:
 8    return len(self._users)
 9
10def refresh_and_get_user_count(self) -> int:
11    self._refresh_cache()
12    return len(self._users)

 1def check_hook(path):
 2    with open(path) as f:
 3        c = f.read()
 4
 5    # 檢查 shebang
 6    if not c.startswith("#!"):
 7        return False, "no shebang"
 8
 9    # 解析配置
10    import yaml
11    cfg = yaml.safe_load(open(".claude/config.yaml"))
12
13    # 驗證
14    for h in cfg.get("hooks", []):
15        if h.get("path") == str(path):
16            if not os.path.exists(path):
17                return False, "not found"
18            if not os.access(path, os.X_OK):
19                return False, "not executable"
20            return True, "ok"
21
22    return False, "not registered"

 1from lib.config_loader import load_hook_config
 2from lib.hook_validator import validate_hook_file
 3
 4def check_hook(hook_path: Path) -> tuple[bool, str]:
 5    """
 6    檢查指定的 Hook 檔案是否有效。
 7
 8    Returns:
 9        (是否有效, 訊息)
10    """
11    # 載入配置
12    config = load_hook_config()
13
14    # 檢查是否已註冊
15    if not config.is_registered(hook_path):
16        return False, "Hook 未在配置中註冊"
17
18    # 驗證檔案
19    validation_result = validate_hook_file(hook_path)
20
21    return validation_result.is_valid, validation_result.message

1# 可以像故事一樣閱讀的程式碼
2user_submitted_form = receive_form_submission(request)
3validated_data = validate_form_data(user_submitted_form)
4save_to_database(validated_data)

1# 需要解謎的程式碼
2d = get(r)
3v = check(d)
4save(v)

1# 轉換敘事
2raw_input = read_user_input()
3cleaned_input = sanitize(raw_input)
4formatted_output = format_for_display(cleaned_input)

 1# 壞：過於簡短，無法理解
 2d = get_data()
 3t = time.time()
 4r = []
 5i = 0
 6
 7# 壞：過於通用，無法區分
 8data = get_user_data()
 9data2 = get_order_data()
10temp = process(data)
11result = combine(temp, data2)
12
13# 壞：誤導性的名稱
14user_list = get_user()  # 實際上回傳單一用戶，不是列表！

 1# 好：說明「這是什麼」
 2user_profile = get_user_profile(user_id)
 3current_timestamp = time.time()
 4validated_items = []
 5item_index = 0
 6
 7# 好：能區分不同用途
 8user_data = get_user_data()
 9order_data = get_order_data()
10merged_report = merge_user_and_orders(user_data, order_data)
11
12# 好：名稱和實際內容一致
13active_user = get_active_user()  # 單數名稱，回傳單一用戶
14active_users = get_active_users()  # 複數名稱，回傳列表

1# 不好：名稱說明來源
2config_from_yaml = load_config()
3user_after_validation = validate(user)
4
5# 好：名稱說明內容
6app_config = load_config()
7valid_user = validate(user)

1# 不好：不清楚是什麼意思
2user_status = True
3file_check = False
4
5# 好：讀起來像問句的答案
6is_user_active = True      # "Is user active?" - Yes
7has_valid_license = False  # "Has valid license?" - No
8can_edit_document = True   # "Can edit document?" - Yes
9should_retry = False       # "Should retry?" - No

1# 不好：不清楚是單一還是多個
2user = get_all_users()  # 回傳列表，但名稱是單數
3user_list = get_user()  # 回傳單一用戶，但名稱暗示列表
4
5# 好：名稱反映結構
6users = get_all_users()           # 複數 = 列表
7user = get_user(user_id)          # 單數 = 單一物件
8user_ids = get_all_user_ids()     # 複數 + 型別提示
9user_id_to_name = build_user_map()  # 說明映射關係

 1# 壞：動詞太模糊
 2def process(data):
 3    pass
 4
 5def handle(request):
 6    pass
 7
 8def do_something(item):
 9    pass
10
11def manage_users():
12    pass
13
14# 壞：不清楚會做什麼
15def user_operation(user, action):
16    pass
17
18def data_stuff(d):
19    pass

 1# 好：清楚說明動作和目標
 2def validate_user_input(user_input: str) -> ValidationResult:
 3    pass
 4
 5def extract_branch_name(git_output: str) -> str:
 6    pass
 7
 8def format_error_message(error: Exception) -> str:
 9    pass
10
11def calculate_total_price(items: list[OrderItem]) -> Decimal:
12    pass

 1# 不好：名稱洩漏實作細節
 2def loop_through_and_sum(numbers):
 3    pass
 4
 5def use_regex_to_find_emails(text):
 6    pass
 7
 8# 好：名稱說明意圖
 9def calculate_sum(numbers):
10    pass
11
12def extract_email_addresses(text):
13    pass

 1# 好：對稱的命名
 2def open_connection():
 3    pass
 4
 5def close_connection():
 6    pass
 7
 8# 好：對稱的命名
 9def start_processing():
10    pass
11
12def stop_processing():
13    pass
14
15# 不好：不對稱
16def open_connection():
17    pass
18
19def disconnect():  # 應該是 close_connection
20    pass

1# 高認知負擔版本
2d = fetch()
3d = clean(d)
4d = transform(d)
5r = aggregate(d)

1# 低認知負擔版本
2raw_data = fetch_user_data()
3cleaned_data = remove_invalid_entries(raw_data)
4normalized_data = normalize_formats(cleaned_data)
5report = generate_summary_report(normalized_data)

 1# 需要追溯 4 步
 2x = get_data()      # 第 1 步
 3x = process(x)      # 第 2 步
 4x = filter(x)       # 第 3 步
 5result = format(x)  # 第 4 步：x 到底是什麼？
 6
 7# 不需要追溯
 8raw_data = get_data()
 9processed_data = process(raw_data)
10filtered_data = filter(processed_data)
11formatted_output = format(filtered_data)  # 直接看名稱就知道是過濾後的資料

 1# 重構前（高認知負擔）
 2def check(p):
 3    c = open(p).read()
 4    if c.startswith("#!"):
 5        l = c.split("\n")
 6        if len(l) > 1:
 7            return l[1].startswith("# -*- coding")
 8    return False
 9
10# 重構後（低認知負擔）
11def has_valid_python_header(file_path: Path) -> bool:
12    """檢查 Python 檔案是否有有效的檔頭"""
13    file_content = file_path.read_text()
14
15    has_shebang = file_content.startswith("#!")
16    if not has_shebang:
17        return False
18
19    lines = file_content.split("\n")
20    has_encoding_declaration = (
21        len(lines) > 1 and
22        lines[1].startswith("# -*- coding")
23    )
24
25    return has_encoding_declaration

 1class ReportGenerator:
 2    def generate(self, report_type: str, data: dict) -> str:
 3        if report_type == "pdf":
 4            # 100 行 PDF 生成邏輯
 5            return self._generate_pdf(data)
 6        elif report_type == "excel":
 7            # 80 行 Excel 生成邏輯
 8            return self._generate_excel(data)
 9        elif report_type == "html":
10            # 60 行 HTML 生成邏輯
11            return self._generate_html(data)
12        else:
13            raise ValueError(f"Unknown report type: {report_type}")

 1from abc import ABC, abstractmethod
 2
 3class ReportFormatter(ABC):
 4    """報告格式化器的抽象介面"""
 5
 6    @abstractmethod
 7    def format(self, data: dict) -> str:
 8        """將資料格式化為報告"""
 9        pass
10
11class PdfFormatter(ReportFormatter):
12    def format(self, data: dict) -> str:
13        # PDF 生成邏輯
14        pass
15
16class ExcelFormatter(ReportFormatter):
17    def format(self, data: dict) -> str:
18        # Excel 生成邏輯
19        pass
20
21class HtmlFormatter(ReportFormatter):
22    def format(self, data: dict) -> str:
23        # HTML 生成邏輯
24        pass
25
26class ReportGenerator:
27    def __init__(self, formatter: ReportFormatter):
28        self._formatter = formatter
29
30    def generate(self, data: dict) -> str:
31        return self._formatter.format(data)

1class CsvFormatter(ReportFormatter):
2    def format(self, data: dict) -> str:
3        # CSV 生成邏輯
4        pass
5
6# 使用
7generator = ReportGenerator(CsvFormatter())
8report = generator.generate(data)

 1# 違反 SRP：一個類別做太多事
 2class UserManager:
 3    def create_user(self, data):
 4        # 驗證邏輯
 5        # 資料庫操作
 6        # 發送歡迎郵件
 7        # 記錄日誌
 8        pass
 9
10    def delete_user(self, user_id):
11        # 權限檢查
12        # 資料庫操作
13        # 清理關聯資料
14        # 發送通知
15        # 記錄日誌
16        pass

 1# 遵循 SRP：每個類別只做一件事
 2class UserValidator:
 3    def validate(self, data: dict) -> ValidationResult:
 4        pass
 5
 6class UserRepository:
 7    def create(self, user: User) -> User:
 8        pass
 9
10    def delete(self, user_id: str) -> bool:
11        pass
12
13class EmailService:
14    def send_welcome_email(self, user: User) -> None:
15        pass
16
17class UserService:
18    def __init__(
19        self,
20        validator: UserValidator,
21        repository: UserRepository,
22        email_service: EmailService
23    ):
24        self._validator = validator
25        self._repository = repository
26        self._email_service = email_service
27
28    def create_user(self, data: dict) -> User:
29        validation = self._validator.validate(data)
30        if not validation.is_valid:
31            raise ValidationError(validation.errors)
32
33        user = self._repository.create(User.from_dict(data))
34        self._email_service.send_welcome_email(user)
35        return user

 1# 難以命名 = 職責不單一
 2class UserStuffManager:  # "stuff" 說明不知道它具體做什麼
 3    pass
 4
 5class DataProcessorAndValidator:  # "and" 說明做了兩件事
 6    pass
 7
 8class HelperUtils:  # "helper/utils" 說明是雜項收集
 9    pass
10
11# 容易命名 = 職責單一
12class UserAuthenticator:  # 清楚：處理用戶認證
13    pass
14
15class ConfigurationLoader:  # 清楚：載入配置
16    pass
17
18class EmailFormatter:  # 清楚：格式化郵件
19    pass

 1# .claude/lib/config_loader.py
 2class ConfigLoader:
 3    """
 4    單一職責：載入和快取配置檔案
 5
 6    不負責：
 7    - 驗證配置內容
 8    - 使用配置執行操作
 9    - 修改配置
10    """
11
12    def __init__(self, config_path: Path):
13        self._config_path = config_path
14        self._cache: Optional[dict] = None
15
16    def load(self) -> dict:
17        """載入配置，使用快取避免重複讀取"""
18        if self._cache is None:
19            self._cache = self._read_config()
20        return self._cache
21
22    def _read_config(self) -> dict:
23        with open(self._config_path) as f:
24            return yaml.safe_load(f)

 1# .claude/lib/parsers/base.py
 2class LanguageParser(ABC):
 3    """語言解析器的抽象介面"""
 4
 5    @abstractmethod
 6    def parse(self, content: str) -> ParseResult:
 7        pass
 8
 9    @abstractmethod
10    def get_supported_extensions(self) -> list[str]:
11        pass
12
13# .claude/lib/parsers/python_parser.py
14class PythonParser(LanguageParser):
15    def parse(self, content: str) -> ParseResult:
16        # Python 解析邏輯
17        pass
18
19    def get_supported_extensions(self) -> list[str]:
20        return [".py"]
21
22# .claude/lib/parsers/factory.py
23class ParserFactory:
24    """
25    對擴展開放：新增語言只需實作 LanguageParser
26    對修改封閉：不需要修改此工廠類別
27    """
28
29    _parsers: dict[str, type[LanguageParser]] = {}
30
31    @classmethod
32    def register(cls, parser_class: type[LanguageParser]) -> None:
33        for ext in parser_class.get_supported_extensions():
34            cls._parsers[ext] = parser_class
35
36    @classmethod
37    def get_parser(cls, file_extension: str) -> LanguageParser:
38        parser_class = cls._parsers.get(file_extension)
39        if parser_class is None:
40            raise UnsupportedLanguageError(file_extension)
41        return parser_class()

 1# .claude/lib/parsers/dart_parser.py
 2class DartParser(LanguageParser):
 3    def parse(self, content: str) -> ParseResult:
 4        # Dart 解析邏輯
 5        pass
 6
 7    def get_supported_extensions(self) -> list[str]:
 8        return [".dart"]
 9
10# 註冊（可在初始化時自動完成）
11ParserFactory.register(DartParser)

1認知負擔指數 = 變數數 + 分支數 + 巢狀深度 + 依賴數

1# 在專案根目錄執行
2grep -h "^def " .claude/hooks/*.py | sort | uniq -c | sort -rn | head -5

1# 假設你想把這段程式碼抽成函式
2if len(result.stdout.strip()) > 0:
3    branches = result.stdout.strip().split("\n")
4    branches = [b.strip() for b in branches if b.strip()]
5    protected = [b for b in branches if b in ["main", "master"]]

1# 錯誤的工作流程
2commit: "修復 #42 並重構 git_utils"  ← 兩件事混在一個 commit
3
4# 正確的工作流程
5commit: "修復 #42：branch 名稱解析的空字串處理"
6commit: "重構 git_utils：抽取 parse_branch_name 函式"

1建立模組    →  寫測試    →  確認測試通過
2config_loader    4 個測試
3git_utils        6 個測試
4hook_io          3 個測試
5hook_logging     2 個測試

1# 重構前：硬編碼在 Python 中
2AGENTS = {
3    "parsley-flutter-developer": {"type": "implementation", "lang": "dart"},
4    "thyme-python-developer": {"type": "implementation", "lang": "python"},
5    # ... 15 個代理人定義散落在程式碼中
6}
7
8# 重構後：讀取 YAML 配置
9agents = config_loader.load_config("agents.yaml")

1Wave 1: 共用模組（被所有 Hook 依賴）
2    ↓
3Wave 2: 配置檔（被 task-dispatch 依賴）
4    ↓
5Wave 3: Hook 檔案（依賴共用模組和配置檔）
6    ↓
7Wave 4: 驗證（依賴所有修改完成）

 1Step 1: 畫出依賴關係圖
 2    → 哪些模組被其他模組依賴？（先做）
 3    → 哪些模組互相獨立？（可以並行）
 4
 5Step 2: 分類修改類型
 6    → 機械性修改：統一命名、統一格式、統一匯入
 7    → 邏輯修改：改變函式行為、改變資料流、改變作用域
 8
 9Step 3: 分配到 Wave
10    → Wave N: 基礎設施（被依賴的、獨立的）
11    → Wave N+1: 機械性修改（依賴基礎設施）
12    → Wave N+2: 邏輯修改（依賴前面的修改）
13    → Wave N+3: 驗證與清理
14
15Step 4: 每個 Wave 定義驗證標準
16    → 哪些測試必須通過？
17    → 程式碼能正常執行嗎？
18    → 可以安全提交嗎？

1parallel-dispatch.md     280 行  ← 原本是「什麼時候可以並行」的簡單指南
2task-splitting.md        230 行  ← 原本是「怎麼拆任務」的清單
3ticket-lifecycle.md      220 行  ← 原本是「Ticket 狀態怎麼轉」的流程
4version-progression.md   180 行  ← 原本是「什麼時候推進版本」的判斷
5incident-response.md     170 行  ← 原本是「出錯了怎麼辦」的流程
6query-vs-research.md     130 行  ← 原本是「查資料要不要派人」的二選一
7plan-to-ticket.md        100 行  ← 原本是「計畫怎麼變成 Ticket」的流程
8decision-tree.md         452 行  ← 核心決策樹，每次都在「補一個分支」

1# 精簡前
2parallel-dispatch.md (280 行，所有內容混在一起)
3
4# 精簡後
5parallel-dispatch.md (98 行，決策入口 + 強制規則)
6  └→ references/parallel-dispatch-details.md (剩餘細節，按需查閱)

1## 並行派發後驗證（強制）
2
3所有並行代理人回報完成後，**必須**執行 `git diff --stat` 驗證。
4
5> 詳細驗證步驟和常見原因：.claude/references/parallel-dispatch-details.md

 1# 精簡前 (170 行)
 2
 3## 強制流程
 4（流程圖 + 說明）
 5
 6## 強制觸發條件
 7（觸發表格）
 8
 9## 派發對應表
10（代理人對應表）
11
12## 多視角分析原則             ← Level 3
13（詳細的分析方法論）
14
15## 安全等級分類               ← Level 3
16（安全等級表格 + 處理流程）
17
18## 報告格式範例               ← Level 3
19（完整的報告模板）
20
21## 禁止行為
22（禁止清單）

 1# 精簡後 (64 行)
 2
 3## 強制流程
 4（流程圖 + 說明）
 5
 6## 強制觸發條件
 7（觸發表格）
 8
 9## 派發對應表
10（代理人對應表）
11
12## 禁止行為
13（禁止清單）
14
15## 相關文件
16> 詳細規則：.claude/references/incident-response-details.md

1Level 0: 快查表（一眼就能找到答案）
2Level 1: 強制規則（必須遵守的約束）
3Level 2: 決策流程（判斷邏輯）
4Level 3: 參考細節（範例、模板、歷史記錄）

 1# Level 0: 函式簽名（一眼就知道做什麼）
 2def can_dispatch_parallel(tasks: list[Task]) -> bool:
 3    # Level 1: Guard clauses（強制規則）
 4    if len(tasks) < 2:
 5        return False
 6    if has_dependency(tasks):
 7        return False
 8
 9    # Level 2: 核心邏輯（判斷邏輯）
10    return not has_file_overlap(tasks)
11
12# Level 3: 實作細節（在被呼叫的函式裡）
13def has_file_overlap(tasks):
14    # 50 行的具體實作...

1# 文件行數統計
2wc -l .claude/rules/flows/*.md .claude/rules/guides/*.md
3
4# 前後對比
5echo "精簡前: 1310 行"
6echo "精簡後:  483 行"
7echo "縮減率: 63%"

1# 錯誤：過度精簡
2## 並行派發
3> 詳見：references/parallel-dispatch-details.md
4
5## 任務拆分
6> 詳見：references/task-splitting-details.md

1程式碼的品質 ≠ 優美
2程式碼的品質 = 易讀