1# modules/database/monitoring.tf — 跟 database 資源同一個 module
 2resource "aws_cloudwatch_log_group" "db_slow_query" {
 3  name              = "/rds/${var.env}/${var.db_identifier}/slowquery"
 4  retention_in_days = var.log_retention_days
 5  kms_key_id        = var.log_kms_key_arn
 6}
 7
 8resource "aws_cloudwatch_metric_alarm" "db_cpu" {
 9  alarm_name          = "${var.env}-${var.db_identifier}-cpu-high"
10  comparison_operator = "GreaterThanThreshold"
11  evaluation_periods  = 3
12  metric_name         = "CPUUtilization"
13  namespace           = "AWS/RDS"
14  period              = 300
15  statistic           = "Average"
16  threshold           = 80
17  alarm_actions       = [var.oncall_sns_arn]
18
19  dimensions = {
20    DBInstanceIdentifier = aws_db_instance.primary.identifier
21  }
22}

1# 列出所有 RDS instance，比對有沒有對應的 CloudWatch alarm
2aws rds describe-db-instances \
3  --query 'DBInstances[].DBInstanceIdentifier' --output text | tr '\t' '\n' | while read db; do
4  count=$(aws cloudwatch describe-alarms \
5    --alarm-name-prefix "${db}" --query 'MetricAlarms | length(@)')
6  echo "${db}: ${count} alarms"
7done

 1resource "aws_cloudwatch_log_group" "api" {
 2  name              = "/app/${var.env}/api"
 3  retention_in_days = var.env == "prod" ? 30 : 7
 4  kms_key_id        = aws_kms_key.logs.arn
 5}
 6
 7resource "aws_cloudwatch_log_group" "audit" {
 8  name              = "/app/${var.env}/audit"
 9  retention_in_days = 365
10  kms_key_id        = aws_kms_key.logs.arn
11}

 1# 只允許 oncall role 讀取 prod log
 2data "aws_iam_policy_document" "log_read" {
 3  statement {
 4    actions   = ["logs:GetLogEvents", "logs:FilterLogEvents"]
 5    resources = [aws_cloudwatch_log_group.api.arn]
 6  }
 7}
 8
 9resource "aws_iam_role_policy" "oncall_log_read" {
10  role   = var.oncall_role_name
11  policy = data.aws_iam_policy_document.log_read.json
12}

 1# 症狀型 alarm：5xx 超過閾值代表使用者已受影響
 2resource "aws_cloudwatch_metric_alarm" "api_5xx" {
 3  alarm_name          = "${var.env}-api-5xx-rate"
 4  comparison_operator = "GreaterThanThreshold"
 5  evaluation_periods  = 3
 6  metric_name         = "5XXError"
 7  namespace           = "AWS/ApiGateway"
 8  period              = 60
 9  statistic           = "Sum"
10  threshold           = 10
11  treat_missing_data  = "notBreaching"
12  alarm_actions       = [var.oncall_sns_arn]
13}
14
15# 成因型指標：CPU 放 dashboard、不設 alarm
16# 除非確認「CPU 到 X% 一定代表服務即將不可用」這個因果關係

1resource "aws_sns_topic" "oncall" {
2  name = "${var.env}-oncall-alerts"
3}
4
5resource "aws_sns_topic_subscription" "pagerduty" {
6  topic_arn = aws_sns_topic.oncall.arn
7  protocol  = "https"
8  endpoint  = var.pagerduty_integration_url
9}

 1# modules/service/variables.tf
 2variable "alarm_5xx_threshold" {
 3  type    = number
 4  default = 10
 5}
 6
 7variable "alarm_latency_p99_ms" {
 8  type    = number
 9  default = 3000
10}

1[conn] Step 1/5: biometric auth completed (duration: 320ms)
2[conn] Step 2/5: credential loaded (user: admin)
3[conn] Step 3/5: WebSocket connected (url: wss://...)
4[conn] Step 4/5: auth token sent
5[conn] Step 5/5: stream subscribed, ready

1[proto] TX: text frame, payload: {"AuthToken":"base64..."} (42 bytes)
2[proto] RX: text frame, payload prefix: "0" (output data, 128 bytes)
3[proto] TX: binary frame, payload: [72, 101, 108, 108, 111] (5 bytes)

1[ui] screen: HomeScreen, action: tap Connect Terminal
2[ui] screen: TerminalScreen, state: connecting → connected
3[ui] screen: TerminalScreen, action: tap back button
4[ui] screen: HomeScreen, state: returned from terminal

1Client (Flutter) → HTTP POST /log → Go receiver → JSON file → grep/jq

1developer.log('WS connected', name: 'ConnectionManager');

1developer.log('auth token sent');

1logger.Info(
2    "event accepted",
3    "layer", "adapter",
4    "event_type", string(event.Type),
5    "event_id", event.ID,
6    "subject_id", event.SubjectID,
7    "correlation_id", event.CorrelationID,
8)

 1func LogAttrsForEvent(event DomainEvent) []any {
 2    return []any{
 3        "event_id", event.ID,
 4        "event_type", string(event.Type),
 5        "subject_kind", string(event.SubjectKind),
 6        "subject_id", event.SubjectID,
 7        "correlation_id", event.CorrelationID,
 8        "schema_version", event.SchemaVersion,
 9    }
10}

1logger.Info("event accepted", LogAttrsForEvent(event)...)

1const (
2    ReasonInvalidPayload = "invalid_payload"
3    ReasonQueueFull      = "queue_full"
4    ReasonDuplicateEvent = "duplicate_event"
5    ReasonTimeout        = "timeout"
6)

1logger.Warn(
2    "event rejected",
3    "layer", "adapter",
4    "reason", ReasonInvalidPayload,
5    "event_type", string(event.Type),
6    "error", err,
7)

1type EventLog interface {
2    Append(ctx context.Context, event DomainEvent) error
3}

 1type InMemoryEventLog struct {
 2    mu     sync.Mutex
 3    events []DomainEvent
 4}
 5
 6func NewInMemoryEventLog() *InMemoryEventLog {
 7    return &InMemoryEventLog{}
 8}
 9
10func (l *InMemoryEventLog) Append(ctx context.Context, event DomainEvent) error {
11    l.mu.Lock()
12    defer l.mu.Unlock()
13
14    l.events = append(l.events, cloneDomainEvent(event))
15    return nil
16}

1func cloneDomainEvent(event DomainEvent) DomainEvent {
2    cloned := event
3    if event.Payload != nil {
4        cloned.Payload = append(json.RawMessage(nil), event.Payload...)
5    }
6    return cloned
7}

 1func (l *InMemoryEventLog) List() []DomainEvent {
 2    l.mu.Lock()
 3    defer l.mu.Unlock()
 4
 5    result := make([]DomainEvent, len(l.events))
 6    for i, event := range l.events {
 7        result[i] = cloneDomainEvent(event)
 8    }
 9    return result
10}

1type JobRepository interface {
2    Apply(ctx context.Context, event DomainEvent) error
3    Get(ctx context.Context, id string) (JobProjection, bool, error)
4}

 1type RecordingEventProcessor struct {
 2    eventLog   EventLog
 3    repository JobRepository
 4    logger     *slog.Logger
 5}
 6
 7func (p *RecordingEventProcessor) Process(ctx context.Context, event DomainEvent) error {
 8    if err := p.eventLog.Append(ctx, event); err != nil {
 9        return fmt.Errorf("append event log: %w", err)
10    }
11
12    if err := p.repository.Apply(ctx, event); err != nil {
13        return fmt.Errorf("apply state projection: %w", err)
14    }
15
16    p.logger.Info("event processed", LogAttrsForEvent(event)...)
17    return nil
18}

1logger.Warn(
2    "callback rejected",
3    "layer", "adapter",
4    "reason", ReasonInvalidPayload,
5    "payload_bytes", len(body),
6)

1logger.Debug(
2    "payload received",
3    "payload_bytes", len(body),
4    "payload_sha256", sha256Hex(body),
5)

 1func TestLogAttrsForEvent(t *testing.T) {
 2    event := DomainEvent{
 3        ID:            "evt_1",
 4        Type:          EventNotificationCreated,
 5        SubjectKind:   SubjectNotification,
 6        SubjectID:     "ntf_1",
 7        CorrelationID: "corr_1",
 8        SchemaVersion: 1,
 9    }
10
11    attrs := LogAttrsForEvent(event)
12    got := attrsToMap(attrs)
13
14    if got["event_id"] != "evt_1" {
15        t.Fatalf("event_id = %v, want evt_1", got["event_id"])
16    }
17    if got["event_type"] != string(EventNotificationCreated) {
18        t.Fatalf("event_type = %v, want %s", got["event_type"], EventNotificationCreated)
19    }
20}

 1func attrsToMap(attrs []any) map[string]any {
 2    result := make(map[string]any)
 3    for i := 0; i+1 < len(attrs); i += 2 {
 4        key, ok := attrs[i].(string)
 5        if !ok {
 6            continue
 7        }
 8        result[key] = attrs[i+1]
 9    }
10    return result
11}

 1func TestInMemoryEventLogAppendCopiesPayload(t *testing.T) {
 2    log := NewInMemoryEventLog()
 3    payload := json.RawMessage(`{"topic":"deployments"}`)
 4
 5    event := DomainEvent{
 6        ID:            "evt_1",
 7        Type:          EventNotificationCreated,
 8        SubjectKind:   SubjectNotification,
 9        SubjectID:     "ntf_1",
10        OccurredAt:    time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC),
11        ReceivedAt:    time.Date(2026, 4, 22, 10, 1, 0, 0, time.UTC),
12        SchemaVersion: 1,
13        Payload:       payload,
14    }
15
16    if err := log.Append(context.Background(), event); err != nil {
17        t.Fatalf("append event: %v", err)
18    }
19
20    payload[0] = '['
21
22    events := log.List()
23    if string(events[0].Payload) != `{"topic":"deployments"}` {
24        t.Fatalf("payload was modified through original slice")
25    }
26}

 1# 使用 print 的問題
 2print("Processing started")        # 無法控制輸出等級
 3print(f"Error: {error}")          # 無法區分一般訊息和錯誤
 4print("Debug: x =", x)            # 生產環境也會輸出
 5
 6# 使用 logging 的好處
 7import logging
 8logger = logging.getLogger(__name__)
 9
10logger.info("Processing started")   # 可以控制等級
11logger.error(f"Error: {error}")    # 明確標示為錯誤
12logger.debug(f"x = {x}")           # 只在 DEBUG 模式輸出

 1import logging
 2import os
 3from datetime import datetime
 4from pathlib import Path
 5from typing import Optional
 6
 7
 8def setup_hook_logging(
 9    hook_name: str,
10    log_subdir: Optional[str] = None,
11    log_level: Optional[int] = None,
12    include_stderr: bool = False
13) -> logging.Logger:
14    """
15    設定 Hook 日誌系統
16
17    Args:
18        hook_name: Hook 名稱，用於識別日誌來源
19        log_subdir: 日誌子目錄，預設為 hook_name
20        log_level: 日誌等級，預設根據環境變數決定
21        include_stderr: 是否同時輸出到 stderr
22
23    Returns:
24        logging.Logger: 配置好的 Logger 實例
25    """
26    # 決定日誌等級
27    if log_level is None:
28        debug_mode = os.getenv("HOOK_DEBUG", "").lower() == "true"
29        log_level = logging.DEBUG if debug_mode else logging.INFO
30
31    # 建立 Logger
32    logger = logging.getLogger(hook_name)
33    logger.setLevel(log_level)
34
35    # 避免重複添加 handler
36    if logger.handlers:
37        return logger
38
39    # 建立日誌目錄
40    project_root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
41    subdir = log_subdir or hook_name
42    log_dir = Path(project_root) / ".claude" / "hook-logs" / subdir
43    log_dir.mkdir(parents=True, exist_ok=True)
44
45    # 日誌檔案路徑
46    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
47    log_file = log_dir / f"{hook_name}-{timestamp}.log"
48
49    # 設定 formatter
50    formatter = logging.Formatter(
51        "[%(asctime)s] %(levelname)s - %(message)s",
52        datefmt="%Y-%m-%d %H:%M:%S"
53    )
54
55    # 檔案 handler
56    file_handler = logging.FileHandler(log_file, encoding="utf-8")
57    file_handler.setFormatter(formatter)
58    logger.addHandler(file_handler)
59
60    # 可選的 stderr handler
61    if include_stderr:
62        import sys
63        stderr_handler = logging.StreamHandler(sys.stderr)
64        stderr_handler.setFormatter(formatter)
65        logger.addHandler(stderr_handler)
66
67    return logger

 1#!/usr/bin/env python3
 2from hook_logging import setup_hook_logging
 3
 4# 初始化 logger
 5logger = setup_hook_logging("branch-verify")
 6
 7def main():
 8    logger.info("Hook started")
 9
10    branch = get_current_branch()
11    logger.debug(f"Current branch: {branch}")
12
13    if is_protected_branch(branch):
14        logger.warning(f"Operating on protected branch: {branch}")
15
16    try:
17        # 執行操作
18        result = do_something()
19        logger.info(f"Operation completed: {result}")
20    except Exception as e:
21        logger.error(f"Operation failed: {e}")
22        raise
23
24if __name__ == "__main__":
25    main()

1import logging
2
3# 取得 logger（使用模組名稱作為標識）
4logger = logging.getLogger(__name__)
5
6# 或使用自訂名稱
7logger = logging.getLogger("my_app")

 1import logging
 2
 3logger = logging.getLogger("my_app")
 4
 5# 輸出到檔案
 6file_handler = logging.FileHandler("app.log", encoding="utf-8")
 7logger.addHandler(file_handler)
 8
 9# 輸出到控制台
10console_handler = logging.StreamHandler()
11logger.addHandler(console_handler)

1import logging
2
3formatter = logging.Formatter(
4    "[%(asctime)s] %(levelname)s - %(name)s - %(message)s",
5    datefmt="%Y-%m-%d %H:%M:%S"
6)
7
8handler = logging.FileHandler("app.log")
9handler.setFormatter(formatter)

 1def setup_logger(name: str) -> logging.Logger:
 2    logger = logging.getLogger(name)
 3    logger.setLevel(logging.INFO)
 4
 5    # 重要：檢查是否已有 handler
 6    if logger.handlers:
 7        return logger
 8
 9    handler = logging.FileHandler("app.log")
10    logger.addHandler(handler)
11    return logger

 1import os
 2import logging
 3
 4def get_log_level() -> int:
 5    """從環境變數取得日誌等級"""
 6    level_name = os.getenv("LOG_LEVEL", "INFO").upper()
 7    return getattr(logging, level_name, logging.INFO)
 8
 9logger = logging.getLogger(__name__)
10logger.setLevel(get_log_level())

1from logging.handlers import RotatingFileHandler
2
3handler = RotatingFileHandler(
4    "app.log",
5    maxBytes=10*1024*1024,  # 10MB
6    backupCount=5           # 保留 5 個備份
7)

1.claude/hook-logs/
2├── branch-verify/
3│   ├── branch-verify-20240120-153000.log
4│   └── branch-verify-20240120-160000.log
5├── ticket-quality-gate/
6│   └── ticket-quality-gate-20240120-155000.log
7└── ...

1import logging
2
3# 好：使用模組名稱，便於追蹤
4logger = logging.getLogger(__name__)
5
6# 不好：使用固定字串，難以區分來源
7logger = logging.getLogger("my_logger")

1logger.debug("Variable x = %s", x)           # 詳細除錯
2logger.info("Processing file %s", filename)  # 一般操作
3logger.warning("Config not found, using default")  # 警告
4logger.error("Failed to connect: %s", error)  # 錯誤

1# 好：使用 % 格式化（只在需要時才格式化）
2logger.debug("Data: %s", expensive_function())
3
4# 不好：f-string 總是會執行
5logger.debug(f"Data: {expensive_function()}")

1resource "aws_cloudwatch_log_group" "api" {
2  name              = "/app/${var.env}/api"
3  retention_in_days = var.env == "prod" ? 30 : 7
4  kms_key_id        = aws_kms_key.logs.arn
5}

 1resource "aws_cloudwatch_metric_alarm" "api_5xx" {
 2  alarm_name          = "${var.env}-api-5xx-rate"
 3  comparison_operator = "GreaterThanThreshold"
 4  evaluation_periods  = 3
 5  metric_name         = "5XXError"
 6  namespace           = "AWS/ApiGateway"
 7  period              = 60
 8  statistic           = "Sum"
 9  threshold           = 10
10  treat_missing_data  = "notBreaching"
11  alarm_actions       = [aws_sns_topic.oncall.arn]
12}

1logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
2
3logger.Info(
4    "user created",
5    "userID", "u_1",
6    "email", "alice@example.com",
7)

1{
2  "time": "2026-04-22T10:00:00Z",
3  "level": "INFO",
4  "msg": "user created",
5  "userID": "u_1",
6  "email": "alice@example.com"
7}

1logger.Debug("cache miss", "key", key)
2logger.Info("server started", "addr", addr)
3logger.Warn("queue full", "dropped", count)
4logger.Error("write file failed", "path", path, "error", err)

1logger.Info("job queued", "id", job.ID)
2logger.Info("job started", "job_id", job.ID)
3logger.Info("job done", "jobID", job.ID)

1logger.Info("job queued", "jobID", job.ID)
2logger.Info("job started", "jobID", job.ID)
3logger.Info("job done", "jobID", job.ID)

 1base := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
 2    Level: slog.LevelInfo,
 3}))
 4
 5logger := base.With(
 6    "component", "worker",
 7    "version", "1.0.0",
 8)
 9
10logger.Info("job started", "jobID", "j_1")
11logger.Info("job finished", "jobID", "j_1")

1logger.Info("job j_1 for user u_1 started")

1logger.Info("job started", "jobID", "j_1", "userID", "u_1")

 1.claude/hook-logs/
 2├── acceptance-gate-hook/
 3│   ├── acceptance-gate-hook-20260304-091523.log
 4│   ├── acceptance-gate-hook-20260304-091845.log
 5│   └── .cleanup_trigger           # 清理觸發計數器
 6├── command-entrance-gate-hook/
 7│   ├── command-entrance-gate-hook-20260304-091523.log
 8│   └── ...
 9└── phase-completion-gate-hook/
10    └── ...

 1def setup_hook_logging(hook_name: str) -> logging.Logger:
 2    """建立並設定 Hook 日誌系統"""
 3    if not hook_name:
 4        hook_name = DEFAULT_HOOK_NAME
 5
 6    sanitized_name = _sanitize_hook_name(hook_name)
 7    root_dir = _find_project_root()
 8    log_base_dir = root_dir / ".claude" / "hook-logs" / sanitized_name
 9
10    # 建立日誌目錄（失敗時降級，不拋出異常）
11    try:
12        log_base_dir.mkdir(parents=True, exist_ok=True)
13    except OSError:
14        return _create_fallback_logger(hook_name)
15
16    logger = logging.getLogger(hook_name)
17    _clear_logger_handlers(logger)
18    logger.setLevel(logging.DEBUG)
19
20    is_debug = os.getenv("HOOK_DEBUG", "").lower() == "true"
21    _setup_logger_handlers(logger, log_base_dir, sanitized_name, is_debug)
22    return logger

1# 每個 Hook 有自己的 logger 實例
2logger_a = logging.getLogger("acceptance-gate-hook")
3logger_b = logging.getLogger("command-entrance-gate-hook")
4# 兩者的 handlers、level、format 完全獨立

1def _clear_logger_handlers(logger: logging.Logger) -> None:
2    """清除 logger 的所有 handlers"""
3    for handler in logger.handlers[:]:
4        logger.removeHandler(handler)
5        handler.close()

1# 正常模式：stdout 只顯示 WARNING 以上
2python3 my-hook.py
3
4# 除錯模式：stdout 顯示所有等級
5HOOK_DEBUG=true python3 my-hook.py

 1def _setup_logger_handlers(logger, log_base_dir, sanitized_name, is_debug):
 2    """為 logger 配置 handlers"""
 3    # 檔案 handler：記錄所有等級，供事後分析
 4    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
 5    log_file_path = log_base_dir / f"{sanitized_name}-{timestamp}.log"
 6    file_handler = _create_file_handler(log_file_path)
 7    if file_handler:
 8        logger.addHandler(file_handler)
 9
10    # 控制台 handler：正常模式只顯示 WARNING+，除錯模式顯示全部
11    logger.addHandler(_create_stream_handler(is_debug))

 1def _sanitize_hook_name(name: str) -> str:
 2    """淨化 hook 名稱，移除無法用於檔案系統的字元"""
 3    if not name:
 4        return DEFAULT_HOOK_NAME
 5
 6    for char in ["<", ">", "|"]:
 7        name = name.replace(char, "-")
 8    name = name.replace("/", "-").replace("\\", "-")
 9
10    # 合併連續 "-" 並移除前後
11    while "--" in name:
12        name = name.replace("--", "-")
13    name = name.strip("-")
14
15    return name if name else DEFAULT_HOOK_NAME

 1def _find_project_root() -> Path:
 2    """查詢專案根目錄
 3
 4    優先順序：
 5    1. 環境變數 CLAUDE_PROJECT_DIR
 6    2. 從 cwd 向上搜尋 CLAUDE.md（最多 5 層）
 7    3. os.getcwd() fallback（永不失敗）
 8    """
 9    env_dir = os.getenv("CLAUDE_PROJECT_DIR")
10    if env_dir:
11        return Path(env_dir)
12
13    current_dir = Path.cwd()
14    for _ in range(CLAUDE_MD_SEARCH_DEPTH):
15        if (current_dir / "CLAUDE.md").exists():
16            return current_dir
17        parent = current_dir.parent
18        if parent == current_dir:
19            break
20        current_dir = parent
21
22    return Path.cwd()

1Hook 執行 → NameError → run_hook_safely 捕獲 → 寫入日誌檔案 → 返回 EXIT_ERROR
2                                                    ↑
3                                              用戶看不到這裡

1# W25-005 之前的版本（有缺陷）
2def _log_exception(logger, hook_name, tb_str):
3    logger.critical(f"Unhandled exception in {hook_name}")
4    logger.critical(tb_str)
5    # 到這裡就結束了 -- 用戶完全不知道出錯

 1def _log_exception(logger, hook_name, tb_str):
 2    """記錄異常 traceback 到日誌"""
 3    # 1. 寫入日誌檔案（完整 traceback，供事後分析）
 4    try:
 5        logger.critical(f"Unhandled exception in {hook_name}")
 6        logger.critical(tb_str)
 7    except Exception as logging_error:
 8        # 日誌系統本身也可能失敗（磁碟滿了、權限問題）
 9        print(f"Failed to log exception: {logging_error}", file=sys.stdout)
10        print(tb_str, file=sys.stdout)
11
12    # 2. 輸出到 stderr，讓 Claude Code 顯示 "hook error"（W25-005 新增）
13    print(
14        f"[Hook Error] {hook_name} failed unexpectedly. "
15        f"Check hook logs for details.",
16        file=sys.stderr
17    )

 1# 目錄建立失敗時的 Fallback
 2try:
 3    log_base_dir.mkdir(parents=True, exist_ok=True)
 4except OSError:
 5    return _create_fallback_logger(hook_name)  # 降級為純 stdout 輸出
 6
 7def _create_fallback_logger(hook_name: str) -> logging.Logger:
 8    """建立 Fallback Logger（僅 StreamHandler）"""
 9    logger = logging.getLogger(hook_name)
10    _clear_logger_handlers(logger)
11    logger.setLevel(logging.DEBUG)
12    logger.addHandler(_create_stream_handler())
13    return logger

 1#!/usr/bin/env python3
 2import sys
 3from pathlib import Path
 4
 5# 這一行在 run_hook_safely 之前執行
 6# 如果失敗，run_hook_safely 根本不會被呼叫
 7from lib.common_functions import hook_output  # ModuleNotFoundError!
 8
 9from hook_utils import run_hook_safely
10
11def main() -> int:
12    # ...
13    return 0
14
15if __name__ == "__main__":
16    sys.exit(run_hook_safely(main, "my-hook"))

 1#!/usr/bin/env python3
 2import sys
 3from pathlib import Path
 4
 5# Import 防護：確保失敗時有明確的 stderr 輸出
 6try:
 7    sys.path.insert(0, str(Path(__file__).parent))
 8    from hook_utils import run_hook_safely
 9    from lib.common_functions import hook_output
10except ImportError as e:
11    print(f"[Hook Import Error] {Path(__file__).name}: {e}", file=sys.stderr)
12    sys.exit(1)

 1def main() -> int:
 2    # ...驗證邏輯...
 3
 4    if should_block:
 5        # 路徑 1：業務邏輯拒絕（有意阻止）
 6        result = {"error": error_message}
 7        print(json.dumps(result), file=sys.stdout)
 8        return 2  # 只有 stdout，沒有 stderr！
 9
10    return 0
11
12# run_hook_safely 包裝
13# 路徑 2：未預期異常 -- _log_exception 已有 stderr 輸出

1if should_block:
2    result = {"error": error_message}
3    print(json.dumps(result), file=sys.stdout)
4    # 新增：確保用戶在 Claude Code UI 能看到拒絕原因
5    print(f"[Agent Ticket Validation] blocked: {error_message}", file=sys.stderr)
6    return 2

1Hook 執行結果
2├── 成功（return 0）→ stdout 正常訊息
3├── 未預期異常（Exception）→ stderr 由 _log_exception 處理
4└── 有意阻止（return 非 0）→ stderr 必須有原因說明  ← 容易遺漏

 1def run_hook_safely(main_func, hook_name):
 2    logger = setup_hook_logging(hook_name)
 3    start_time = time.time()
 4
 5    try:
 6        exit_code = main_func()
 7        elapsed_time = time.time() - start_time
 8        logger.debug(f"Hook execution time: {elapsed_time:.2f}s")
 9        return exit_code
10    except (KeyboardInterrupt, SystemExit):
11        raise
12    except Exception:
13        elapsed_time = time.time() - start_time
14        logger.debug(f"Hook execution time before failure: {elapsed_time:.2f}s")
15        tb_str = traceback.format_exc()
16        _log_exception(logger, hook_name, tb_str)
17        return EXIT_ERROR

1[2026-03-04 09:15:23] DEBUG - Hook execution time: 0.05s       # 正常
2[2026-03-04 09:15:24] DEBUG - Hook execution time: 2.34s       # 偏慢，值得關注
3[2026-03-04 09:15:25] DEBUG - Hook execution time before failure: 0.00s  # import 階段就失敗了

 1LOG_RETENTION_DAYS = 7
 2LOG_CLEANUP_TRIGGER_FREQUENCY = 10
 3
 4def _cleanup_old_logs(log_base_dir: Path, retention_days: int = LOG_RETENTION_DAYS):
 5    """清理超期日誌檔案"""
 6    try:
 7        cutoff_time = datetime.now() - timedelta(days=retention_days)
 8        for log_file in log_base_dir.glob("*.log"):
 9            try:
10                mtime = datetime.fromtimestamp(log_file.stat().st_mtime)
11                if mtime < cutoff_time:
12                    log_file.unlink()
13            except (OSError, ValueError):
14                pass
15    except OSError:
16        pass

 1def _setup_logger_handlers(logger, log_base_dir, sanitized_name, is_debug):
 2    """為 logger 配置 handlers"""
 3    # 觸發日誌清理（降低頻率）
 4    cleanup_marker = log_base_dir / ".cleanup_trigger"
 5    try:
 6        if cleanup_marker.exists():
 7            count = int(cleanup_marker.read_text().strip() or "0")
 8            if count >= LOG_CLEANUP_TRIGGER_FREQUENCY:
 9                _cleanup_old_logs(log_base_dir)
10                cleanup_marker.write_text("0")
11            else:
12                cleanup_marker.write_text(str(count + 1))
13        else:
14            cleanup_marker.write_text("1")
15    except (OSError, ValueError):
16        pass  # 清理失敗不影響日誌功能

1# 錯誤做法：只寫日誌，用戶不知道
2logger.critical(tb_str)
3
4# 正確做法：日誌 + 用戶通知
5logger.critical(tb_str)
6print(f"[Hook Error] {hook_name} failed", file=sys.stderr)

 1# 錯誤做法：只保護 main()
 2sys.exit(run_hook_safely(main, "hook"))
 3
 4# 正確做法：import 也要保護
 5try:
 6    from lib.module import function
 7except ImportError as e:
 8    print(f"[Hook Import Error] {__file__}: {e}", file=sys.stderr)
 9    sys.exit(1)
10
11sys.exit(run_hook_safely(main, "hook"))

1# 錯誤做法：所有錯誤用同一種訊息
2print("hook error", file=sys.stderr)
3
4# 正確做法：包含 Hook 名稱和錯誤類型
5print(f"[Hook Error] {hook_name} failed unexpectedly", file=sys.stderr)
6print(f"[Hook Import Error] {filename}: {error}", file=sys.stderr)
7print(f"[Agent Validation] blocked: {reason}", file=sys.stderr)

 1Hook 被觸發
 2│
 3├─ [階段 1] Import 載入
 4│  ├─ 成功 → 繼續
 5│  └─ 失敗 → try-except 捕獲
 6│            ├─ stderr: [Hook Import Error] hook.py: error
 7│            └─ sys.exit(1)
 8│
 9├─ [階段 2] setup_hook_logging
10│  ├─ 成功 → Logger 就緒（FileHandler + StreamHandler）
11│  └─ 失敗 → Fallback Logger（僅 StreamHandler）
12│
13├─ [階段 3] main() 執行
14│  ├─ 成功 → logger.debug("execution time: Xs")
15│  │         return exit_code
16│  ├─ 業務拒絕 → stderr: [Hook Name] blocked: reason
17│  │             return 2
18│  └─ 未預期異常 → logger.critical(traceback)
19│                   stderr: [Hook Error] hook failed
20│                   return 1
21│
22└─ [階段 4] 日誌清理（每 10 次觸發）
23   └─ 清理 7 天前的日誌檔案