Claude Code Hook 开发：官方 Skill 把拦截机制讲透了

说个很多人用 Claude Code 都会踩的坑：工具调用没有任何拦截机制，你让 AI 写文件它就写，你让它执行危险命令它也执行。等到反应过来，代码已经被改得面目全非了。

其实 Claude Code 早就给了解法——Hooks。只是文档散落在各处，真正用好的人不多。

最近翻到一个官方 Skill 叫 hook-development，来自 Anthropic 官方，文档写得非常系统，忍不住来分享一下。

Hook 是什么？

Hook 就是在 Claude Code 执行过程中插入干预点的事件驱动脚本。你可以在：

• PreToolUse：工具执行前——验证/拦截/修改输入
• PostToolUse：工具执行后——检查结果、记录日志
• Stop：Agent 准备结束时——判断任务是否真正完成
• SessionStart：会话启动时——加载项目上下文
• UserPromptSubmit：用户发送指令时——注入额外信息

有了这些钩子，你的 Claude Code 就从一个「听话的 AI」升级成「有判断力的助手」。

两种写法：Prompt Hook vs Command Hook

Prompt Hook（推荐）：扔给 LLM 判断，灵活、聪明，适合复杂逻辑：

{
  "type": "prompt",
  "prompt": "检查这个文件写入是否安全：$TOOL_INPUT",
  "timeout": 30
}

Command Hook：跑 bash 脚本，快速、确定，适合性能敏感的操作：

{
  "type": "command",
  "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
  "timeout": 60
}

两者可以混用，同一个事件可以同时触发多个 Hook，并行执行。

实战场景

场景 1：拦截危险写入

项目里有些目录（.env、node_modules）绝对不能乱动？

{
  "PreToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "prompt",
      "prompt": "检查文件路径是否安全，涉密目录直接 deny。"
    }]
  }]
}

场景 2：代码写完自动检查质量

每次 Edit 执行完，自动运行一个检查脚本，输出反馈给 Agent：

{
  "PostToolUse": [{
    "matcher": "Edit",
    "hooks": [{
      "type": "command",
      "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/lint-check.sh"
    }]
  }]
}

场景 3：任务结束前强制验证

Claude Code 每次想停下来的时候，都先过一遍完整性检查——有没有跑测试？构建能过吗？

{
  "Stop": [{
    "matcher": "*",
    "hooks": [{
      "type": "prompt",
      "prompt": "验证任务是否完成：测试通过了吗？构建成功了吗？"
    }]
  }]
}

怎么安装

Skill 页面有完整文件结构：SKILL.md + examples/ + scripts/ + references/。官方还给了 Validate Hook 脚本的 lint 工具，写完可以先自测再部署。

需要注意的是：Hook 配置只在会话启动时加载，改完要重新 exit 再进 Claude Code 才能生效。

整体来说，这个 Skill 把 Claude Code 插件开发里最难理解的部分——Hook 系统——讲透了。文档里有 8+ 常见模式、迁移指南、安全最佳实践，还配套了可运行的脚本。适合想深度定制 Claude Code 行为、或者做团队插件的开发者。

GitHub 链接附上，有兴趣的可以去读原始文档：

https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills/hook-development

GitHub: https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills/hook-development