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. 最後清理（移除棄用程式碼）