一、为什么需要选择
一个 PreToolUse 安全检查 Hook 放在 .claude/settings.json(项目级)里,团队成员 clone 后自动生效。但某天你发现所有个人项目也需要这个检查——逐项目复制配置不现实,改放 ~/.claude/settings.json(用户级)才能跨项目生效。
反过来,调试用的日志 Hook 放在用户级,每个项目的 /hooks 菜单里都会出现它——同事看到你的项目配置里没有这个 Hook,却在执行中看到它在跑,排查时找不到来源。
配置放错层级的后果:
- 共享范围不匹配 — 团队规范放在本地级(
.claude/settings.local.json),新成员 clone 后看不到 - 作用域溢出 — 项目专属的格式化 Hook 放在用户级,在不使用该格式化工具的项目中报错
- 来源不透明 — 多个层级配了同事件的 Hook,排查时不知道哪个层级在生效
Hook 配置有 6 个位置,分属 4 个层级。选对位置是分层策略的前提。
二、限制与红线
叠加合并,不是覆盖
所有层级中匹配的 Hook 同时执行。用户级配了一个 PreToolUse 安全检查,项目级配了一个 PreToolUse 格式检查——两个都会跑,不存在"项目级覆盖用户级"。
这条规则适用于所有 array 类型的 settings 字段,不仅是 hooks。claudeMdExcludes 数组同样是叠加合并——所有层级的排除模式取并集。