还在用“记得跑一遍测试”“改完代码先别提交我要看看 diff”这种话一遍遍提醒 Claude Code说实话我一开始也是这么干的直到我把同一句叮嘱重复到第十遍它依然在改完代码后兴冲冲地停在那里等我验收我才意识到问题不在提示词而在架构。Claude Code 作为命令行里的 AI 编程助手核心优势是能直接读写文件、执行命令、操作 git。但“能力越大破坏力越大”你越放任它自由发挥越需要一套机制去约束它的行为。Hooks 就是专门干这件事的在特定事件触发的瞬间自动跑一段你写好的脚本把规则、检查、拦截、收尾全部自动化。相当于给 AI 装了一整套条件反射不用你开口它就知道什么该做、什么不该做。这篇文章我会从 Hooks 的触发原理讲起再给出我实际项目中正在用的配置方案、脚本模板和踩坑记录。无论你是刚装好 Claude Code 的新手还是被“反复提醒”折磨了很久的老用户这套东西都能直接改吧改吧用到你的工作流里。1. 为什么要用 Hooks把“人肉提醒”变成“系统默认”1.1 反复提醒的根源上下文是易失的先说一个扎心的事实Claude Code 的记忆本质上是非常脆弱的。上下文窗口再大也有被压缩、被截断的一天。你以为它记住了“改完代码必须跑测试”这条规则实际上等上下文滚动几轮之后这条约定已经被挤到边缘位置它自己都未必看得见。就算它记得每次调用工具前它都要现场判断一次“现在要不要跑测试”。这个判断受措辞、情绪、上下文位置的影响天然带有随机性。你今天换个方式写提示词它可能就忘了。这就是为什么你会陷入“反复提醒—它偶尔照做—你再提醒”的循环。更坑的是每一次提醒都在占用上下文空间。一条“记得跑测试”看着没几个字但架不住你说十遍、二十遍。这些重复内容挤占了真正重要的业务信息让 AI 处理代码的效率反而更低了。1.2 Hooks 解决的核心矛盾Hooks 的思路和“写更多提示词”完全不同。它把约定从对话层下沉到了执行层。你不再需要让 AI“记得”做某件事而是让某个事件发生时操作系统直接替你把这个动作做掉。举个例子。我现在的项目里配置了一条 PostToolUse 钩子只要 Claude 用 Edit 或 Write 工具改过文件就自动执行npm run lint并把 lint 结果反馈给 Claude。从那以后我再也没有在同一件事上重复叮嘱过它。它改完代码脚本自动跑检查有错就当场改没错就继续往下走。整个链路非常顺滑。你还可以做更多超出对话能力的事情在它执行rm -rf前拦截、在上下文压缩前把关键结论写进临时文件、在每次会话开始时把团队规范注入进去。这些都不是“更聪明的提示词”能做到的而是机制层面的保障。1.3 什么场景下 Hooks 收益最大从我自己的项目和身边朋友的反馈来看以下几类人用 Hooks 的收益格外明显长期在大型代码仓库里用 AI 干活的人。仓库越复杂AI 越容易“闯祸”提前拦截和自动保护越有价值。团队协作场景。把 Hooks 配置提交到项目仓库里所有人都共享同一套约束规则AI 的行为风格高度统一。自由职业者和独立开发者。经常隔几天才回来接着做不可能每次重新交代一遍项目规范Hooks 替你做了。对 AI 生成的代码不放心、又懒得逐行检查的人。用 PreToolUse 拦截高风险命令用 PostToolUse 自动跑测试风险面能收敛很多。2. Hooks 机制拆解事件、脚本与生命周期2.1 核心事件类型与触发时机Claude Code 的 Hooks 支持多类事件我用下来最有存在感的几类给你列一下PreToolUseAI 调用任何工具之前触发。最典型用途是拦截危险命令或者给某些工具提前注入上下文。PostToolUse工具执行完成之后触发。自动 lint、自动格式化、记录执行结果都在这一层做。StopClaude 结束本轮回复之后触发。适合做收尾动作比如整理变更清单、更新 CHANGELOG。PreCompact上下文即将被压缩之前触发。可以把当前任务的关键状态写到外部文件防止压缩后“失忆”。SessionStart新会话开始瞬间触发。适合加载项目规范、检查依赖环境、拉取最新配置。SessionEnd会话结束时触发。清理临时文件、生成工作总结、汇报会话统计都可以挂这里。UserPromptSubmit用户提交 prompt 的瞬间触发可以在问题进入模型之前做拦截或改写。这些事件之间不是互斥的一个项目里可以同时挂多个。真正的关键是想清楚每种事件该管什么别把 PostToolUse 该做的事塞到 Stop 里你会明显感觉响应变“迟钝”。2.2 Hook 脚本的输入、输出与退出码约定这是我发现新手最容易踩坑的地方。记住三个核心约定基本就打通了第一脚本启动时stdin 会收到一段 JSON。里面包含 session_id、transcript_path、tool_name、tool_input 等字段具体内容随事件类型不同。比如 PreToolUse 里你能拿到 AI 准备执行的命令原文Stop 里你能拿到这一轮完整对话的记录路径。很多钩子脚本的第一步就是解析这份 JSON。第二stdout 的内容会反馈给 Claude。你在脚本里 print 出来的文本Claude 能在后续对话中直接看到。这是整个机制最“智能”的一点PostToolUse 里跑完 lint 输出的报错信息AI 看到后会自动去修改。你不传它就不知道刚才发生了什么。第三退出码决定流程是否继续。0 表示成功流程正常往下走2 在 PreToolUse 里是特殊含义表示“拒绝工具调用”stdout 内容会作为拒绝原因给 Claude 看其他非 0 退出码会被当成错误处理往往会中止当前动作并在界面上标记失败。我整理了一张常用组合表方便你对照着写事件stdin 关键字段常见用途期望退出码PreToolUsetool_name、tool_input危险命令拦截、权限控制0 放行2 拒绝并附原因PostToolUsetool_name、tool_input、output自动 lint、格式化、记录结果0 成功非 0 标记失败Stoptranscript_path代码提交、文档更新0 成功PreCompacttranscript_path保存上下文快照0 成功SessionStartsession_id、cwd注入规范、环境检查0 成功2.3 配置方式settings.json 与 claude hook 命令Hooks 的配置统一放在 settings.json 里分项目级和用户级。项目级位置是.claude/settings.json跟着代码仓库走适合团队共享用户级在~/.claude/settings.json是个人全局配置。配置结构长这样{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: python .claude/hooks/pre_tool_bash.py } ] } ], PostToolUse: [ { matcher: Edit|Write|MultiEdit, hooks: [ { type: command, command: bash .claude/hooks/post_tool_lint.sh } ] } ] } }matcher用来匹配工具名称支持正则。Bash只匹配终端命令Edit|Write|MultiEdit匹配所有文件修改类工具。如果你想全局匹配所有工具直接设成*就行。除了手改 settings.json也可以直接用命令claude hook add添加Claude Code 会引导你选择事件类型、工具匹配范围和要执行的命令。我个人的习惯是先用命令加一次生成标准的格式再手动改脚本逻辑这样格式不容易出错。3. 实战从零搭建一套 Hooks 工作流3.1 环境准备与最小可用配置动手之前先把基础环境准备好。你需要确认几件事Claude Code 已安装并完成登录授权claude --version能看到版本号。项目路径下存在.claude目录没有就mkdir -p .claude/hooks创建。准备好脚本运行环境。我建议 Hook 脚本统一用 bash 或 Node.js 写这两个环境 Claude Code 的底层都默认支持不容易出兼容问题。用jq解析 JSON。如果你的机器没装先装一下解析 stdin 数据会省很多力。然后创建一个最小配置先跑通“Hello World”再说。编辑.claude/settings.json{ hooks: { Stop: [ { matcher: *, hooks: [ { type: command, command: echo [hook] Claude has finished this round .claude/hook.log } ] } ] } }然后随便让 Claude 做一件事比如让它“读一下当前目录的文件”。等它回复结束后打开.claude/hook.log。如果能看到那行标记说明 Hooks 链路已经通了。这一步千万别跳过很多人后面配置半天不生效回头查才发现一开始就是配置没加载成功。3.2 场景一改完代码自动跑 lint 并回传结果这是 Hooks 最常见的实用场景。Claude 改完代码自动触发 lint并把结果回传给它。先写 Hook 脚本.claude/hooks/post_tool_lint.sh#!/bin/bash # 读取 PostToolUse 的 JSON 输入 input$(cat) # 可以在这里基于 input 做更多逻辑比如判断修改的文件列表 # 这里直接从项目根目录跑 lint固定路径 cd $CLAUDE_PROJECT_DIR || exit 1 # 执行 lint并把输出原样打印到 stdout npm run lint 21 # 无论 lint 是否通过都返回 0 # 返回 0 的目的是让 Claude 正常继续lint 结果作为上下文给它看 exit 0然后注册到 PostToolUse{ hooks: { PostToolUse: [ { matcher: Edit|Write|MultiEdit, hooks: [ { type: command, command: bash .claude/hooks/post_tool_lint.sh } ] } ] } }关键点在于脚本里的npm run lint 21输出了完整结果而exit 0让它不会中断主流程。这样每次 Claude 改完文件lint 结果会自动出现在它的上下文里它能看到错误就继续修。实测下来AI 的修复准确率会明显提升因为它不再靠“猜”哪些文件有问题而是直接读取到了真实的检查报告。如果你的项目用的是 ESLint 自动修复可以加一条npm run lint -- --fix再做一次格式化。不过注意自动修复后的代码还会再次触发 PostToolUse要小心死循环。一个简单的防护方法是在脚本里检查 git diff如果没有变化就直接退出。3.3 场景二拦截危险命令给 AI 立规矩Claude Code 最让人不放心的地方是它会执行终端命令。虽然它平时很谨慎但在上下文混乱时可能做出rm -rf、git push --force这类危险操作。PreToolUse 就是最后一道闸。先写拦截脚本.claude/hooks/pre_tool_bash.py#!/usr/bin/env python3 import json import sys import re data json.load(sys.stdin) tool_input data.get(tool_input, {}) command tool_input.get(command, ) dangerous_patterns [ r\brm\s-rf\s/, r\bgit\spush.*--force, r\bcurl\s.*\|\s*(ba)?sh, ] for pattern in dangerous_patterns: if re.search(pattern, command): # 输出拒绝原因exit 2 表示拒绝工具调用 reason f这条命令被 Hooks 拦截了{command} print(reason) sys.exit(2) # 放行 sys.exit(0)注册到配置{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: python .claude/hooks/pre_tool_bash.py } ] } ] } }这里有个细节exit 2后脚本 stdout 的内容会作为“拒绝原因”反馈给 Claude。你可以在原因里写清楚为什么不许执行甚至给出替代方案。Claude 看到后通常会自己调整策略比如改成“先列出文件再确认删除”。建议你拦截清单里不要把git push一棒子打死而是只拦--force。否则日常推送也被卡住你的开发效率会很难受。3.4 场景三PreCompact 保存关键上下文用 Claude Code 干长任务时上下文窗口会被慢慢塞满触发自动压缩。压缩后 Claude 容易“忘记”前期的重要结论。PreCompact 钩子可以在压缩发生前把关键信息保存到外部文件。脚本.claude/hooks/pre_compact.sh示例#!/bin/bash input$(cat) # 提取当前时间作为快照标识 timestamp$(date %Y%m%d_%H%M%S) snapshot_file.claude/context_snapshot_${timestamp}.md # 把最近一段对话记录的关键结论写入快照文件 # 实际项目中你可以让 Claude 在对话里输出任务状态然后这里 grep 出来 echo # Context snapshot at ${timestamp} $snapshot_file echo Transaction path: $(echo $input | jq -r .transcript_path // empty) $snapshot_file echo 请查看最近的对话记录总结当前任务进度然后继续执行。 $snapshot_file exit 0配置加到 PreCompact{ hooks: { PreCompact: [ { matcher: *, hooks: [ { type: command, command: bash .claude/hooks/pre_compact.sh } ] } ] } }关于 PreCompact 有一个更进阶的玩法在这个钩子脚本里你可以用 Claude Code 自己的 CLI 命令把当前目录的关键信息再喂回去比如执行一次claude -p 基于当前上下文输出当前任务进度和下一步计划 --output-format json然后把结果写入快照。压缩后的新上下文可以在 SessionStart 或用户提示词里引用这个快照文件相当于给 AI 做了一个外部“记忆库”。3.5 场景四SessionStart 注入团队规范如果你在团队里用 Claude Code最头疼的一件事就是不同成员的 AI 行为风格不统一。有人让它用 TypeScript有人让它写 JavaScript。SessionStart 钩子能解决这个问题。脚本.claude/hooks/session_start.sh#!/bin/bash # 把团队规范文件注入到对话开始时的上下文 if [ -f .claude/team-rules.md ]; then echo 以下是团队约定请严格遵守 cat .claude/team-rules.md fi exit 0配置{ hooks: { SessionStart: [ { matcher: *, hooks: [ { type: command, command: bash .claude/hooks/session_start.sh } ] } ] } }.claude/team-rules.md里可以写“统一使用 2 空格缩进”“禁止修改 package-lock.json”“提交信息遵循 conventional commits”之类的规则。每次会话开始这些内容就会自动进入 Claude 的上下文比你在提示词里手动加一大段强多了。这个文件建议提交到 git 仓库里团队成员 pull 下来就自动生效规范和代码一起走版本管理。3.6 调试与验证怎么确认 Hooks 真的生效了配置 Hooks 最怕的就是“以为生效了实际没有”。我有几个自己的排查顺序最简单的验证方式是在每个脚本开头加一行日志比如echo Hooks triggered: $(date) .claude/hook_debug.log。这样一来只要脚本跑过日志里就有记录。如果想看实时效果打开 Claude Code 的详细日志模式。在会话中执行/status能看到当前配置摘要执行/hooks可以直接查看已经注册的钩子列表。还有一个小技巧故意触发一次 Hooks 规则里的操作。比如你配置了 PostToolUse 自动 lint那就让 Claude 新建一个带语法错误的文件看它会不会自己修复。如果它没反应优先检查 matcher 是否匹配到了正确的工具名。4. 常见问题与排查技巧实录4.1 Hook 不执行 / 配置不生效这是问得最多的问题。实际原因十有八九是配置文件加载顺序错了或者目录不对。Claude Code 的配置加载优先级是命令行参数 项目级 settings.json 用户级 settings.json。如果你项目里配了 Hooks但用户级配置里也有同名事件到底执行哪个需要先搞明白。我的建议是团队项目用项目级配置个人习惯用用户级配置两者不要写重复的事件。否则排查时你会一头雾水。另外注意 matcher 是正则匹配不是简单的字符串包含。比如你想匹配所有工具就要用*而不是留空。留空的 matcher 在某些版本里不会匹配任何工具。4.2 脚本卡死 / 超时Hook 脚本跑太久会拖慢 Claude Code 的整体响应甚至触发超时中断。常见原因是脚本里有交互式命令在等输入比如git diff等待分页器、npm install等待确认。解决办法脚本开头统一加export CI1或者export DEBIAN_FRONTENDnoninteractive强制命令进入非交互模式。所有命令都加--non-interactive或取消输入等待的选项。还有一个我们实测遇到的坑在 Hook 脚本里调用claude命令行本身容易产生死锁。因为 Claude 正在等脚本退出而脚本又在启动一个新的 Claude 进程。如果确实需要嵌套调用记得加--max-turns 1并且使用timeout包裹。但我建议尽量别这么干能避免就避免。4.3 退出码冲突为什么用了 exit 2 没拦住很多人跟我反馈“我在 PreToolUse 里写了 exit 2怎么命令还是执行了”问题多半出现在脚本里还有其他退出语句。比如你想在 Python 脚本里拒绝某个命令但脚本中间有个地方调用了sys.exit(0)或者有一个未捕获的异常导致退出码变成 1那么 PreToolUse 的语义就变了。非 0 退出码不一定等于“拒绝”在部分场景下会被当成错误直接中止工具调用而中止不等于拒绝Claude 可能换一种方式重试。我的经验是PreToolUse 的拒绝逻辑要写得非常明确只在最后一行做退出判断而且退出码和 stdout 同时设置。千万不要在脚本里多个位置分散退出更不要依赖异常退出来表示拒绝。4.4 跨平台问题Windows / macOS / Linux 的差异Claude Code 在三个平台都能跑但 Hooks 脚本的兼容性很容易出问题。Windows 原生环境没有 bash如果你写了 bash 脚本大概率会执行失败。解决方案有两个一是在 Windows 上优先用 PowerShell 脚本或者用 Git Bash 的完整路径调用 bash。二是在项目里同时提供.sh和.ps1两个版本在配置里用环境判断写不同的命令。还要注意换行符问题。如果项目在 Windows 上 checkout 出 CRLF 换行bash 脚本可能会报错找不到命令。建议在项目根目录加一个.gitattributes把.claude/hooks/目录下的脚本强制为 LF 换行。4.5 性能与并发别让 Hook 拖慢主流程Hook 脚本虽然强大但每次触发都会产生额外开销。一个常见的反模式是 PostToolUse 里跑全量测试套件然后每次改文件都要等几十秒。我的建议是给 Hook 脚本设一个“轻量优先”原则默认只跑快速检查lint、prettier、类型检查把全量测试放到 Stop 事件里。测试需要的昂贵操作可以加一个速率限制比如记录上次执行时间一分钟内只跑一次。这样既不会漏掉关键检查也不会让交互节奏变得黏滞。另外如果你的项目并行调用了多个工具Hooks 脚本也可能是并发执行的。脚本里不要假设只有一个实例在跑写到同一个临时文件时要加锁或者给每个进程用独立的文件名。5. 最后说两句实在话把 Hooks 用起来之后最直观的感受是“AI 终于带上脑子了”。不是它的模型变聪明了而是你给它装了护栏和例行程序。它不需要每次都在“要不要跑测试”这种问题上犹豫你也不需要一遍遍重复同样的话。如果你打算马上动手改造工作流我的建议是最小化起步先挂一个 PostToolUse 自动 lint再挂一个 PreToolUse 拦截危险命令。这两条跑顺了再慢慢扩展到 Stop 收尾、PreCompact 保存上下文、SessionStart 注入规范。别一上来就配十几个钩子你会被自己的调试成本劝退。Hooks 的价值不是一次性配置完就完了。它会随着你项目的演进、你对 AI 信任度的变化而调整。今天你觉得需要拦的明天可能就不需要了昨天没想到的自动化点可能某次踩坑之后就冒出来了。这个调整过程本身就是用 AI 编程最真实也最有意思的部分。