Claude Code(四)Hooks及用法：构建 Agent 的确定性神经系统

在之前的文章中，我探讨了 Claude Code 的基本交互。如果说 Prompt 是指挥 AI 的“语言”，那么 Hooks（钩子） 就是控制 AI 行为的“神经系统”。

今天，我将跳出简单的命令配置，从架构设计的角度记录我对 Hooks 的深入研究。

核心概念：概率性 AI 与确定性系统

在软件工程中，LLM（大语言模型）本质上是一个概率性系统——我给它指令，它“很可能”会执行，但不是绝对。这在严谨的工程场景（如生产环境部署、敏感文件操作）中是不可接受的。

Hooks 的出现，是为了引入确定性。

架构视角： 我将 Hooks 想象成 Web 开发中的 Middleware（中间件） 或 Git 的 Pre-commit Hooks。它们是一道道刚性的逻辑“关卡”，包裹在柔软灵活的 AI 核心之外。

graph LR
    A[用户输入] --> B{Pre-Hooks 拦截层}
    B -- 注入上下文 --> C[Claude AI 核心]
    B -- 阻断/拒绝 --> D[终止操作]
    C --> E{Post-Hooks 处理层}
    E -- 格式化/审计 --> F[最终输出/文件变更]
    E -- 触发后续任务 --> G[自动化 Agent]

通过这种架构，我实现了：

1. 确定性控制：无论 AI 多么“有创意”，它都无法绕过我硬编码的安全检查。
2. 无感上下文：不需要我手动输入背景信息，Hooks 自动在幕后“喂”给 AI。
3. 副作用管理：将文件清理、日志记录等脏活累活从 AI 的 Token 消耗中剥离。

生命周期全景图

Claude Code 的生命周期比简单的“问答”要复杂得多，Hook 事件贯穿了从会话启动到结束的每一个微小环节。

下图展示了一个典型指令（如“帮我修改代码”）背后的 Hook 触发流：

sequenceDiagram
    participant User
    participant System as Hook System
    participant Claude as Claude Agent
    participant Tool as File/Bash Tool

    Note over User, Claude: 阶段一：意图注入
    User->>System: 提交 Prompt
    System->>System: 触发 UserPromptSubmit
    Note right of System: 自动检索 Skill/文档<br/>注入 Hidden Context
    System->>Claude: 增强后的 Prompt

    Note over Claude, Tool: 阶段二：执行控制
    Claude->>System: 请求使用 Tool (Edit)
    System->>System: 触发 PreToolUse/Permission
    Note right of System: 检查敏感文件<br/>安全审计
    System-->>Claude: Allow/Deny
    Claude->>Tool: 执行操作
    Tool-->>System: 触发 PostToolUse
    Note right of System: 记录变更文件<br/>更新项目索引
    System-->>Claude: 返回执行结果

    Note over Claude, User: 阶段三：收尾质量门
    Claude->>System: 任务完成 (Stop)
    System->>System: 触发 Stop
    Note right of System: 运行 TSC 检查<br/>运行 Prettier
    System->>User: 最终响应

关键事件解析

事件 (Event)	核心价值	典型应用场景
SessionStart	环境初始化	加载项目特定的环境变量、检查依赖版本、恢复上次会话记忆。
UserPromptSubmit	上下文增强 (RAG)	这是实现“智能”的关键。在此处分析用户意图，悄悄注入相关的 API 文档或编码规范，而无需我显式提供。
PreToolUse	安全卫士	防止 AI 修改 .env、锁定文件或在错误的分支上提交代码。它拥有“一票否决权”。
PostToolUse	状态追踪	AI 是无状态的，但项目是有状态的。在此处记录“AI 修改了哪些文件”，为后续的测试或回滚提供依据。
Stop	质量关口	在 AI 交差之前，强制执行编译检查。如果编译失败，甚至可以拒绝 AI 的停止请求，迫使它修复错误。

实战案例：构建“工程感知”基础设施

在 claude-code-infrastructure-showcase 项目中，我构建了一套基于 Hooks 的高级基础设施。这不仅仅是配置，而是一套自动化工作流。

Skill 自动激活 (UserPromptSubmit)

最痛点的场景：我有 50 个项目的编码规范，如果全部放入 System Prompt，上下文窗口瞬间爆炸。

解决方案：动态注入。

工作原理：

1. 我输入：“优化这个数据库查询”。
2. UserPromptSubmit Hook 捕获输入，正则匹配关键词 数据库 SQL。
3. 脚本读取本地 skills/database-best-practices.md。
4. 将内容追加到 Prompt 尾部（对用户不可见）。

这样，Claude 在处理任务时，就像临时“回忆”起了相关的专业知识。

幽灵文件追踪器 (PostToolUse)

Claude 有时会忘记自己刚刚改了什么，特别是在长会话中。

解决方案：构建外部记忆。

我利用 PostToolUse 监听所有的 Write 和 Edit 操作。每当文件发生物理变更，Hook 脚本就会将文件路径记录到 .claude/session_context.json 中。

# 伪代码逻辑
if [ "$TOOL_NAME" == "Edit" ]; then
  echo "$TARGET_FILE" >> .claude/context/modified_files.log
  # 甚至可以自动触发 git add
  git add "$TARGET_FILE"
fi

当我下次问“我今天改了哪些文件？”时，Claude 可以读取这个日志，精准回答，而不是靠幻觉瞎编。

闭环质量防御 (Stop)

这是从“玩具”到“工具”的质变。

在 Stop 钩子中，我不仅运行格式化工具（Prettier），更关键的是运行编译检查。

强力模式： 如果 tsc (TypeScript Compiler) 检查失败，Hook 可以配置为拒绝停止。它会将错误日志反向喂给 Claude，并指令：“编译未通过，请修复这些错误后再结束任务。”

这构成了自动化的 ReAct (Reasoning + Acting) 循环，直到代码真正跑通。

配置指南与最佳实践

标准配置模板

我推荐在项目根目录 .claude/settings.json 中使用如下配置，兼顾扩展性与维护性：

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-injector.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/file-tracker.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/auto-format.sh" },
          { "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/build-verifier.sh" }
        ]
      }
    ]
  }
}

进阶调优技巧

1. 性能陷阱：Hooks 是同步执行的。如果我的 PostToolUse 脚本要跑 5 秒，Claude 就会卡住 5 秒。
   • 对策：将耗时操作（如重型分析）放入后台运行（nohup ... &），或者仅对增量文件进行检查。
2. 环境隔离：Hook 脚本中的 $PATH 可能与我的终端不同。
   • 对策：在脚本开头显式 source ~/.zshrc 或使用绝对路径调用工具（如 /usr/local/bin/npm）。
3. 调试黑盒：当 Hook 不工作时，Claude 不会报错，只会默默失败。
   • 对策：在脚本头部加上 set -x，并将日志输出到标准错误流 >&2。Claude 会将 stderr 的内容显示在调试日志中。

结语

Claude Code Hooks 的本质，是将 Software 1.0 (明确的代码逻辑) 的力量赋予 Software 2.0 (神经网络)。

通过合理配置 Hooks，我不再是被动地“使用” AI，而是将 AI 作为一个高智商的模块，集成到我要严密的软件工程体系中。这才是 Agent 开发的终极形态。

---

下一篇预告：Claude Code #5-斜杠命令- 学习如何配置自定义命令工具。