Claude Code 确定性工程社区实践三层护栏拆解说明本文整理自一篇社区实践分享来源为掘金社区文章证据类型为社区信号并非 Anthropic 官方文档解读。文中涉及的 Hook 退出码语义、Skill 触发方式、规则行数阈值等机制性描述均为该社区作者的个人实践经验官方文档待独立核验。读者在落地前应自行对照官方文档确认。把 Claude Code 当成更聪明的聊天框是不少生产事故的起点。该社区作者给出的判断很直接它不是问答系统而是概率性的执行系统——同一个需求每次产物都不一样。作者主张要做的事只有一件把概率压缩成确定性。作者自述用一年多时间走过一段弯路一开始以为瓶颈在模型不断换更强的模型该出的 bug 还是出后来注意力从「让模型更聪明」转到「让约束更硬」提升比换三次模型加起来都明显。这属于作者的个人经验判断不是可复现的基准结论。作者把护栏拆成三层。规则层CLAUDE.md、.claude/rules/、Skills、Commands强制力弱回答「它知不知道项目规矩」分工层SubAgent、工具白名单强制力中回答「有没有人出来唱反调」反馈层Hooks、MCP、Checkpoint、验收脚本强制力强回答「改好了三个字谁来验证」。一句话概括规则层管愿意怎么做分工层管被允许怎么做反馈层管做不到就走不掉。作者认为只有第三层是真正的强制力。一、三堵墙作者观察到的三类反复出现的问题上下文漂移规划与中途约定只存在于对话历史里历史被压缩后「刚才说好用 A 方案」就丢了它按重新推断的方案继续写而你毫无察觉。自我宽容同一个 Agent 先写代码再自己审查等于让考生给自己阅卷。口头验收「改好了」的命中率取决于它有多想收尾而不是代码的真实状态。作者认为共同点是缺的不是模型能力是工程约束。二、规则层把口头约定写成可判定文件作者主张 CLAUDE.md 不是备忘录而是编译期约束。每一条都必须可被判定——要么通过要么违反。判断标准只有一条能不能被 grep 出来、被脚本检查。不能就重写。作者批评大多数人的版本是「注意事项」下挂三条高质量、规范、最佳实践这类内容约束力接近于零因为模型无法判定自己是否违反了「高质量」。以 acme-api 这个示例为例作者给出的写法是运行时 Node.js 20 LTS TypeScript 5.x ESM禁止出现 require()包管理只用 pnpmnpm install / yarn add 一律视为错误src/routes/ 只放路由声明业务逻辑下沉到 src/services/错误码必须引用 ErrorCode 枚举新增 HTTP 端点必须挂 requireAuth()确需放开写 allowAnonymous。再列清楚不要做的事不改 src/legacy/**、不改测试断言去迁就实现、不做计划外重构。验收标准四条同时满足pnpm typecheck 通过、pnpm test 全绿、pnpm lint 无 error接口类改动必须用真实请求打过一次并贴出响应。作者的一个关键观察禁止条款的效果明显好过倡导条款——有没有挂 requireAuth()grep 一下就知道符不符合「高质量」谁也判不了。作者还提到一条经验阈值据其个人实践观察CLAUDE.md 超过两百行后每条规则被「注意到」的概率明显下降因此建议按领域拆到 .claude/rules/用 frontmatter 的 globs 限定生效范围。作者认为规则加载量会影响模型表现。需要强调两百行这个数字是作者的经验判断不是官方基准也不构成普适阈值。再往上是两个容易混淆的机制。按作者描述Skill.claude/skills/名称/SKILL.md自动触发管「做事的规矩」核心是 frontmatter 的 description写得含糊这个 Skill 就等于不存在作者的 api-guard 跑一张六项检查清单其中保留的「需你决策」一段是让 Skill 学会承认自己不知道否则它会用看似合理的猜测把业务语义堵上。Slash Command.claude/commands/xxx.md手动调用管「做事的顺序」最常用的 ship.md 是只读调研、出方案并停下等确认、实现、真实执行并贴结果的验证、自审。三、分工层让批判与创造不共享上下文作者认为规则是静态的代码质量问题却是动态的靠结构解决让 critic 和 author 不处于同一个上下文。按作者描述SubAgent 就是 .claude/agents/ 下的 Markdownfrontmatter 定义身份与能力边界子 Agent 在隔离上下文里运行这是整个设计的核心。作者建议三个角色够用。planner 用最强档模型tools 限 Read、Grep、Glob、WebSearch只给计划不给代码说不清的列成问题清单反问。coder 用中档模型tools 为 Read、Write、Edit、Bash、Grep、Glob只改计划内文件。reviewer 用小档且换模型系列只读tools 含受限 Bashpnpm test:*、pnpm typecheck、pnpm lint每条问题必须带文件加行号、0 到 100 置信度、具体后果置信度低于 70 一律不输出。作者列出三个容易被忽略的决策reviewer 必须只读能改代码的 reviewer 会自己动手从审查者退化成第二个 coderreviewer 用小模型反而更好同模型自我审查的最大问题是过度认同换个不同系列的小模型能打破这种共鸣还便宜置信度阈值比评分更重要让人放弃 AI 审查的不是漏报是误报淹没有效信息报 30 条、28 条是废话等于报 0 条。这些均为作者经验判断。作者把角色编成一条流程planner 拆解拿到待确认问题后转问人、不许替答交给 coder 实现调 reviewer 独立验证并让它真的跑命令高于 70 分的问题交回 coder 修复最多两轮。作者特别说明这种编排的可靠性来自 prompt 写得够硬不是引擎级保证。要更强的确定性作者主张得上 Hook。四、反馈层把「改好了」翻译成「跑过了」作者认为前面所有东西本质上都是提示模型可以在某次采样里忘了遵守只有 Hook 是确定会执行的——挂在工具调用事件上由运行时触发不由模型决定。作者用一句话概括rules 是「它应该这样做」hooks 是「它不得不这样做」。按作者描述最有用的事件是 Stop每当 Claude 想结束回合先跑你的脚本。作者称退出码 0 放行2 拦截并把 stderr 原样喂回给 Claude——这不是报错是把反馈传回去它读到后会接着干活。需要提醒退出码语义属于该社区作者的实践描述具体行为请以官方文档为准。作者给出的配置有四个要点git push 必须禁掉让 Agent 拥有推送权限是迟早出事的决定Bash(pnpm:) 这种白名单粒度比 Bash() 安全得多PostToolUse 防错误累积Stop 防提前收工个人偏好放 .claude/settings.local.json 并加进 .gitignore团队规则放 settings.json 提交 Git。permissions 里同时 deny 掉 rm 与 .env 读取。作者的 verify-app.mjs 分四步跑 typecheck、test、lint 收集失败用 git diff --name-only HEAD 取改动文件检查 src/routes/ 下有没有 requireAuth 或 allowAnonymous任一失败就写 stderr 并 process.exit(2)。作者强调三个 pnpm 命令不是重点最后那段项目专属检查才是——它把「新增端点必须挂鉴权」从软约定变成会拦截的硬约束。作者认为 MCP 解决另一半问题它能看到什么。作者常驻 context7 治过时的 API 写法、playwright 自己开浏览器验证、filesystem 看见项目全貌、数据库 MCP 查真实数据。作者提醒三个坑数据库一律只读账号给一个能 DROP TABLE 的连接串等同于把生产库 root 密码贴出来filesystem 路径必须绝对改完配置必须重启。五、实战给一个 Express 服务做鉴权收口作者举的例子起点很典型每个路由自己写 jwt 校验缺 header 返回 401jwt.verify 失败返回 403而另一个路由同样情况却返回 401参数校验写成 500退款逻辑没有任何幂等保护同样的逻辑在另外两个路由里是另外两个版本。按作者描述planner 会 grep 出全部 jwt.verify 调用点真正的价值是它会反问三个路由角色要求不同是否按角色收口能否一次性替换token 过期与非法是否返回同一个错误返回不同可能泄漏用户是否存在。作者强调这三个问题不回答它就不该动手。作者抽出 requireAuth 中间件时有四个刻意取舍中间件自己不写响应错误统一走 next(err)让「错误长什么样」只有一个地方定义且只对 status 大于等于 500 打 error 日志JWT_SECRET 缺失时启动即失败token 过期与非法返回同一错误职责单一只做认证。作者还要求覆盖失败路径不止 happy path无 Authorization 头返回 401scheme 写成 Basic 返回 401token 过期返回 401 且响应体结构与无 token 时完全一致这条防的不是 bug 是信息泄漏角色不足返回 403缺 amount 返回 400 而非 500相同幂等键重复提交两次 refundId 相同。验收别问「你确定没问题吗」作者建议直接下指令用 playwright 走一遍登录验证 401 时前端跳登录页而不是白屏把截图给我。最后把同一份 verify-app.mjs 放进 CI——作者指出本地 Hook 可以绕过CI 绕不过。复盘时作者承认边界退款要不要幂等、幂等键什么粒度、能否一次性切过去这三件业务语义的事它猜不中。作者总结流程能保证已知的正确被稳定执行不能保证未知的语义被正确猜中。结语作者认为这套东西真正改变的不是代码写得快不快而是你敢不敢把活交给它。裸用只能做随时能检查的小事配好三层之后你才敢让它做那种要跑二十分钟、而你能去接杯咖啡的任务。再次说明本文为社区实践手册整理非官方文档解读。文中所有机制细节、阈值与退出码语义均来自该社区作者经验落地前请以官方文档为准。