1events := make(chan Event, 128)
2notifications := make(chan Notification, 128)
3
4repo := NewNotificationRepository()
5worker := NewWorker(repo, events, notifications)
6server := NewHTTPServer(repo, notifications)

1file / HTTP / timer ──> events ──> Worker ──> notifications
2                                      │
3                                      ▼
4                                  Repository
5                                      │
6                                      ▼
7                                   HTTP API

 1>>> import this
 2The Zen of Python, by Tim Peters
 3
 4Beautiful is better than ugly.
 5Explicit is better than implicit.
 6Simple is better than complex.
 7Complex is better than complicated.
 8Flat is better than nested.
 9Sparse is better than dense.
10Readability counts.
11...

1# 好的做法：明確導入
2from lib.hook_io import read_hook_input, write_hook_output
3from lib.git_utils import get_current_branch
4
5# 不好的做法：隱式導入所有
6from lib.hook_io import *  # 不知道導入了什麼

 1# 好的命名：一看就懂
 2def get_current_branch() -> Optional[str]:
 3    """獲取當前分支名稱"""
 4    success, output = run_git_command(["branch", "--show-current"])
 5    return output if success and output else None
 6
 7# 不好的命名：需要猜測
 8def gcb():
 9    s, o = rgc(["branch", "--show-current"])
10    return o if s and o else None

 1def run_git_command(args: list[str]) -> tuple[bool, str]:
 2    """
 3    執行 git 命令並返回結果
 4
 5    Returns:
 6        tuple[bool, str]: (是否成功, 輸出內容或錯誤訊息)
 7    """
 8    try:
 9        result = subprocess.run(
10            ["git"] + args,
11            capture_output=True,
12            text=True,
13        )
14        if result.returncode == 0:
15            return True, result.stdout.strip()
16        else:
17            return False, result.stderr.strip()
18    except Exception as e:
19        return False, str(e)

1success, output = run_git_command(["status"])
2if success:
3    print(output)
4else:
5    print(f"Error: {output}")

 1# 不好：過深的巢狀
 2def check_file(path):
 3    if path:
 4        if path.exists():
 5            if path.suffix == '.py':
 6                if path.stat().st_size > 0:
 7                    return True
 8    return False
 9
10# 好：使用 early return
11def check_file(path):
12    if not path:
13        return False
14    if not path.exists():
15        return False
16    if path.suffix != '.py':
17        return False
18    if path.stat().st_size <= 0:
19        return False
20    return True

1# Pythonic
2squares = [x**2 for x in range(10)]
3
4# 非 Pythonic
5squares = []
6for x in range(10):
7    squares.append(x**2)

1# Pythonic
2with open(file_path, "r", encoding="utf-8") as f:
3    content = f.read()
4
5# 非 Pythonic
6f = open(file_path, "r", encoding="utf-8")
7content = f.read()
8f.close()  # 容易忘記關閉

1# Pythonic
2for i, item in enumerate(items):
3    print(f"{i}: {item}")
4
5# 非 Pythonic
6for i in range(len(items)):
7    print(f"{i}: {items[i]}")

 1def write_hook_output(
 2    output: dict,
 3    ensure_ascii: bool = False,
 4    indent: int = 2
 5) -> None:
 6    """
 7    輸出 Hook 結果到 stdout
 8
 9    Args:
10        output: 要輸出的字典
11        ensure_ascii: 是否確保 ASCII 編碼（預設 False 以支援中文）
12        indent: JSON 縮排空格數
13    """
14    print(json.dumps(output, ensure_ascii=ensure_ascii, indent=indent))

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

1type Logger interface {
2 Info(message string)
3}
4
5type Server struct {
6 addr   string
7 logger Logger
8}

1type UserFinder interface {
2 FindUser(ctx context.Context, id string) (User, error)
3}
4
5type UserHandler struct {
6 finder UserFinder
7}

 1func NewUserHandler(finder UserFinder) UserHandler {
 2 return UserHandler{finder: finder}
 3}
 4
 5func main() {
 6 db := NewDatabase("postgres://localhost/app")
 7 repository := NewUserRepository(db)
 8 handler := NewUserHandler(repository)
 9
10 http.HandleFunc("/users/", handler.ServeHTTP)
11}

 1type AuditFields struct {
 2 CreatedAt time.Time
 3 UpdatedAt time.Time
 4}
 5
 6type User struct {
 7 ID    string
 8 Email string
 9 AuditFields
10}

 1type fakeUserFinder struct {
 2    user User
 3    err  error
 4}
 5
 6func (f fakeUserFinder) FindUser(ctx context.Context, id string) (User, error) {
 7 if f.err != nil {
 8     return User{}, f.err
 9 }
10 return f.user, nil
11}

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

 1func LoadConfig(path string) (Config, error) {
 2 data, err := os.ReadFile(path)
 3 if err != nil {
 4     return Config{}, fmt.Errorf("read config %q: %w", path, err)
 5 }
 6
 7 var config Config
 8 if err := json.Unmarshal(data, &config); err != nil {
 9     return Config{}, fmt.Errorf("parse config %q: %w", path, err)
10 }
11
12 return config, nil
13}

 1func CreateUser(email string) (User, error) {
 2 email = strings.TrimSpace(email)
 3 if email == "" {
 4  return User{}, fmt.Errorf("email is required")
 5 }
 6
 7 if !strings.Contains(email, "@") {
 8  return User{}, fmt.Errorf("invalid email")
 9 }
10
11 return User{Email: email}, nil
12}

1if err := repository.Save(ctx, user); err != nil {
2 return fmt.Errorf("save user %q: %w", user.Email, err)
3}

 1func handleCreateUser(w http.ResponseWriter, r *http.Request) {
 2 var req createUserRequest
 3 if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 4  http.Error(w, "invalid json", http.StatusBadRequest)
 5  return
 6 }
 7
 8 user, err := CreateUser(req.Email)
 9 if err != nil {
10  http.Error(w, err.Error(), http.StatusBadRequest)
11  return
12 }
13
14 writeJSON(w, http.StatusCreated, user)
15}

 1func run() error {
 2 config, err := LoadConfig("config.json")
 3 if err != nil {
 4  return err
 5 }
 6
 7 return StartServer(config)
 8}
 9
10func main() {
11 if err := run(); err != nil {
12  log.Fatal(err)
13 }
14}

 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# 自訂實作（看似合理，實則隱藏成本）
 2class LazyFileHandler(logging.FileHandler):
 3    """延遲建立檔案的 Handler"""
 4    def __init__(self, filename, mode='a', encoding=None):
 5        self.filename = filename
 6        self.mode = mode
 7        self._file_created = False
 8        # 不呼叫 super().__init__() 以避免建立檔案
 9        logging.Handler.__init__(self)
10
11    def emit(self, record):
12        if not self._file_created:
13            os.makedirs(os.path.dirname(self.filename), exist_ok=True)
14            self._file_created = True
15        super().emit(record)
16        # AttributeError: 'LazyFileHandler' has no attribute 'stream'

11. 開發成本：寫自訂類別          ~30 分鐘
22. 除錯成本：追蹤 AttributeError  ~1 小時
33. 修復成本：派發 hotfix 任務      ~2 小時
44. 驗證成本：確認修復後無迴歸      ~30 分鐘
5─────────────────────────────────
6   總成本：~4 小時

1# 一行解決
2handler = logging.FileHandler(filename, delay=True)
3# delay=True：延遲到第一次 emit 時才建立檔案
4# Python 3.0 就已存在，經過 15+ 年的穩定性驗證

1# 這段程式碼出現在 11 個 Hook 檔案中
2def read_json_from_stdin():
3    import sys, json
4    try:
5        return json.loads(sys.stdin.read())
6    except Exception:
7        return {}

 1# 修改後的版本
 2def read_json_from_stdin():
 3    import sys, json, logging
 4    logger = logging.getLogger(__name__)
 5    try:
 6        data = sys.stdin.read()
 7        return json.loads(data)
 8    except json.JSONDecodeError as e:
 9        logger.warning("stdin JSON 解析失敗: %s", e)
10        return {}
11    except Exception as e:
12        logger.error("stdin 讀取異常: %s", e)
13        return {}

1第 1 次修改：11 處 x 5 分鐘 = 55 分鐘
2第 2 次修改：11 處 x 5 分鐘 + 排查第 1 次遺漏的 bug = 75 分鐘
3第 3 次修改：11 處 x 5 分鐘 + 排查前兩次的行為不一致 = 120 分鐘
4...

 1# lib/hook_io.py（共用模組）
 2def read_json_from_stdin() -> dict:
 3    """
 4    從 stdin 讀取 JSON 資料。
 5
 6    Returns:
 7        解析後的字典，失敗時返回空字典
 8    """
 9    import sys, json, logging
10    logger = logging.getLogger(__name__)
11    try:
12        data = sys.stdin.read()
13        return json.loads(data)
14    except json.JSONDecodeError as e:
15        logger.warning("stdin JSON 解析失敗: %s", e)
16        return {}
17    except Exception as e:
18        logger.error("stdin 讀取異常: %s", e)
19        return {}

1# 每個 Hook 檔案中
2from lib.hook_io import read_json_from_stdin
3
4input_data = read_json_from_stdin()

1# 「安全」的錯誤處理（實際上是最危險的）
2def run_hook_safely(hook_func):
3    try:
4        hook_func()
5    except Exception as e:
6        # 只寫入檔案日誌，不通知任何人
7        log_to_file(f"Hook 失敗: {e}")

11. 發現問題            0 分鐘（偶然發現，否則可能更久）
22. 確認哪些 Hook 失敗    30 分鐘（需要手動逐一檢查）
33. 找到失敗原因          2 小時（沒有日誌可看，只能猜測）
44. 修復失敗的 Hook       1 小時
55. 驗證修復效果          30 分鐘
66. 確認沒有其他受影響的部分  1 小時
7─────────────────────────
8   總成本：~5 小時（且可能仍有遺漏）

1def run_hook_safely(hook_func, hook_name: str):
2    try:
3        hook_func()
4    except Exception as e:
5        # 寫入檔案日誌（完整追蹤）
6        log_to_file(f"Hook 失敗: {e}", traceback=True)
7        # 輸出到 stderr（確保使用者可見）
8        print(f"[Hook Error] {hook_name}: {e}", file=sys.stderr)

11. 發現問題           0 分鐘（stderr 立即可見）
22. 確認失敗原因        5 分鐘（日誌有完整的 traceback）
33. 修復失敗的 Hook     30 分鐘
44. 驗證修復效果        10 分鐘
5─────────────────────────
6   總成本：~45 分鐘

 1# 方案 A：每次都清理
 2def run_hook():
 3    execute_hook_logic()
 4    cleanup_old_logs()  # 每次 Hook 執行後都清理
 5
 6# 方案 B：每 N 次清理一次
 7LOG_CLEANUP_TRIGGER_FREQUENCY = 10
 8
 9def run_hook():
10    execute_hook_logic()
11    state["execution_count"] += 1
12    if state["execution_count"] % LOG_CLEANUP_TRIGGER_FREQUENCY == 0:
13        cleanup_old_logs()
14
15# 方案 C：外部排程清理
16# 由 cron job 或系統排程器負責
17# Hook 本身不做任何清理

 1LOG_CLEANUP_TRIGGER_FREQUENCY = 10
 2
 3def maybe_cleanup_logs(execution_count: int, log_dir: Path) -> None:
 4    """
 5    根據執行次數決定是否清理舊日誌。
 6
 7    每 LOG_CLEANUP_TRIGGER_FREQUENCY 次觸發一次清理，
 8    在精確度和 I/O 成本之間取得平衡。
 9    """
10    if execution_count % LOG_CLEANUP_TRIGGER_FREQUENCY != 0:
11        return
12    cleanup_old_logs(log_dir)

 1# 方案 A：直接執行，失敗再處理
 2def dispatch_task(task):
 3    try:
 4        result = execute(task)  # 消耗資源
 5    except PermissionError:
 6        # 失敗了，資源已經浪費
 7        log("任務失敗：權限不足")
 8        return None
 9
10# 方案 B：預先驗證
11def dispatch_task(task):
12    if not has_required_permissions(task):
13        log("跳過：權限不足")
14        return None
15    result = execute(task)  # 確認可行才消耗資源

1預驗證成本 = 驗證時間 x 每次派發
2失敗成本 = 任務執行時間 x 失敗機率
3
4當 失敗成本 > 預驗證成本 時，預驗證是值得的

1總成本 = 開發成本 + 維護成本 + 修復成本 + 機會成本

 1func handle(ctx context.Context, request Request) error {
 2    result, err := client.Fetch(ctx, request.ID)
 3    if err != nil {
 4        return fmt.Errorf("fetch data: %w", err)
 5    }
 6
 7    if err := repository.Save(ctx, result); err != nil {
 8        return fmt.Errorf("save result: %w", err)
 9    }
10
11    return nil
12}

1這個服務主要是 [webhook](/backend/knowledge-cards/webhook/) receiver、[queue](/backend/knowledge-cards/queue/) [consumer](/backend/knowledge-cards/consumer/) 與 [WebSocket](/backend/knowledge-cards/websocket/) 推送。
2主要風險是大量 I/O、[timeout](/backend/knowledge-cards/timeout/)、[backpressure](/go/backend/knowledge-cards/backpressure/) 與 [graceful shutdown](/backend/knowledge-cards/graceful-shutdown/)。
3Go 的 goroutine/context 模型和單一 binary 部署符合這些條件，所以 Go 是好候選。

1這個系統主要是企業內部資料管理、權限、報表與工作流。
2主要風險是業務規則完整性、框架生態、資料庫整合與長期平台治理。
3Java / C# 生態可能比 Go 更貼近主問題。

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