Hooks Guide — 自动化工作流实践

是什么

Hooks 实践指南，介绍如何通过 Shell 命令钩子在 Claude Code 生命周期节点自动执行操作，实现确定性控制。与依赖 LLM 判断不同，Hooks 保证某些操作一定发生，适合格式化、通知、权限控制等场景。

核心机制

配置结构：在 settings.json 的 hooks 对象中，以事件名为 key，每个事件包含 matcher 数组和 hooks 数组：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{"type": "command", "command": "..."}]
      }
    ]
  }
}

常见自动化场景：

• 桌面通知：Notification 事件 + osascript（macOS）/ notify-send（Linux）
• 自动格式化：PostToolUse + Edit|Write matcher + prettier/black
• 保护文件：PreToolUse + Edit matcher + 路径检查，返回 deny
• 重注入上下文：PostCompact 事件，压缩后重新注入关键信息
• 审计配置变更：ConfigChange 事件，记录变更日志
• 环境重载：CwdChanged 事件，配合 direnv 自动加载环境变量
• 自动审批特定权限：PermissionRequest 事件，对已知安全操作自动批准

Prompt-based Hooks：用 LLM 评估条件而非确定性脚本，适合代码质量检查等需要判断的场景。

Agent-based Hooks：用完整 Agent 执行复杂逻辑，适合需要多步骤处理的场景。

关键细节

• 查看已配置 Hooks：/hooks（只读，修改需编辑 settings.json）
• macOS 通知命令：osascript -e 'display notification "..." with title "Claude Code"'
• Linux 通知命令：notify-send "Claude Code" "..."
• 自动格式化示例：jq -r '.tool_input.file_path' | xargs npx prettier --write
• Hook 配置位置：~/.claude/settings.json（全局）或 .claude/settings.json（项目）

关联

• hooks — Hooks 完整事件参考和 JSON 格式规范
• skills — 给 Claude 添加指令和可执行命令
• goal — /goal 命令底层使用 Stop Hook 实现

实践要点

• 先用 /hooks 验证配置是否生效，再测试实际行为
• 多个 Hook 事件共用同一个 hooks 对象，不要重复写顶层 key
• 格式化 Hook 要处理文件不存在的情况（Claude 可能删除了文件）
• 通知 Hook 在 macOS 上需要先在系统设置中允许 Script Editor 发送通知
• Stop Hook 返回 {retry: true} 可让 Claude 继续工作，实现自动循环