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    → 可以安全提交嗎？

 1# hooks/pre_commit.py
 2def run_git_command(cmd):
 3    result = subprocess.run(cmd, capture_output=True, text=True)
 4    return result.stdout.strip()
 5
 6# hooks/post_merge.py -- 完全相同的程式碼
 7def run_git_command(cmd):
 8    result = subprocess.run(cmd, capture_output=True, text=True)
 9    return result.stdout.strip()
10
11# hooks/branch_check.py -- 又是一模一樣
12# hooks/worktree_guardian.py -- 第四份...

1def parse_worktree_line(line):
2    if line.startswith("worktree "):
3        return line[9:]  # 三個月後，你還記得 9 是什麼嗎？

 1# 一個 800+ 行的 Hook 檔案
 2PROTECTED_BRANCHES = ["main", "master", "develop"]
 3ALLOWED_PATTERNS = ["feat/*", "fix/*", "chore/*"]
 4ERROR_MESSAGES = {
 5    "branch_not_allowed": "分支名稱不符合規範",
 6    "missing_ticket": "缺少 Ticket 引用",
 7    # ... 數十行配置繼續
 8}
 9
10def check_branch():
11    # 真正的邏輯只有幾十行，卻埋在幾百行配置之下
12    pass

 1# 修正前：logger 是全域變數，所有函式都看得到
 2logger = setup_hook_logging("hook-name")
 3
 4def helper_function():
 5    logger.info("doing something")  # OK，全域可見
 6
 7def main():
 8    result = helper_function()
 9
10# 修正後：logger 搬進 main()，但 helper 沒收到通知
11def helper_function():
12    logger.info("doing something")  # NameError! logger 不見了
13
14def main():
15    logger = setup_hook_logging("hook-name")  # 現在是區域變數
16    result = helper_function()  # helper 找不到 logger

 1# 偵測 IMP-001：找出重複的函式定義
 2grep -rh "^def " hooks/*.py | sort | uniq -c | sort -rn | head -10
 3#  4 def run_git_command(cmd):    <-- 出現 4 次，高度疑似重複
 4#  2 def parse_output(line):      <-- 出現 2 次，需要確認
 5
 6# 偵測 IMP-002：找出魔法數字
 7grep -rn -E "\[[0-9]+:\]" hooks/*.py      # 數字切片 [9:]
 8grep -rn "sleep([0-9]" hooks/*.py        # 硬編碼的等待時間
 9grep -rn "range([0-9]" hooks/*.py        # 硬編碼的迴圈次數
10
11# 偵測 ARCH-001：找出超長檔案
12find hooks/ -name "*.py" -exec wc -l {} \; | awk '$1 > 500'
13# 847 hooks/user_prompt_submit.py    <-- 紅色警報
14
15# 偵測 IMP-005：模組遷移後殘留的舊 Import
16grep -rn "from common_functions import" hooks/*.py
17# 如果 common_functions.py 已經搬到 lib/，這些都是未更新的引用

 1import ast
 2import sys
 3
 4def find_scope_references(filename, variable_name):
 5    """找出所有在非 main 函式中引用特定變數的位置。
 6    限制：此函式只做名稱比對，無法追蹤賦值或閉包捕獲。"""
 7    with open(filename) as f:
 8        tree = ast.parse(f.read())
 9
10    issues = []
11    for node in ast.walk(tree):
12        if isinstance(node, ast.FunctionDef) and node.name != "main":
13            param_names = {arg.arg for arg in node.args.args}
14            if variable_name in param_names:
15                continue  # 函式已接收此變數為參數，非問題
16            for child in ast.walk(node):
17                if isinstance(child, ast.Name) and child.id == variable_name:
18                    issues.append(f"  {node.name}() 在第 {child.lineno} 行引用 {variable_name}")
19                    break
20    return issues
21
22# 使用方式
23issues = find_scope_references("hooks/pre_commit.py", "logger")
24for issue in issues:
25    print(issue)

 1# py_compile：語法 OK 不代表能跑
 2python3 -m py_compile hooks/pre_commit.py  # 通過！但 logger 根本找不到
 3
 4# pylint：能抓到更多問題
 5pylint hooks/pre_commit.py
 6# E0602: Undefined variable 'logger' (undefined-variable)
 7
 8# 實際執行：最可靠的驗證
 9python3 hooks/pre_commit.py < /dev/null
10# NameError: name 'logger' is not defined

 1問題：單一 Hook 檔案超過 800 行，其中約一半是硬編碼的配置資料
 2
 3Why 1: 為什麼檔案會有 800 行？
 4--> 因為配置資料（分支規則、錯誤訊息、檔案模式）和程式邏輯
 5    全部寫在同一個檔案中
 6
 7Why 2: 為什麼配置和邏輯放在一起？
 8--> 因為開發時為求快速，直接在程式碼中定義配置常數
 9
10Why 3: 為什麼選擇快速做法而非分離？
11--> 因為缺乏配置管理策略，沒有標準化的做法可以遵循
12
13Why 4: 為什麼沒有配置管理策略？
14--> 因為 Hook 系統初期設計時，只考慮了功能實現，
15    沒有考慮到配置會不斷增長
16
17Why 5: 為什麼初期設計沒考慮配置增長？
18--> 【根本原因】缺乏明確的架構原則指導配置與程式碼分離

1.claude/error-patterns/
2├── README.md              # 系統說明與索引
3├── test/                  # 測試相關：TEST-001, TEST-002, ...
4├── documentation/         # 文件相關：DOC-001, DOC-002, ...
5├── architecture/          # 架構相關：ARCH-001, ARCH-002, ...
6└── implementation/        # 實作相關：IMP-001, IMP-002, ...

 1# [Pattern ID]: [簡短標題]
 2
 3## 基本資訊
 4
 5- **Pattern ID**: {CATEGORY}-{NNN}
 6- **風險等級**: 高/中/低
 7- **發現日期**: YYYY-MM-DD
 8
 9## 問題描述
10
11### 症狀
12
13[用程式碼範例展示問題的外在表現]
14
15### 根本原因 (5 Why 分析)
16
171. Why 1: ...
182. Why 2: ...
193. Why 3: ...
204. Why 4: ...
215. Why 5: (根本原因)
22
23## 解決方案
24
25### 正確做法
26
27[程式碼範例]
28
29### 錯誤做法 (避免)
30
31[程式碼範例]
32
33## 檢測方法
34
35[grep 指令、AST 腳本或工具配置]

 1發現壞味道
 2    |
 3    v
 4影響正確性嗎？（會導致 Bug）
 5    |
 6    +-- 是 --> 立即修復，建立 Ticket
 7    |
 8    +-- 否 --> 影響多個檔案嗎？
 9                |
10                +-- 是 --> 記錄 Error Pattern + 建立 Ticket
11                |
12                +-- 否 --> 認知負擔高嗎？（函式超長、巢狀太深）
13                            |
14                            +-- 是 --> 排入下次重構
15                            |
16                            +-- 否 --> 記錄，暫不處理

 1BRANCH_RULES = {
 2    "protected": ["main", "master"],
 3    "max_length": 50,
 4    "patterns": ["feat/*", "fix/*", "chore/*"],
 5}
 6
 7def check(data):
 8    res = []
 9    for i in range(len(data)):
10        if data[i]["type"] == "A":
11            if data[i]["status"] == 1:
12                if data[i]["value"] > 100:
13                    res.append(data[i]["name"][5:])
14    return res

1# hooks/pre_commit.py
2def run_git_command(cmd):
3    result = subprocess.run(cmd, capture_output=True, text=True)
4    return result.stdout.strip()
5
6# hooks/post_merge.py  -- 完全相同
7# hooks/branch_check.py  -- 完全相同
8# hooks/worktree_guardian.py  -- 完全相同

1# 找出重複的函式定義
2grep -rh "^def " .claude/hooks/*.py | sort | uniq -c | sort -rn | head -20
3
4# 範例輸出：
5#    4 def run_git_command(cmd):
6#    3 def get_current_branch():
7#    2 def parse_worktree_line(line):

1.claude/lib/
2├── __init__.py           # 公開介面
3├── git_utils.py          # Git 操作
4├── config_loader.py      # 配置載入
5├── hook_io.py            # 輸入輸出
6└── hook_logging.py       # 日誌系統

 1# lib/git_utils.py
 2"""Git 操作工具模組。"""
 3
 4import subprocess
 5from pathlib import Path
 6from typing import List, Optional
 7
 8def run_git_command(
 9    cmd: List[str],
10    cwd: Optional[Path] = None,
11    check: bool = False
12) -> str:
13    """執行 Git 命令並回傳輸出。
14
15    Args:
16        cmd: Git 命令列表，例如 ["git", "status"]
17        cwd: 工作目錄，預設為當前目錄
18        check: 是否在命令失敗時拋出異常
19    """
20    result = subprocess.run(
21        cmd, capture_output=True, text=True, cwd=cwd, check=check
22    )
23    return result.stdout.strip()
24
25def get_current_branch(cwd: Optional[Path] = None) -> str:
26    """取得當前分支名稱。"""
27    return run_git_command(["git", "branch", "--show-current"], cwd=cwd)

1# hooks/pre_commit.py（重構後）
2from lib.git_utils import run_git_command, get_current_branch
3
4def check_branch():
5    current_branch = get_current_branch()
6    # 使用共用函式，不再重複定義

 1# 重構前：三個檔案各自的版本
 2# hooks/file_a.py
 3def parse_worktree_line(line):
 4    return line[9:]                        # 不 strip
 5
 6# hooks/file_b.py
 7def parse_worktree_line(line):
 8    return line[9:].strip()                # 有 strip
 9
10# hooks/file_c.py
11def parse_worktree_line(line):
12    return line.removeprefix("worktree ")  # 用 Python 3.9+ API
13
14# 重構後：統一實作，支援選項
15WORKTREE_PREFIX = "worktree "
16
17def parse_worktree_line(line: str, strip: bool = True) -> str:
18    """解析 worktree 輸出行。"""
19    result = line.removeprefix(WORKTREE_PREFIX)
20    return result.strip() if strip else result

 1from pathlib import Path
 2from typing import Callable
 3
 4# 重構前
 5def check_all_python_files():
 6    for file in Path(".").glob("**/*.py"):
 7        if validate_python(file): print(f"OK: {file}")
 8
 9def check_all_yaml_files():
10    for file in Path(".").glob("**/*.yaml"):
11        if validate_yaml(file): print(f"OK: {file}")
12
13# 重構後
14def check_files(pattern: str, validator: Callable[[Path], bool]) -> None:
15    for file in Path(".").glob(pattern):
16        if validator(file): print(f"OK: {file}")
17
18check_files("**/*.py", validate_python)
19check_files("**/*.yaml", validate_yaml)

 1# === 步驟 1：替換 import ===
 2# 遷移前
 3from lib.common_functions import setup_hook_logging
 4# 遷移後
 5from hook_utils import setup_hook_logging
 6
 7# === 步驟 2：包裹主函式 ===
 8# 遷移前
 9if __name__ == "__main__":
10    try:
11        main()
12    except Exception as e:
13        logger.error(f"執行失敗: {e}")
14        sys.exit(1)
15# 遷移後
16from hook_utils import run_hook_safely
17if __name__ == "__main__":
18    sys.exit(run_hook_safely(main, "my-hook"))
19
20# === 步驟 3：驗證 ===
21uv run python hook-name.py < /dev/null

1# 遷移前（同目錄）
2from common_functions import hook_output  # OK
3
4# 遷移後（模組移到 lib/，但 import 未更新）
5from common_functions import hook_output  # ModuleNotFoundError!
6
7# 正確的遷移後 import
8from lib.common_functions import hook_output  # OK

1# 1. 列出所有引用舊路徑的檔案
2grep -r "from common_functions import" .claude/hooks/*.py
3
4# 2. 逐一更新每個引用者的 import 路徑
5
6# 3. 逐一驗證（不能只跑其中幾個！）
7for f in .claude/hooks/*.py; do
8    uv run python "$f" < /dev/null 2>&1 | grep -q "Error" && echo "FAIL: $f"
9done

1try:
2    from hook_utils import setup_hook_logging
3except ImportError as e:
4    print(f"[Hook Import Error] {Path(__file__).name}: {e}", file=sys.stderr)
5    sys.exit(1)

 1# file1.py
 2def process_user_data(user):
 3    if not user.get("name"):
 4        return {"error": "缺少姓名"}
 5    if not user.get("email"):
 6        return {"error": "缺少信箱"}
 7    return {"success": True, "data": user}
 8
 9# file2.py
10def process_order_data(order):
11    if not order.get("product"):
12        return {"error": "缺少商品"}
13    if not order.get("quantity"):
14        return {"error": "缺少數量"}
15    return {"success": True, "data": order}

1def parse_worktree_line(line: str) -> str:
2    if line.startswith("worktree "):
3        return line[9:]  # 為什麼是 9？
4    return line
5
6if len(branch) > 50:    # 為什麼是 50？
7    raise Error("分支名稱過長")
8
9time.sleep(3)           # 為什麼等 3 秒？

1WORKTREE_PREFIX = "worktree "
2
3def parse_worktree_line(line: str) -> str:
4    if line.startswith(WORKTREE_PREFIX):
5        return line[len(WORKTREE_PREFIX):]
6    return line

1WORKTREE_PREFIX = "worktree "
2
3def parse_worktree_line(line: str) -> str:
4    return line.removeprefix(WORKTREE_PREFIX)

 1from enum import IntEnum
 2
 3class Limits(IntEnum):
 4    MAX_BRANCH_LENGTH = 50
 5    MAX_COMMIT_MSG_LENGTH = 72
 6    MAX_RETRIES = 3
 7    TIMEOUT_SECONDS = 30
 8
 9if len(branch) > Limits.MAX_BRANCH_LENGTH:
10    raise ValueError("分支名稱過長")

1if count == 0:               # 可接受：0 在布林邏輯中
2if text.find("key") == -1:   # 可接受：-1 作為找不到的標記
3half = total / 2              # 可接受：明顯的數學常數

 1# user_prompt_submit.py (847 行，配置佔 400+)
 2PROTECTED_BRANCHES = ["main", "master", "develop"]
 3ALLOWED_PATTERNS = ["feat/*", "fix/*", "chore/*"]
 4ERROR_MESSAGES = {
 5    "branch_not_allowed": "分支名稱不符合規範",
 6    "missing_ticket": "缺少 Ticket 引用",
 7    # ... 數百行配置
 8}
 9
10def main():
11    # 實際邏輯只有 200 行
12    pass

1# file1.py
2PROTECTED_BRANCHES = ["main", "master"]
3# file2.py
4PROTECTED_BRANCHES = ["main", "master", "develop"]  # 多了 develop！

 1# config/branch_rules.yaml
 2protected_branches:
 3  - main
 4  - master
 5  - develop
 6
 7allowed_patterns:
 8  - "feat/*"
 9  - "fix/*"
10  - "chore/*"
11
12error_messages:
13  branch_not_allowed: "分支名稱不符合規範"
14  missing_ticket: "缺少 Ticket 引用"

 1# lib/config_loader.py
 2from pathlib import Path
 3from typing import Any, Dict
 4import yaml
 5
 6_config_cache: Dict[str, Any] = {}
 7
 8def load_config(filename: str) -> Dict[str, Any]:
 9    """載入 YAML 配置檔案（含快取）。"""
10    if filename in _config_cache:
11        return _config_cache[filename]
12
13    config_path = Path(__file__).parent.parent / "config" / filename
14    if not config_path.exists():
15        raise FileNotFoundError(f"配置檔案不存在: {config_path}")
16
17    with open(config_path, "r", encoding="utf-8") as f:
18        config = yaml.safe_load(f)
19
20    _config_cache[filename] = config
21    return config

1from lib.config_loader import load_config
2
3def check_branch():
4    config = load_config("branch_rules.yaml")
5    if current_branch in config["protected_branches"]:
6        print(f"錯誤: {config['error_messages']['branch_not_allowed']}")
7        return False
8    return True

1# 錯誤：這是邏輯，不是資料
2process_steps:
3  - name: "validate"
4    function: "validate_input"

1timeout = config["timeout"]        # KeyError!
2timeout = config.get("timeout", 30)  # 正確

1# hook_a.py
2print("錯誤：未找到待處理的 Ticket")
3print("建議執行 /ticket create 建立新 Ticket")
4
5# hook_b.py
6print("錯誤：未找到待處理的 Ticket")  # 同一訊息，略有不同
7print("請先建立 Ticket 再執行")

 1# lib/hook_messages.py
 2class CoreMessages:
 3    """Hook 執行通用訊息 - 所有 Hook 共用"""
 4    HOOK_START = "{hook_name} 啟動"
 5    INPUT_EMPTY = "輸入為空，預設允許"
 6    JSON_PARSE_ERROR = "JSON 解析錯誤，預設允許: {error}"
 7
 8class GateMessages:
 9    """Gate Hook 阻擋訊息 - 5 個 gate hooks 使用"""
10    TICKET_NOT_FOUND_ERROR = """錯誤：未找到待處理的 Ticket
11建議: 執行 /ticket create 建立新 Ticket"""
12
13    TICKET_NOT_CLAIMED_ERROR = """錯誤：Ticket {ticket_id} 尚未認領
14建議: 執行 /ticket track claim {ticket_id} 認領"""
15
16class WorkflowMessages:
17    """工作流指導訊息 - 5 個工作流 hooks 使用"""
18    PRE_FIX_EVAL_REQUIRED = """[強制] 修復前評估
19  1. 執行 /pre-fix-eval
20  2. 派發 incident-responder 分析"""

1from lib.hook_messages import GateMessages
2
3def validate_ticket(ticket_id: str):
4    if not is_claimed(ticket_id):
5        print(GateMessages.TICKET_NOT_CLAIMED_ERROR.format(
6            ticket_id=ticket_id
7        ))
8        return False
9    return True

 1發現硬編碼
 2    |
 3    v
 4會隨環境改變？ ─是→ YAML 配置檔
 5    |
 6    否
 7    v
 8是使用者看到的文字？ ─是→ Messages 類別
 9    |
10    否
11    v
12是無法理解的數字？ ─是→ 具名常數 / len() / removeprefix()
13    |
14    否
15    v
16保留原樣（程式邏輯的一部分）

 1def validate_branch(branch):
 2    if len(branch) > 50:
 3        return False
 4    if branch.startswith("refs/heads/"):
 5        branch = branch[11:]
 6    for i in range(3):
 7        if check_remote(branch):
 8            return True
 9        time.sleep(2)
10    return False

 1MAX_BRANCH_LENGTH = 50
 2REFS_HEADS_PREFIX = "refs/heads/"
 3MAX_RETRIES = 3
 4RETRY_DELAY_SECONDS = 2
 5
 6def validate_branch(branch: str) -> bool:
 7    """驗證分支名稱。"""
 8    if len(branch) > MAX_BRANCH_LENGTH:
 9        return False
10    branch = branch.removeprefix(REFS_HEADS_PREFIX)
11    for attempt in range(MAX_RETRIES):
12        if check_remote(branch):
13            return True
14        time.sleep(RETRY_DELAY_SECONDS)
15    return False

1# 找出數字切片（潛在魔法數字）
2grep -rn "\[[0-9]*:\]" hooks/*.py
3
4# 找出 sleep 和 range 中的硬編碼
5grep -rn "sleep([0-9]" hooks/*.py
6grep -rn "range([0-9]" hooks/*.py
7
8# 找出硬編碼中文字串（潛在散落訊息）
9grep -rn '[一-龥]' hooks/*.py

 1def process_hook_result(result_line):
 2    if result_line.startswith("status: "):
 3        status = result_line[8:]
 4    else:
 5        status = "unknown"
 6
 7    if len(status) > 100:
 8        print("狀態文字過長，已截斷")
 9        status = status[:97] + "..."
10
11    VALID_STATUSES = ["pass", "fail", "skip", "error"]
12    if status not in VALID_STATUSES:
13        print("無效的狀態值: " + status)
14        return None
15    return status

 1# Hook A：用 common_functions 的 setup_hook_logging
 2from lib.common_functions import setup_hook_logging
 3logger = setup_hook_logging("hook-a")
 4
 5# Hook B：用 hook_logging 的 setup_hook_logging（不同模組，同名函式）
 6from lib.hook_logging import setup_hook_logging
 7logger = setup_hook_logging("hook-b")
 8
 9# Hook C：直接用 logging 模組
10import logging
11logging.basicConfig(level=logging.INFO)
12logger = logging.getLogger(__name__)
13
14# Hook D：print 大法
15def log(msg):
16    print(f"[hook-d] {msg}")

11. 建立統一介面    → 寫一個所有人都要用的模組
22. 漸進式遷移      → 逐批將現有 Hook 切換到新介面
33. 驗證           → 確認行為一致
44. 處理例外       → 處理少數無法直接遷移的情況

 1# hook_utils.py — 統一日誌模組
 2
 3def setup_hook_logging(hook_name: str) -> logging.Logger:
 4    """建立並設定 Hook 日誌系統
 5
 6    - 建立日誌目錄 .claude/hook-logs/{hook_name}/
 7    - 建立帶時間戳的日誌檔案
 8    - 配置 FileHandler + StreamHandler
 9    """
10
11def run_hook_safely(main_func: Callable[[], int], hook_name: str) -> int:
12    """安全執行 Hook 函式，頂層例外處理
13
14    - 呼叫 setup_hook_logging 取得 logger
15    - 執行 main_func，捕獲所有 Exception
16    - 異常時記錄完整 traceback，返回 1
17    """

 1def setup_hook_logging(hook_name: str) -> logging.Logger:
 2    sanitized_name = _sanitize_hook_name(hook_name)
 3    root_dir = _find_project_root()
 4    log_base_dir = root_dir / ".claude" / "hook-logs" / sanitized_name
 5
 6    try:
 7        log_base_dir.mkdir(parents=True, exist_ok=True)
 8    except OSError:
 9        return _create_fallback_logger(hook_name)
10
11    logger = logging.getLogger(hook_name)
12    _clear_logger_handlers(logger)
13    logger.setLevel(logging.DEBUG)
14
15    is_debug = os.getenv("HOOK_DEBUG", "").lower() == "true"
16    _setup_logger_handlers(logger, log_base_dir, sanitized_name, is_debug)
17
18    return logger

1# 重構前：每個 Hook 自己處理
2if __name__ == "__main__":
3    try:
4        result = main()
5        sys.exit(result)
6    except Exception as e:
7        # 有的寫日誌，有的 print，有的什麼都不做
8        print(f"Error: {e}")
9        sys.exit(1)

1# 重構後：一行搞定
2if __name__ == "__main__":
3    sys.exit(run_hook_safely(main, "acceptance-gate"))

1# command-entrance-gate-hook.py
2print("錯誤：未找到待處理的 Ticket\n建議操作: 執行 /ticket create")
3
4# acceptance-gate-hook.py
5print("[ERROR] 子任務未全部完成\nTicket: {}\n請先完成所有子任務")
6
7# main-thread-edit-restriction-hook.py
8print("編輯操作受限")

 1# lib/hook_messages.py
 2
 3class CoreMessages:
 4    """所有 Hook 共用的通用訊息"""
 5    HOOK_START = "{hook_name} 啟動"
 6    INPUT_EMPTY = "輸入為空，預設允許"
 7    JSON_PARSE_ERROR = "JSON 解析錯誤，預設允許: {error}"
 8
 9class GateMessages:
10    """5 個 Gate Hook 的阻擋/警告訊息"""
11    TICKET_NOT_FOUND_ERROR = """錯誤：未找到待處理的 Ticket
12
13    為什麼阻止執行：
14      開發命令必須有對應的 Ticket，確保工作可追蹤和驗收。
15
16    建議操作:
17      1. 執行 /ticket create 建立新 Ticket
18      2. 或執行 /ticket track claim {id} 認領現有 Ticket"""
19
20class WorkflowMessages:
21    """工作流指導 Hook 的訊息"""
22    EXTERNAL_QUERY_DETECTED = "檢測到 {tool_name} 調用"
23
24class QualityMessages:
25    """品質檢查 Hook 的訊息"""
26    # ...

1# 重構前
2print("錯誤：未找到待處理的 Ticket\n建議操作: ...")
3
4# 重構後
5from lib.hook_messages import GateMessages
6print(GateMessages.TICKET_NOT_FOUND_ERROR)

1# 帶參數的訊息
2print(GateMessages.TICKET_NOT_CLAIMED_ERROR.format(ticket_id="0.31.0-W2-001"))

 1# 風格 A：模組級初始化（13 個 Hook）
 2logger = setup_hook_logging("my-hook")  # 最外層
 3
 4def helper():
 5    logger.info("working...")           # 引用全域 logger
 6
 7def main():
 8    helper()
 9    return 0
10
11# 風格 B：main() 內初始化（3 個 Hook）
12def helper(logger):
13    logger.info("working...")           # 接收 logger 參數
14
15def main():
16    logger = setup_hook_logging("my-hook")
17    helper(logger)
18    return 0

1# 修改後（有 bug）
2def check_acceptance_criteria(ticket_path):
3    logger.info(f"Checking {ticket_path}")  # NameError!
4
5def main():
6    logger = setup_hook_logging("acceptance-gate-hook")
7    result = check_acceptance_criteria(path)

1def check_acceptance_criteria(ticket_path, logger):  # 加入參數
2    logger.info(f"Checking {ticket_path}")
3
4def main():
5    logger = setup_hook_logging("acceptance-gate-hook")
6    result = check_acceptance_criteria(path, logger)  # 傳遞 logger

 1#!/usr/bin/env python3
 2"""Hook 說明文件"""
 3
 4import sys
 5import json
 6from pathlib import Path
 7
 8# 引入統一基礎設施
 9# Hook 不是安裝的套件，需要手動把 hooks/ 目錄加入 Python 搜尋路徑
10# 這樣才能 import 同目錄下的 hook_utils 和 lib/ 子模組
11_hooks_dir = Path(__file__).parent
12if _hooks_dir not in [p for p in sys.path if Path(p) == _hooks_dir]:
13    sys.path.insert(0, str(_hooks_dir))
14
15from hook_utils import run_hook_safely, setup_hook_logging
16from lib.hook_messages import GateMessages, CoreMessages
17
18# 常數定義
19EXIT_SUCCESS = 0
20EXIT_BLOCK = 2
21
22# ---- 業務邏輯 ----
23
24def check_something(data, logger):
25    """每個 helper 都接收 logger 參數"""
26    logger.info(CoreMessages.HOOK_START.format(hook_name="my-hook"))
27    # ...
28
29def main():
30    logger = setup_hook_logging("my-hook")
31    # 讀取輸入、執行檢查、輸出結果
32    return EXIT_SUCCESS
33
34# ---- 入口 ----
35if __name__ == "__main__":
36    sys.exit(run_hook_safely(main, "my-hook"))

1錯誤路徑：邊改邊用 → 半成品狀態 → 新舊混合更亂
2正確路徑：新模組獨立完成 → 逐批遷移 → 舊模組標記棄用

11. 先確認安全網（stderr 輸出、測試覆蓋）
22. 再執行風險操作（作用域修改）
33. 最後清理（移除棄用程式碼）

 1# 風格 A：模組級初始化（13 個 Hook 使用）
 2logger = setup_hook_logging("my-hook")  # 在最外層
 3
 4def helper():
 5    logger.info("working...")  # OK：logger 是全域變數
 6
 7def main():
 8    helper()
 9    logger.info("done")
10    return 0
11
12# 風格 B：main() 內初始化（已有部分 Hook 使用）
13def helper(logger):
14    logger.info("working...")  # OK：logger 是參數
15
16def main():
17    logger = setup_hook_logging("my-hook")  # 在 main() 內
18    helper(logger)
19    logger.info("done")
20    return 0

 1# 修改前
 2logger = setup_hook_logging("acceptance-gate-hook")
 3
 4def check_acceptance_criteria(ticket_path):
 5    logger.info(f"Checking {ticket_path}")  # OK
 6    # ...
 7
 8def validate_ticket_format(content):
 9    logger.info("Validating format")  # OK
10    # ...
11
12def main():
13    result = check_acceptance_criteria(path)
14    # ...
15
16# 修改後（有 bug）
17def check_acceptance_criteria(ticket_path):
18    logger.info(f"Checking {ticket_path}")  # NameError!
19    # ...
20
21def validate_ticket_format(content):
22    logger.info("Validating format")  # NameError!
23    # ...
24
25def main():
26    logger = setup_hook_logging("acceptance-gate-hook")  # 區域變數
27    result = check_acceptance_criteria(path)
28    # ...

1L - Local      : 函式內部
2E - Enclosing  : 外層函式（閉包）
3G - Global     : 模組級
4B - Built-in   : Python 內建

 1# 修改前：logger 在 G（Global）
 2logger = setup_hook_logging("hook")  # Global scope
 3
 4def helper():
 5    logger.info("...")  # L 找不到 → E 找不到 → G 找到了
 6
 7# 修改後：logger 在 main 的 L（Local）
 8def helper():
 9    logger.info("...")  # L 找不到 → E 找不到 → G 找不到 → NameError!
10
11def main():
12    logger = setup_hook_logging("hook")  # main 的 Local scope
13    helper()  # helper 無法存取 main 的 Local

 1def run_hook_safely(main_func, hook_name):
 2    logger = setup_hook_logging(hook_name)
 3    try:
 4        exit_code = main_func()
 5    except (KeyboardInterrupt, SystemExit):
 6        raise
 7    except Exception:
 8        tb_str = traceback.format_exc()
 9        _log_exception(logger, hook_name, tb_str)
10        return EXIT_ERROR  # 返回錯誤碼，但不會 crash

11. main() 被 run_hook_safely 呼叫
22. main() 內呼叫 check_acceptance_criteria()
33. check_acceptance_criteria() 引用 logger → NameError
44. NameError 是 Exception 的子類別
55. run_hook_safely 捕獲，寫入日誌檔案
66. 返回 EXIT_ERROR（整數 1）
77. Hook 系統收到非零退出碼 → 顯示 "hook success"（suppressOutput）
88. 用戶看不到任何異常

 1# 用 AST 分析找出所有引用 logger 的非 main 函式
 2python3 -c "
 3import ast, sys
 4
 5tree = ast.parse(open(sys.argv[1]).read())
 6for node in ast.walk(tree):
 7    if isinstance(node, ast.FunctionDef) and node.name != 'main':
 8        for child in ast.walk(node):
 9            if isinstance(child, ast.Name) and child.id == 'logger':
10                print(f'  {node.name}() references logger')
11                break
12" acceptance-gate-hook.py

1  check_acceptance_criteria() references logger
2  validate_ticket_format() references logger
3  check_worklog_sections() references logger
4  ... (共 11 個函式)

1def check_acceptance_criteria(ticket_path, logger):  # 加入 logger 參數
2    logger.info(f"Checking {ticket_path}")
3    # ...
4
5def validate_ticket_format(content, logger):  # 加入 logger 參數
6    logger.info("Validating format")
7    # ...

1def main():
2    logger = setup_hook_logging("acceptance-gate-hook")
3    result = check_acceptance_criteria(path, logger)  # 傳遞 logger
4    validate_ticket_format(content, logger)            # 傳遞 logger
5    return 0

 1# AST 驗證：確認沒有函式在引用全域 logger
 2python3 -c "
 3import ast, sys
 4
 5tree = ast.parse(open(sys.argv[1]).read())
 6issues = []
 7for node in ast.walk(tree):
 8    if isinstance(node, ast.FunctionDef) and node.name != 'main':
 9        params = {arg.arg for arg in node.args.args}
10        if 'logger' not in params:
11            for child in ast.walk(node):
12                if isinstance(child, ast.Name) and child.id == 'logger':
13                    issues.append(node.name)
14                    break
15if issues:
16    print(f'FAIL: {issues} still reference global logger')
17else:
18    print('PASS: all functions receive logger as parameter')
19" acceptance-gate-hook.py

1python3 -m py_compile acceptance-gate-hook.py
2# 通過！沒有任何錯誤