Claude Hooks

Claude Hooks 是 Claude Code 内置的事件驱动自动化系统，能够响应开发工作流中的特定事件执行 shell 脚本。与提供建议的 Skills 不同，Hooks 提供执行力 - 它们是真正可执行的脚本，可以根据编码会话中发生的事情进行验证、阻止、注入上下文或触发操作。

Hooks 将 Claude Code 从 AI 助手转变为可编程的开发环境，你可以定义规则、标准和集成，无需依赖 LLM 的理解即可自动执行。

核心功能

1. 五种 Hook 事件类型

Claude Code 支持不同生命周期事件的 hooks：UserPromptSubmit（提示提交时）、PreToolUse（工具执行前）、PostToolUse（工具执行后）、Stop（会话结束前）和 SubagentStop（子代理完成时）。每个事件提供特定的上下文和控制点。

2. 退出码控制机制

Hooks 通过具有特殊含义的退出码进行通信：exit 0 正常继续，exit 1 发出警告但允许继续，exit 2 阻止并强制 Claude 修复问题。这创建了一个"建议 + 执行"系统，hooks 实际上可以阻止编写或提交不良代码。

3. 真实的 Shell 脚本执行

Hooks 是使用系统权限运行的实际 bash/shell 脚本，不依赖于 LLM 解释。可以运行 linters、测试、部署、API 调用、数据库查询或任何命令行工具，作为 AI 辅助工作流的一部分。

4. 双向通信

Hook 脚本可以通过 stdout/stderr 向 Claude 发送消息，直接将上下文、验证结果或指令注入到对话中。Claude 将 hook 反馈视为用户输入，创建反馈循环。

5. 基于插件的分发

Hooks 与 Skills 和 MCP 服务器一起作为插件的一部分打包和共享。使用 /plugin install 安装完整的工作流包，获得预配置的验证、测试和部署自动化。

6. 环境和上下文访问

Hooks 接收环境变量、工具参数、文件路径和会话上下文。访问当前 git 分支、更改的文件、工具名称、参数等，做出智能决策。

适用场景

谁应该使用 Claude Hooks？

• DevOps 工程师：自动化部署验证、基础设施检查和环境设置
• 质量保证团队：执行测试要求、代码覆盖率阈值和 lint 标准
• 安全团队：扫描漏洞、验证权限、防止提交机密信息
• 开发团队：标准化提交消息、PR 要求和代码审查流程
• 企业组织：执行合规政策、审计跟踪和治理规则

解决的问题

1. 手动质量门控：消除忘记运行测试或 linters - hooks 在提交或会话结束前自动执行它们
2. 上下文丢失：将当前 git 状态、环境信息或项目特定细节注入到每次 Claude 交互中
3. 安全风险：防止意外提交机密信息、访问敏感文件或破坏性操作
4. 集成差距：将 Claude Code 与现有工具桥接 - Slack、JIRA、监控系统、CI/CD 管道
5. 团队标准执行：确保每个人都遵循相同的编码标准、提交约定和工作流

Hook 事件类型和示例

UserPromptSubmit Hook

触发时机：用户向 Claude 提交提示时

常见用途：

• 注入 git 状态和当前分支信息
• 添加项目特定上下文或约定
• 记录用户请求以进行分析
• 用户输入的安全筛查

示例：

#!/bin/bash
# hooks/user-prompt-submit.sh

BRANCH=$(git branch --show-current)
echo "📍 当前分支: $BRANCH"

if [[ -n $(git status --porcelain) ]]; then
  echo "📝 有未提交的更改"
fi

exit 0

PreToolUse Hook

触发时机：任何 Claude Code 工具执行前（Read、Write、Edit、Bash 等）

常见用途：

• 读/写前验证文件权限
• 阻止访问敏感文件或目录
• 限制昂贵操作的速率
• 记录工具使用模式

示例：

#!/bin/bash
# hooks/pre-tool-use.sh

if [[ "$TOOL_NAME" == "Read" ]] && [[ "$FILE_PATH" =~ \.env|credentials|secret ]]; then
  echo "⚠️ 已阻止：尝试读取敏感文件 $FILE_PATH"
  exit 2  # 阻止执行
fi

exit 0

PostToolUse Hook

触发时机：工具调用成功完成后

常见用途：

• 验证工具输出
• 为特定操作发送通知
• 收集指标和分析
• 触发后续自动化

示例：

#!/bin/bash
# hooks/post-tool-use.sh

if [[ "$TOOL_NAME" == "Bash" ]] && [[ "$COMMAND" =~ deploy ]]; then
  curl -X POST $SLACK_WEBHOOK \
    -d '{"text":"🚀 Claude Code 触发了部署"}'
fi

exit 0

Stop Hook

触发时机：Claude Code 准备退出或完成会话之前

常见用途：

• 运行最终质量检查（lint、测试、类型检查）
• 确保所有更改都已提交
• 清理临时文件
• 生成会话报告

示例：

#!/bin/bash
# hooks/stop-hook.sh

echo "🔍 运行最终质量检查..."

if ! npm run lint; then
  echo "❌ Lint 失败。请在退出前修复。"
  exit 2  # 强制 Claude 修复问题
fi

if ! npm test; then
  echo "❌ 测试失败。请在退出前修复。"
  exit 2
fi

echo "✅ 所有检查通过！"
exit 0

SubagentStop Hook

触发时机：子代理完成其委托任务时

常见用途：

• 审查子代理工作质量
• 聚合多个子代理的结果
• 验证委托任务完成情况
• 记录子代理性能

与 Claude Code 生态系统的集成

Skills + Hooks = 完整的工作流自动化：

• Skills 提供知识和建议（做什么和如何做）
• Hooks 执行规则和标准（必须做和不能做）
• 一起创建"建议 + 执行"系统

插件打包：

• Hooks 作为插件的一部分分发
• 插件捆绑：Skills + Hooks + MCP 服务器 + 命令
• 安装完整工作流：/plugin install @team/code-standards

MCP 集成：

• Hooks 可以验证 MCP 工具调用
• PreToolUse/PostToolUse 拦截外部工具操作
• 确保第三方集成遵循你的政策

分层架构：

优势对比

相比竞品的优势：

1. 真正的执行 vs 建议：与 Cursor/Copilot 只提供建议不同，hooks 通过退出码实际阻止不良操作
2. 真实代码执行：Hooks 是实际的 shell 脚本，不依赖可能被忽略的 LLM 配置
3. 生命周期覆盖：从提示到工具执行再到会话结束的每个阶段都有 hooks
4. 开放分发：没有审批流程 - 自由创建和共享插件，不像供应商市场
5. 基于标准：MCP 协议实现跨工具和平台的互操作性

独特卖点：

• AI 无法绕过的可编程质量门控
• 通过可执行脚本完全控制 AI 行为
• 与任何命令行工具或 API 集成
• 拥有 500+ 插件的社区驱动插件生态系统
• 无供应商锁定 - 脚本永远属于你

使用技巧

1. 清晰的退出码：使用 exit 0 表示成功，exit 1 表示警告，exit 2 强制修复 - 对控制流保持明确意图
2. 描述性消息：回显清晰的消息，解释 hooks 正在做什么以及为什么阻止
3. 幂等脚本：确保 hooks 可以安全地多次运行而不产生副作用
4. 错误处理：包括 try-catch、验证输入、优雅处理边缘情况
5. 安全优先：永远不要硬编码机密、验证所有输入、使用最小权限
6. 模块化设计：为特定目的创建专注的 hooks，而不是单体脚本
7. 充分测试：在部署到团队之前使用各种场景测试 hooks

常见问题

Hooks 有什么权限？

Hooks 以用户的 shell 权限运行。它们可以访问文件、运行命令和发起网络请求，就像你手动运行的任何脚本一样。

Hooks 可以访问敏感数据吗？

可以，这就是为什么你应该在安装插件之前审查 hook 脚本。只使用来自可信来源的 hooks 或编写自己的。

如果 hook 失败会发生什么？

取决于退出码：exit 1 记录警告但继续，exit 2 阻止操作并强制 Claude 在继续之前修复问题。

我可以临时禁用 hooks 吗？

可以，你可以通过 Claude Code 设置禁用特定 hooks 或整个插件，而无需卸载它们。

Hooks 可以离线工作吗？

可以，hooks 是本地 shell 脚本，无论互联网连接如何都会执行。只有 hooks 中的外部 API 调用需要网络访问。

如何调试 hook 脚本？

Hook 的 stdout/stderr 出现在 Claude 的对话中。添加 echo 语句进行调试，或从命令行手动运行 hooks 进行测试。

真实案例

质量门控执行

Sionic AI 每天运行 1000+ 个机器学习实验。他们的 Stop hooks 验证 GPU 配置、框架参数，并在启动昂贵的训练运行之前防止已知的失败路径。

安全扫描

PreToolUse hooks 在允许文件写入或提交之前扫描硬编码的机密、API 密钥或凭据，防止意外暴露。

团队工作流标准化

PostToolUse hooks 执行提交消息约定、运行自动代码格式化，并触发 CI/CD 管道，确保团队的一致性。

集成自动化

Hooks 在部署发生时发送 Slack 通知，在代码提交时更新 JIRA 工单，并自动将指标记录到监控系统。

替代方案

如果 Claude Hooks 不适合，可以考虑：

• GitHub Actions：更适合基于云的 CI/CD，但未与本地 AI 工作流集成
• Git Hooks：类似概念，但仅适用于 git 事件，不适用于 AI 工具交互
• Make/Task Runners：适合手动工作流，但缺乏 AI 集成和事件触发器
• Cursor Rules：基于配置，但缺乏执行力和可执行脚本

总结

Claude Hooks 代表了开发者与 AI 助手合作方式的根本转变。通过提供可执行、可执行的规则而不仅仅是建议，hooks 确保你的 AI 在团队标准内协作，并与现有工具和工作流无缝集成。

无论是执行代码质量、防止安全问题、自动化部署还是与基础设施集成，hooks 都为你提供了对 AI 辅助开发工作流各个方面的可编程控制，而无需依赖 LLM 来理解和遵循你的规则。