Claude Code Hook 系统详解与 Hello World 实操

📄 Claude Code Hook 系统详解与 Hello World 实操

一句话总结：本文从 Harness Engineering（执行层工程化）概念出发，系统介绍了 Claude Code 的 Hook（钩子）系统------一种在工具调用、用户提交等运行时事件上自动执行自定义脚本的机制，并通过完整的 Hello World 示例演示了从脚本编写到配置验证的全流程。

流程图

🤔 什么是 Harness？
Harness = Claude Code 的 RTOS 内核
Hook = 事件驱动的 ISR 回调
6 种 Hook 事件类型
matcher 匹配器过滤目标
Hello World 实操：

脚本 + settings.json 配置
验证：查看 hook_log.txt

内容梳理

一、从 Harness Engineering 到 Hook 系统

我对 Harness Engineering 的理解是：它指 Claude Code 运行时基础设施的工程化工作，负责工具编排、Hook 系统、会话管理、权限管控、Worktree 隔离、定时任务等底层机制。用嵌入式开发类比------如果 Claude Code 是 BMC（Baseboard Management Controller - 基板管理控制器）芯片，那 Harness 就是驱动这块芯片的 RTOS（Real-Time Operating System - 实时操作系统）内核。

而 Hook 系统是 Harness 中最具可编程性的子系统。

二、Hook 系统的核心机制

Hook（钩子）是在特定事件发生时自动触发用户自定义脚本的机制。我用嵌入式的话类比：就像 BMC 的 SMI（System Management Interrupt - 系统管理中断）或 GPIO（General Purpose Input/Output - 通用输入输出）中断处理------当事件发生，固件自动跳转到注册的 ISR（Interrupt Service Routine - 中断服务例程）。Hook 就是 Claude Code 的"ISR"。

支持的 6 种 Hook 事件：

事件	触发时机	类比
PreToolUse	工具调用之前	Pre-condition 检查
PostToolUse	工具调用之后	Post-condition 验证
Notification	权限请求弹窗时	Watchdog 告警回调
UserPromptSubmit	用户提交 prompt	用户按下 Enter 时
Stop	Claude 响应结束	主循环空闲 Hook
SubagentStop	子 Agent 结束	Agent 结束

**Matcher（匹配器）**决定 Hook 对哪些具体目标生效：

"" --- 匹配所有事件
"Edit"、"Bash"、"Read" --- 匹配特定工具名
matcher_regex --- 用正则匹配命令内容

Hook 输入环境变量：

变量	含义
`CLAUDE_TOOL_NAME`	触发 Hook 的工具名
`CLAUDE_TOOL_INPUT`	工具的输入参数（JSON, JavaScript Object Notation - JavaScript 对象表示法）
`CLAUDE_PROJECT_DIR`	项目根目录

三、三种典型 Hook 场景示例

每次编辑前自动记录日志：PreToolUse 匹配 Edit，写入 session.log
每次 commit 前跑 lint ：PreToolUse 匹配 Bash + git commit.* 正则，执行 npm run lint
响应结束后桌面通知：Stop 事件触发 PowerShell 通知命令

四、Hello World 完整实操

下面搭建一个 Hook，在每次对话中自动记录 Claude Code 的运行时事件日志。

步骤 1：创建 Hook 脚本

在项目根目录下创建 .claude/hooks/hello_hook.sh：

bash 复制代码

#!/bin/bash
# Hello World Hook ------ 演示 Claude Code Hook 系统的基本用法
# 环境变量 CLAUDE_TOOL_NAME / CLAUDE_TOOL_INPUT / CLAUDE_PROJECT_DIR 由 harness 自动注入

LOG_FILE="$CLAUDE_PROJECT_DIR/.claude/hooks/hook_log.txt"
TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
EVENT=${1:-"unknown"}

case "$EVENT" in
  UserPromptSubmit)
    echo "[$TIMESTAMP] ✅ 用户提交了 Prompt" >> "$LOG_FILE"
    ;;
  Stop)
    echo "[$TIMESTAMP] ⏹️  Claude 响应结束" >> "$LOG_FILE"
    ;;
  PreToolUse)
    echo "[$TIMESTAMP] 🔧 即将调用工具: $CLAUDE_TOOL_NAME" >> "$LOG_FILE"
    ;;
  PostToolUse)
    echo "[$TIMESTAMP] ✅ 工具执行完毕: $CLAUDE_TOOL_NAME" >> "$LOG_FILE"
    ;;
  *)
    echo "[$TIMESTAMP] 📣 事件触发: $EVENT | 工具: ${CLAUDE_TOOL_NAME:-none}" >> "$LOG_FILE"
    ;;
esac

脚本通过 $1 接收事件类型参数，case 分支根据事件类型写入不同格式的日志。Harness 自动注入 $CLAUDE_TOOL_NAME、$CLAUDE_PROJECT_DIR 等环境变量。

创建后赋予执行权限：

bash 复制代码

chmod +x .claude/hooks/hello_hook.sh

步骤 2：在 settings.json 中注册 Hook

编辑 .claude/settings.json，在顶层添加 hooks 字段：

json 复制代码

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "bash \"${CLAUDE_PROJECT_DIR}/.claude/hooks/hello_hook.sh\" PreToolUse"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "bash \"${CLAUDE_PROJECT_DIR}/.claude/hooks/hello_hook.sh\" PostToolUse"
        }]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [{
          "type": "command",
          "command": "bash \"${CLAUDE_PROJECT_DIR}/.claude/hooks/hello_hook.sh\" UserPromptSubmit"
        }]
      }
    ],
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "bash \"${CLAUDE_PROJECT_DIR}/.claude/hooks/hello_hook.sh\" Stop"
        }]
      }
    ]
  }
}

如果 settings.json 中已有其他配置（如 permissions），将 hooks 与它们并列放在顶层即可，不要覆盖已有字段。

关键字段说明：

字段	含义
`hooks.<事件名>`	事件类型，支持 PreToolUse / PostToolUse / UserPromptSubmit / Stop / Notification / SubagentStop
`matcher`	匹配器，`""` 表示匹配该事件的所有实例
`type`	执行类型，`"command"` 为 shell 命令，还支持 `"prompt"` 注入提示词
`command`	要执行的命令，`${CLAUDE_PROJECT_DIR}` 由 harness 替换为项目根目录

数据流： 用户发送消息 → UserPromptSubmit → 思考 → PreToolUse（每次工具前）→ PostToolUse（每次工具后）→ Stop

步骤 3：验证

重启 Claude Code 后进行正常对话，然后查看日志文件：

bash 复制代码

cat .claude/hooks/hook_log.txt

输出示例：

复制代码

[2026-05-17 14:30:01] ✅ 用户提交了 Prompt
[2026-05-17 14:30:02] 🔧 即将调用工具: Read
[2026-05-17 14:30:02] ✅ 工具执行完毕: Read
[2026-05-17 14:30:05] ⏹️  Claude 响应结束

总结与展望

总结

Hook 是 Claude Code 的事件驱动自动化机制，类比嵌入式 ISR（Interrupt Service Routine - 中断服务例程）
支持 6 种事件类型，通过 matcher 精确控制触发范围
配置方式为 settings.json 声明 + shell 脚本实现，环境变量传递上下文
除了 command 类型，还支持 prompt 类型注入提示词
Hello World 实操覆盖了从脚本编写到日志验证的完整链路

展望

自动化工作流：可将 Hook 与编译、CI（Continuous Integration - 持续集成）、通知等环节串联，构建完整的开发流水线------这是嵌入式固件开发中"一键编译部署测试"诉求的自然延伸
PreToolUse 安全检查 ：利用 PreToolUse 对高风险命令（如 rm -rf、git push --force）做二次确认，防止误操作
PostToolUse 审计追踪：记录所有工具调用日志，用于事后排查问题或分析 AI 行为模式
结合 MCP Server：Hook 脚本可以调用 MCP（Model Context Protocol - 模型上下文协议）工具的 HTTP 接口，实现跨进程的复杂自动化编排