用项目规则与钩子约束 Claude Code
文章区分 CLAUDE.md 的上下文指导作用与 Hooks 的脚本执行约束,建议精简规则、解释原因,并拆分详细说明。实践覆盖危险命令拦截、敏感文件保护、自动格式化及团队经验沉淀。
AI 深度解读
Claude Code 写出的代码能运行,却未必适合你的项目:状态库选错了,依赖装错了目录,提交前也没跑验证。作者给出的办法是把约束分成两层:用 CLAUDE.md 交代项目习惯,用 Hooks 执行必须落实的检查。
这套思路值得借鉴,但「写进规则就不会再犯」「装上脚本就能保护秘密」都需要打个问号。读懂两者各自能管什么,比收集一份超长模板更有用。
CLAUDE.md 应该教 AI 怎么做取舍
作者把 CLAUDE.md 比作新成员的入职手册。README.md 通常解释项目做什么,它则告诉 Claude Code 怎样进入项目:从哪里启动、如何测试、哪些技术选择已经确定。
例如,项目已经使用 Zustand,Claude 却另起一套 Redux,功能可能正常,维护成本却留给了团队。缺少项目上下文时,模型只能按自己的默认方案补空白。
所以,规则不能只有「使用 Zustand」,还应该解释状态怎样分工。原文这段示例解决的就是选型边界:
Use Zustand for state management; we want to keep global
state minimal. For cases that don't require complex business
logic and only carry UI state, prefer React Context. Our goal
is to prevent unnecessary re-renders and keep state as close
to the relevant component as possible.
要看的是第二行开始的条件:简单 UI 状态可以交给 React Context,不必全部塞进全局状态。作者希望模型理解工程目的,遇到灰色地带时也能作出贴近项目的选择。不过,这段话表达的是设计目标,不能据此断言 Context 一定能减少重渲染。
操作规则也要具体。原文要求 monorepo 添加依赖前检查 @repo/shared,使用 --filter,例如 pnpm add lodash --filter web,并禁止把业务依赖随手加到根目录。验证流程则包含启动应用、用 Playwright MCP 检查关键 UI 路径,再进入提交阶段。
好规则应当消除项目里的真实歧义。
文件越短越好,还是信息越准越好?
作者建议从 /init 生成草稿开始,再删除无用内容。按文中描述,该命令会分析目录、构建系统、测试框架和代码模式。作者还介绍了用 Enter 确认写入,以及通过 Shift+Tab 切换 Auto-Accept、Plan 模式的交互;原文没有注明适用的 Claude Code 版本,具体行为不能当作跨版本保证。
篇幅方面,作者引用 Boris Cherny 团队的做法:约 2,500 tokens、约 100 行。这个数字适合作为精简参照,不是精确上限。文件每次进入上下文都会占空间,规则堆得太多,重要约束也可能被淹没。
文中给出了几种拆分方式:
~/.claude/CLAUDE.md保存跨项目个人偏好,./CLAUDE.md保存团队共享规则。./CLAUDE.local.md保存项目内的个人笔记,按文中建议加入.gitignore。./frontend/CLAUDE.md保存子目录规则,让前后端分别维护自己的约定。- 低频流程放进
.claude/skills/<name>/SKILL.md,需要时再调用。
@ 引用需要单独辨析。原文既说被引用文件会自动进入每次请求,又说拆文件后 Claude 只在需要时读取,前后并不一致。因此,把内容移到 @docs/git-rules.md、@package.json 或 @prisma/schema.prisma,能改善组织结构,却不能直接认定节省了 token。按需调用的 Skills,是作者另外提出的方案。
作者还介绍了会话中的 @auth 文件引用,以及以 # 开头快速保存记忆,例如 #Always use bun in this project, not npm,并区分项目记忆与 ~/.claude/CLAUDE.md。这些同样没有版本说明。
更有价值的是维护机制:同一种错误纠正两次,就补进规则;把 CLAUDE.md 提交到 Git,让评审经验成为团队共享知识。原文称 Boris 团队通过 @.claude 从 PR 评审积累经验,但没有交代完整自动化配置,不能理解为加一个标记就能直接复现。
Hooks 能强制执行,但强制到哪里取决于脚本
CLAUDE.md 是建议性上下文。即使写了 IMPORTANT:、YOU MUST,也没有变成执行层面的禁止条件。
Hooks 则在事件触发时运行脚本。PreToolUse 在工具调用前检查,适合拦截操作;PostToolUse 在调用后处理,适合格式化或其他收尾动作。
自然语言负责解释意图,脚本负责检查可判定的条件。
作者给出的安装方式,是把 karanb192/claude-code-hooks 仓库放进 ~/.claude/hooks,脚本依赖 Node.js,再配置 ~/.claude/settings.json。下面这段原样配置展示了检查怎样绑定到工具:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{
"type": "command",
"command":
"node ~/.claude/hooks/block-dangerous-commands.js"
}]
},
{
"matcher": "Read|Edit|Write|Bash",
"hooks": [{
"type": "command",
"command":
"node ~/.claude/hooks/protect-secrets.js"
}]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{
"type": "command",
"command":
"node ~/.claude/hooks/auto-stage.js"
}]
}
]
}
}
要看清 matcher:危险命令检查匹配 Bash,秘密保护匹配 Read|Edit|Write|Bash,修改后的处理只匹配 Edit|Write。是否覆盖其他访问路径,原文没有证明。
第三个脚本也容易看错。auto-stage.js 做的是 git add <file>,并不是自动格式化。文章开头提到的「每次编辑自动格式化」,没有在这份配置中实现。

文中称 Claude Code 支持 18+ 种事件,包括 Notification、Stop、SubagentStop、SessionStart、SessionEnd,并给出默认 10 分钟超时、超时后跳过继续的描述。这些信息没有版本标注;尤其按照作者自己描述的超时行为,也不能把 Hooks 理解成永远无法越过的安全边界。
我的判断
作者最有价值的判断,是把项目约定与执行检查分开。架构偏好、状态归属、目录职责,适合写进 CLAUDE.md;格式检查、类型检查、明确禁止的文件操作,更适合交给程序判断。
但文章没有给出规则遵守率、token 消耗或事故减少的对照数据。「约 2,500 tokens」「纠错后不再重犯」属于经验和目标,不能作为效果承诺。作者列出的 .env 读取、危险命令拦截,也主要是预期结果,没有展示完整测试记录。
三份技术栈模板同样应当按项目裁剪:Next.js 15、React 19、Angular 19 是模板版本,type > interface、禁止 any、要求 Facade 都是团队偏好,不是通用最佳答案。MERN 模板禁止硬编码 MONGODB_URI、JWT_SECRET 有明确目的;但另一处把所有 API URL 都归入安全问题,就混淆了配置管理与秘密保护。
Hooks 可以补充工程流程,不能替代已有 CI、权限控制和代码评审。自动暂存尤其需要取舍:它省去一次操作,却也让「修改完成」提前变成「进入暂存区」。提供的原文最后停在 check-patterns.js 的读取代码开头,没有完整实现,因此不能据此判断它如何可靠拦截 console.log。
能拿来做什么
- 给现有前端仓库运行
/init后,优先留下启动命令、验证命令、状态分工和依赖安装位置,再补上团队反复纠正过的具体错误。 - 为 monorepo 明确 workspace 边界,把
pnpm add lodash --filter web这类可直接执行的示例写进规则,并解释为什么依赖不能随意放进根目录。 - 把
turbo lint && turbo build --filter=[APP_NAME]或项目实际采用的验证流程接入自动检查。先确认失败怎样反馈,再考虑加入格式化、自动暂存等动作。 - 用虚构秘密的临时
.env验证读取拦截,检查脚本路径与匹配范围。危险命令规则应通过检查脚本输入验证,不要为了测试保护是否生效而实际执行破坏性命令。