ClaudeCodeHooks配置指南，5个可直接复用的自动化规则
Claude Code 的 Hooks 功能允许开发者在关键操作节点自动执行校验或处理脚本，将重复性规范动作固化为流程。本文详解其配置位置、事件机制与5个实用模板，涵盖代码格式化、敏感文件保护、危险命...
在 AI 编程助手日益普及的当下，如何确保其行为符合工程规范成为关键问题。Claude Code 提供的 Hooks 机制，正是将人为叮嘱转化为自动化流程的核心工具——它不依赖模型记忆或用户提醒，而是在特定操作触发时自动执行预设指令，实现对代码修改、命令执行等关键环节的强制约束。
Hooks 的核心价值在于“机制兜底”。例如，开发者常需反复强调“改完代码要格式化”“别动 .env 文件”“删库前必须确认”，但这些口头要求极易被忽略。若将规则写入 CLAUDE.md，仅作为说明文档存在，AI 仍可能因上下文偏差而遗漏；而通过 Hooks，可在 Edit 或 Write 工具调用后自动运行格式化脚本，或在 Bash 执行前检查命令是否含 rm -rf 等高危操作，真正实现“规矩不靠自觉，靠机制兜底”。
配置 Hooks 并非写在项目说明文件中，而是独立存在于 settings.json 的 "hooks" 字段下。根据作用范围，有三类配置文件：
- 项目级：
.claude/settings.json，随 Git 提交，供团队共享统一规范； - 个人级：
~/.claude/settings.json，对所有本地项目生效，适合个性化习惯； - 本地级：
.claude/settings.local.json，不提交至版本控制，用于临时测试新规则。
配置结构为三层嵌套：事件名（如 PostToolUse）→ matcher（正则匹配工具名，如 Edit|Write）→ hooks 列表（含 type 与 command）。其中，事件决定“何时触发”，matcher 决定“对哪些工具生效”，command 指向实际执行的 Shell 命令。官方推荐将逻辑封装为 Python 脚本，避免 JSON 中复杂转义，也便于审查与调试。
- 退出码 0：放行，流程继续；
- 退出码 2：阻断操作，stderr 内容将返回给 Claude 作为拒绝理由；
- 其他非零值：视为非致命错误，流程继续但记录异常。
这一协议使 Hook 不仅能拦截风险，还能动态影响后续行为，形成闭环控制。
基于上述机制，以下5个配置模板可直接复用，适用于绝大多数开发场景：
① 代码修改后自动格式化
配置监听 PostToolUse 事件，匹配 Edit 与 Write 工具，调用 format_changed.py 脚本。该脚本读取变更文件路径，按后缀调用对应格式化工具（如 black 处理 .py，prettier 处理 .js/.ts），确保每次编辑后代码风格统一。此配置显著降低团队协作中的格式争议，尤其适用于多人并行开发项目。
② 禁止修改敏感文件（如 .env）
通过 PreToolUse 事件拦截 Edit 或 Write 操作，脚本检查 tool_input.file_path 是否匹配 .env$ 正则。若命中，立即返回退出码 2 并提示“禁止直接编辑环境变量文件，请使用 secrets manager”，从源头防止密钥泄露。
③ 危险命令拦截（rm / drop / truncate）
针对 Bash 工具，在 PreToolUse 阶段扫描 command 字段是否含 rm -rf、DROP TABLE、TRUNCATE 等关键词。一旦检测到，阻断执行并要求用户显式确认（如输入 /confirm-danger），避免误删生产数据。
④ 提交前自动类型检查（TypeScript/Python）
在 UserPromptSubmit 事件触发时运行类型检查脚本。例如，对 TypeScript 项目调用 tsc --noEmit，对 Python 项目运行 mypy。若检查失败，返回错误信息并阻止后续生成，将问题前置到编写阶段而非运行时。
⑤ 会话结束自动清理临时文件
利用 Stop 事件，在一轮对话结束时执行清理脚本，删除 .tmp、~ 等临时后缀文件，防止垃圾文件堆积影响项目整洁度。
实施任一配置仅需五步：创建 .claude/hooks/ 目录 → 存放脚本 → 将配置片段粘贴至对应 settings.json → 在 Claude Code 会话中输入 /hooks 加载配置 → 选择一个触发点测试效果。Windows 用户需注意，若脚本路径含空格，command 字段中路径应加双引号包裹。
值得注意的是，Hooks 与 CLAUDE.md 形成互补关系：前者是“门锁”，后者是“说明书”。CLAUDE.md 描述项目目标与约束，而 Hooks 将关键约束转化为不可绕过的执行规则。二者结合，才能构建既灵活又可靠的 AI 编程协作环境。
随着 AI 编程工具深入开发流程，自动化校验机制正从“可选项”变为“必选项”。Claude Code 的 Hooks 设计体现了工程化思维——不寄望于模型的完美记忆，而是通过标准化接口与明确协议，将人类经验沉淀为可持续执行的流程。对于追求稳定交付的团队而言，合理配置 Hooks 已成为提升 AI 辅助开发安全性的基础实践。
