第1课：钩子（Hooks）——自动检查和事件拦截

为什么需要这个#

想象您雇了一个助手来处理代码。钩子就像您留给这个助手的指令：“删除文件前——再检查一遍”、“每次修改后——确保没有破坏任何东西”。

钩子（英文 hook——“钩子”）是在 Claude Code 工作的特定时刻自动运行的脚本或指令。钩子允许：

🛡️ 阻止危险命令（例如删除重要文件）
✅ 在保存前检查代码
📋 在会话开始时添加上下文
🔍 控制工作质量

钩子何时触发#

Claude Code 支持多个事件（时刻），可以将钩子"挂"上去：

事件	何时触发	用途
`SessionStart`	会话启动时	加载项目设置
`UserPromptSubmit`	您发送请求时	添加上下文或检查请求
`PreToolUse`	执行操作之前	阻止危险操作
`PostToolUse`	执行操作之后	检查结果
`Stop`	Claude 完成工作时	确保一切已完成
`SessionEnd`	会话结束时	清理、记录日志

两种类型的钩子#

1. 命令钩子（command）#

运行脚本（程序）。适合快速、精确的检查：

{
  "type": "command",
  "command": "bash ./scripts/check.sh",
  "timeout": 10
}

2. 提示钩子（prompt）——推荐方式#

使用 AI 分析情况。适合复杂检查：

{
  "type": "prompt",
  "prompt": "检查此文件操作是否安全。返回 'approve' 或 'deny'。",
  "timeout": 30
}

分步指南：配置钩子#

步骤1：钩子存储位置#

钩子可以在两个地方配置：

用户设置中 — 文件 .claude/settings.json（对所有项目生效）
插件中 — 插件文件夹内的 hooks/hooks.json 文件

步骤2：创建简单钩子——阻止危险命令#

在项目中创建文件 .claude/settings.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

然后创建脚本 .claude/hooks/block-rm.sh：

#!/bin/bash
# 读取 Claude 要执行的命令信息
COMMAND=$(cat | jq -r '.tool_input.command')

# 如果命令包含 rm -rf——阻止！
if echo "$COMMAND" | grep -q 'rm -rf'; then
  echo '{"hookSpecificOutput": {"permissionDecision": "deny", "permissionDecisionReason": "危险命令 rm -rf 已被钩子阻止"}}' 
else
  exit 0  # 一切正常，允许执行
fi

步骤3：来自 security-guidance 插件的安全钩子#

security-guidance 插件包含一个钩子，在编辑文件时提醒注意安全：

{
  "description": "Security reminder hook",
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/security_reminder_hook.py"
          }
        ],
        "matcher": "Edit|Write|MultiEdit"
      }
    ]
  }
}

请注意：

matcher — 过滤器：钩子仅在 Edit、Write 或 MultiEdit 操作时触发
${CLAUDE_PLUGIN_ROOT} — 指向插件文件夹的变量（始终使用它以保证可移植性）

步骤4：来自 Hookify 插件的钩子#

Hookify 插件是一个强大的工具，允许通过简单的 .local.md 文件创建钩子。以下是阻止危险 rm 命令的示例：

---
name: block-dangerous-rm
enabled: true
event: bash
pattern: rm\s+-rf
action: block
---

⚠️ **检测到危险的 rm 命令！**

此命令可能删除重要文件。请：
- 检查路径是否正确
- 考虑更安全的替代方案
- 确保您有备份

以下是在完成前要求运行测试的钩子示例：

---
name: require-tests-run
enabled: false
event: stop
action: block
conditions:
  - field: transcript
    operator: not_contains
    pattern: npm test|pytest|cargo test
---

**未检测到测试！**

在完成前请运行测试，以确保更改正常工作。

Hookify 拦截所有主要事件：PreToolUse、PostToolUse、Stop、UserPromptSubmit。

匹配器（Matchers）——钩子过滤器#

匹配器是决定钩子何时触发的过滤器：

"matcher": "Write"           // 仅用于文件写入
"matcher": "Read|Write|Edit" // 用于读取、写入和编辑
"matcher": "Bash"            // 仅用于 bash 命令
"matcher": "*"               // 用于所有操作
"matcher": "mcp__.*"         // 用于所有 MCP 工具

重要提示#

⚠️ 钩子在会话启动时加载。 如果您修改了钩子，需要重启 Claude Code 使更改生效。

调试时使用：

claude --debug

可以在 Claude Code 内部使用 /hooks 命令检查已加载的钩子。

课程总结#

钩子是在 Claude Code 工作的特定时刻自动运行的脚本
存在命令钩子（脚本）和提示钩子（基于 AI）
钩子允许阻止危险操作、检查代码质量和添加上下文
匹配器过滤钩子适用于哪些工具
Hookify 插件允许通过简单的 Markdown 文件创建钩子
在插件中始终使用 ${CLAUDE_PLUGIN_ROOT} 作为路径