Claude Code Hooks 与自动化指南：事件驱动的 AI 工作流完全教学

1. 什么是 Hooks？跟 Skills 有什么不同？

• Skills：使用者主动触发（输入 /指令 或自然语言）→ Claude 执行预设流程
• Hooks：事件自动触发（工具被呼叫、讯息送出、指令完成等）→ 系统自动执行 Shell 指令
• 组合威力：/Deploy Skill 执行部署 → 部署完成 → Hook 自动跑 Smoke Test → Smoke Test 通过 → Hook 发 Slack 通知

2. Hook 事件类型

3. 设定方式：settings.json

• 设定档位置：~/.Claude/Settings.Json（全域）或 .Claude/Settings.Json（专案层级）
• 基本结构：Hooks 物件下按事件类型分组，每个事件可绑定多个 Hook
• 每个 Hook 包含：Type（Command）、Command（要执行的 Shell 指令）、Description（说明）
• 可选栏位：Matcher（只对特定工具名称触发）、Timeout（超时设定）
• 优先顺序：专案层级的设定会覆盖全域设定

4. 范例 1-3：开发流程自动化

• 范例 1 — 档案修改后自动 Lint：Posttooluse + Matcher: Write/Edit → 执行 Eslint --Fix 或 Black 自动格式化刚修改的档案
• 范例 2 — 对话开始时载入专案状态：Sessionstart → 执行 Git Status 和 Docker Ps，把结果带入对话上下文
• 范例 3 — 危险操作前拦截：Pretooluse + Matcher: Bash → 检查指令是否包含 Rm -Rf、Git Push --Force 等危险操作，有的话阻止执行

5. 范例 4-6：品质保证自动化

• 范例 4 — 提交前自动跑测试：Pretooluse + Matcher: Bash（当指令包含 Git Commit）→ 先跑 Pytest，测试通过才允许提交
• 范例 5 — 翻译安全检查：Posttooluse + Matcher: Write（当修改 .Po 或 Locale 档案）→ 自动执行 Python3 Scripts/Check_Translations.Py --Js-Safety
• 范例 6 — Json 修改后自动验证：Posttooluse + Matcher: Write（当修改 Data/Guides/ 下的档案）→ 自动执行 ./Scripts/Validate_Json.Sh

6. 范例 7-8：通知与记录

• 范例 7 — 完成后自动通知：Stop → 把 Claude 的最后回应摘要发到 Slack 或 Telegram，让团队成员知道任务完成
• 范例 8 — 操作记录：Posttooluse → 把每次工具呼叫的类型和参数记录到 Log 档案，方便事后追踪「Claude 做了什么」

7. Hooks + Skills 组合模式

• 模式 1 — 前置检查：Hook（Pretooluse）确认环境正常 → Skill 执行主要工作。例如部署前 Hook 检查 Ci 是否通过
• 模式 2 — 后处理链：Skill 完成主要工作 → Hook（Stop）自动执行后处理。例如 /Content-Pipeline 建立内容后，Hook 自动 Commit 并通知
• 模式 3 — 品质门禁：Skill 修改程式码 → Hook（Posttooluse）自动跑 Lint 和测试 → 全部通过才继续。确保 Ai 产出的程式码符合品质标准

8. 除错与最佳实践

• Hook 没触发：确认事件类型和 Matcher 是否正确。用 Echo 指令测试 Hook 是否被呼叫
• Hook 阻挡了操作：检查 Hook 的 Exit Code。非零的 Exit Code 会阻止操作
• Hook 太慢：加入 Timeout 设定，避免 Hook 卡住整个工作流。预设超时 60 秒
• 最佳实践 1：Hook 指令保持简单——一个 Hook 做一件事
• 最佳实践 2：用 Description 清楚说明 Hook 的用途，方便团队成员理解
• 最佳实践 3：先在个人设定中测试，确认无误后再推到专案设定
• 最佳实践 4：敏感操作（如自动 Push、自动部署）的 Hook 要特别谨慎，建议加入确认步骤