一、Hooks 的主要定位

Claude Code Hooks 是一套面向 AI Agent 执行生命周期的事件驱动 机制。它允许在工具执行、任务创建、执行前后等关键节点注入自定义逻辑，这样就能实现对 Claude 工作流的约束与自动化提高。

痛点：在实际项目中。常常缺少统一的安全校验和日志记录，导致危险命令直接被执行或调试信息散落难以追踪。说起来，Hooks 正是为了解决这些痛点而设计的。

其运行方式如下：

• 事件监听：Claude 在特定 Agent 生命周期节点触发 Hook 事件。
• 脚本执行：程序根据配置调用本地或远程脚本。不过，
• 上下文注入：脚本通过标准 JSON 输入获取当前执行上下文。
• 结果反馈：脚本通过退出码与结构化输出影响工具执行结果。

二、Hooks 配置文件

项目级别的 Claude Code Hooks 配置通常放在：

.claude/settings.json

示例 JSON：

{
"hooks": {
"事件名":
}
]
}
}

matcher 与 if 的区别

1. matcher：监听哪个工具

• 只监听 Bash 工具

  "matcher": "Bash"

• 监听文件写入类工具

  "matcher": "Write|Edit"

• 监听 GitHub MCP 工具

  "matcher": "mcp__github__.*"

2. if：这个工具的哪些调用才触发

• Bash 工具里只有 git push * 才触发

  "if": "Bash"

二者同时满足才执行：

matcher = 工具级过滤
if = 调用级过滤

三、主要的 Hook Event 与输入机制

Hook 的输入机制

Claude 内部事件发生
↓ 构造 JSON payload
↓ 写入 hook 程序 stdin
↓ 执行你的脚本
↓ 读取 stdout / exit code / stderr
↓ 决定是否阻断 / 附加信息 / 继续执行
exitcode=2 表示阻止执行，exitcode=0 表示继续执行

PreToolUse

场景痛点：团队经常担心 AI 自动运行危险命令（如 rm -rf /) 或误操作生产环境。通过 PreToolUse 可以提前拦截。

• 禁止 rm -rf *
• 禁止生产库操作

settings.json 示例：

{
"hooks": {
"PreToolUse":
}
]
}
}

check-dangerous.py 实现:

import json,sys,os
data = json.load
cmd = data.get.get
log_path = os.path.join。"hook.log")
with open as f:
f.write
f.write}
")
dangerous =
for d in dangerous:
if d in cmd:
with open as f:
f.write
print
sys.exit # 非零退出码阻止执行
with open as f:
f.write
sys.exit

If Claude tries to run:

rm -rf node_modules

The script will block it and return:

Blocked dangerous command: rm -rf node_modules

PostToolUse

痛点：Linter/Formatter 常被忘记手动运行，导致代码质量下降。PostToolUse 能自动化这些收尾工作。

• Linter 自动化
• 代码格式化 变更记录写入日志 自动补充上下文

  {
  "hooks":{
  "PostToolUse":
  }
  ]
  }
  }
  
  
  #!/bin/bash
  npm run eslint
  npm run prettier
  
  
  UserPromptSubmit
  
  Pain point:Sensitive information may slip into prompts;team conventions are often forgotten.
  
  
  PROMPT
  自动注入规范 敏感词过滤
  
  
  
  
  {
  "hooks":{
  "UserPromptSubmit":
  }
  ]
  }
  }
  <
  / code>
  / pre>
  
  
  
  
  
  import json,sys
  data = json.loads )
  prompt = data.get
  rules = """. 不允许修改 public API. 必须兼容 Vue2. 必须写中文注释"""
  if "" not in prompt:
  data = prompt + "\ n"+ rules
  print。flush=True )
  <
  / code>
  / pre>
  
  
  Stop 
  
  **Pain point** : After a task finishes re is often no automated verification or logging.
  
  
  li>最终检查 li>
  li>自动测试 li>
  li>自动 li>
  li>自动提交日志 li>
  ul>
  
  
  
  
  
  
  echo “Running tests…”
  mvn test
  <
  / code>
  / pre>
  
  CwdChanged 
  
  **Pain point** : 手动切换虚拟环境或加载 .env 文件容易忘记，导致后续命令失效。
  
  
  li> 自动切换 Python venv li>
  li> 自动加载 .env li>
  li> 自动切换 MCP 配置 li>
  ul>
  
  
  
  
  
  
  if;n
  export $
  fi
  <
  / code>
  / pre>
  
  TaskCreated 
  
  **Pain point** : 缺少子任务生成日志，审计困难。
  
  
  
  
  import json,sys
  data = json.load
  print
  print )
  <
  / code />
  / pre>
  
  
  
  WorktreeCreate 
  
  **Pain point** : 多 Agent 并行工作时缺乏统一记录导致难以追踪每个 worktree 的状态。
  
  
  >
  json
  {
  “hooks”: {
  “WorktreeCreate”:
  }
  ]
  }
  }
  
  
  
  >
  python
  import json,sys
  
  data = json.load
  wt = data.get
  print
  print)
  print)
  print)
  
  
  PreCompact 
  
  **Pain point** : 当上下文被压缩时关键信息可能丢失。PreCompact 可用于阻止压缩或做快照保存。
  
  
  >
  json
  {
  “hooks”: {
  “PreCompact”:
  }
  ]
  }
  }
  
  
  
  >
  python
  import json,sys
  
  payload = {
  “decision”: “block”,“reason”: “大型重构进行中。禁止压缩上下文”
  }
  
  print)
  sys.exit
  
  
  四、Hook Type 
  
  Claude Hooks 当前支持以下几种类型： 
  
  
  command 
  
  prompt 
  
  agent 
  
  http 
  
  / ul/>
  
  Command Hook
  
  = shell 、 python 、 node 、 bash 等常见解释器。适用于安全检查、lint、部署脚本等场景。说起来，
  
  Prompt Hook  
  
  适用于需要“再让模型判断”的情形。例如在 Stop 时检查代码是否全部修改完成、是否还有未解决 TODO 等。
  
  示例 Prompt Hook 配置：,json
  {
  “hooks”:{ “Stop”:
  }]
  }]
  }
  注意： 可配置 timeout 防止无限等待。
  
  
  
  Agent Hook 
  
  重量级方案——启动一个子 Agent 完整地验证或修复代码。例如在 Stop 时启动一个专门负责 Clean Architecture 检查的 Agent。
  
  示例 Agent Hook 配置：,json
  {
  “hooks”:{
  “Stop”:
  }
  ]
  }
  }
  适用场景： 复杂业务规则校验、大规模重构后的质量审查。
  
  
  
  HTTP Hook 
  
  将事件转发到公司内部 webhook 或 CI 程序，实现统一监控与审计。说起来，
  
  示例 HTTP Hook 配置：。json
  {
  “hooks”：{
  ”PostToolUse”：
  }
  ]
  ​ }
  ​ }
  ​
  ​ 注意事项：
  ​ • POST 内容为完整 event payload；​ • 响应体可返回 decision 阻止后续操作。​ ​
  
  
  
  MCP Tool Hook 
  
  利用 Claude 自带的 MCP 工具程序直接对外发送消息，例如 Slack 通知、邮件提醒等。
  
  示例 MCP Tool Hook 配置 ： ,json
  {
  ”hook”：{
  ”stop”。}
  ]
  }
  ​
  ​​ ​
  ​ 适用场景：
  ​ • 项目部署完成后即时通知；​ • 错误告警推送至运维渠道。​​ ​
  
  
  
  五、Skill Scoped Hooks 
  
  
  🔥Pain Point:          >>>>>">Hook 不一定是全局生效。它可以只在某个 Claude Skill 中生效，以避免跨项目冲突。
  
  
  💡普通 Global Hook vs Skill Scoped Hook
  
  
  
  
  类型
  作用范围
  Global hook任何 Bash 都会触发
  Skill hook仅在当前 skill 生效
  
  
  
  
  
  
  
  Scope
  说明
  global所有对话均会触发
  skill仅在定义该 skill 时触发
  
  
  
  
  
  
  
  PRE CODE BLOCK HERE:
  
  --- name ：production-deploy 
  
  说到HOOKS。
  
  PRETOOLUSE：
  
  — MATCHER：“BASH”
  
  — TYPE：“COMMAND”
  
  COMMAND：“./scripts/prod-safety-check.sh”
  
  至于ONCE，TRUE
  
  THE END