功能对比
| Hook 事件 | 适合用途 | 风险提示 |
|---|---|---|
| PreToolUse | 在工具调用前阻止或提醒 | 策略要清楚，输出要可操作。 |
| PostToolUse | 在成功编辑后运行 lint、格式检查或记录 | 不要每次编辑都跑很慢的完整测试。 |
| PermissionRequest | 提醒开发者 Claude Code 需要处理 | 只放短通知命令。 |
| Stop | 回合结束时输出摘要或状态 | 不要意外修改文件。 |
| SessionStart / SessionEnd | 准备或清理会话级状态 | 脚本应可重复运行。 |
什么时候使用 Hooks
Hooks 适合重复验证、格式化检查、轻量通知、权限提醒、受保护文件防护栏或团队专属工作流策略。
安全模式
每个 hook 只做一件可观察的事。优先选择读取输入、输出清晰结果，并且开发者可以手动运行的命令。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|MultiEdit|Write",
"hooks": [
{ "type": "command", "command": "npm run lint", "timeout": 120 }
]
}
]
}
}Matcher 清单
好的 matcher 会让 hook 更可预测。Lint 检查匹配编辑类工具，密钥文件防护匹配读/搜索工具，权限提醒匹配 PermissionRequest，回合状态匹配 Stop。
- 先窄后宽，确认有价值再扩大范围。
- 记录命令期望的 stdin payload。
- 设置 timeout，避免 hook 无限卡住会话。
- 失败输出要告诉开发者下一步怎么做。
常见错误
隐藏副作用会降低 AI 工作流的可信度。
- 避免意外修改文件。
- 部署、网络写入和凭证轮换不要放进自动 hooks。
- 不要每次 tool call 都跑很长的完整测试。
- 在 CLAUDE.md 或 AGENTS.md 中记录 hook 行为。
常见问题
Hooks 能替代测试吗？
不能。Hooks 应该运行或辅助检查，而不是成为唯一验证层。
Hooks 可以是团队专属的吗？
可以，但要记录清楚，让每位开发者理解自动化行为。
CLAUDE.md 里应该写什么？
说明 hooks 何时运行、失败意味着什么、如何手动复现命令，以及谁负责 settings JSON。
在哪里生成 hook JSON？
需要起步 settings JSON 时使用 Claude Code Hooks 生成器，然后在团队共享前审查权限。