让编码智能体遵守团队规范的关键

AI 编程助手刚接入时很惊艳，用上几周，代码审查却开始反复纠正同一批问题：日志库选错、接口目录不对、绕过内部服务。原文把原因指向一个容易被忽略的地方：团队约定没有进入助手能读取的上下文，它只能沿用公共代码里的常见做法。

作者提出五个修补办法，从编写仓库规则到自动检查，再到用审查反馈更新规则。对程序员最有用的启发是：别把每次纠正都留在聊天里，要让它成为下一次任务也能用到的项目知识。

为什么代码能跑，却总不符合团队习惯

模型从大量公共代码中学到了默认选择，例如 Python 项目怎么命名、React 组件怎么组织、HTTP 请求通常用什么库。但团队约定经常来自主动偏离默认的决定：日志必须接入内部封装，支付必须经过账务服务，某个业务对象只能使用统一名称。

这些决定可能藏在两年前的 review 评论、少有人打开的 wiki，或者某位工程师的记忆里。助手启动任务时，能依赖的是它读取的文件和加载的指令。约定没有进入其中，就很难指望它稳定遵守。

代码库里存在某种写法，不等于助手知道那是必须遵守的规则。

原文将问题归因于约定的存放位置，而非模型故障。这个解释有道理，但不能推到另一个极端：即使规则已经写清，助手是否读到、是否理解、执行时是否遗漏，仍然需要检查。

规则要短，还要给出可以照着做的样板

作者把最高优先级给了 CLAUDE.md。按原文描述，Claude Code 会在每次会话开始时加载仓库中的这个文件，因此团队可以把共同约定放在这里。

下面这段规则把工具选择、目录结构和操作边界变成了明确指令：

## Rules
- Log with `lib/log`. Never use `console.log` or the standard logging module.
- New endpoints copy the structure of `api/orders/`.
- Never call the payments API directly. Go through `services/billing`.
- Schema changes: write the migration and open a PR. Never apply it.

要留意最后一行：它区分了「编写迁移并开 PR」和「执行迁移」，约束的不只是代码风格，还有助手可以做到哪一步。

作者的第二个建议是给样板。与其长篇解释接口分层，不如直接指向 api/orders/。经常新增的接口、组件、后台任务，各挑一个参考实现，再把路径写进规则。助手便有了具体的模仿对象。某个目录有独立约定时，可以在该目录放置 CLAUDE.md，让根文件保持简短。

第三个建议是明确排除常见替代项。原文举了三组例子：用 httpx，不用 requests；日期存 UTC，不存本地时间；领域对象叫 Customer，不用 Client 或 AccountHolder。

最后一组尤其贴近日常开发。同一个业务概念被起出三个名字，局部看都讲得通，跨模块阅读却会增加理解成本。规则文件也可以承担小型术语表的作用。

能自动检查的约定，别只靠助手记住

前面三招都在改善输入，第四招开始约束输出：linter、formatter、类型检查器或架构测试能发现的问题，就交给这些工具。

作者还提到，Claude Code 支持通过项目的 .claude/settings.json 配置 hooks，在编辑文件后自动运行命令，例如 formatter 或 linter。原文没有提供具体配置，不能据此直接复制落地；可以确定的是作者的思路：把检查前移，让问题尽量在提交审查之前暴露。

第五招则是一条维护习惯：同样的问题纠正两次，就检查规则里是否少了一行。修代码时，在同一个 PR 中补充 CLAUDE.md，并像审查代码一样审查规则变更。

作者描述，持续几周后，审查评论会从「日志库用错了」转向「这个行为是否正确」，规则文件也会成为新同事和助手共同使用的团队说明书。不过，文章没有给出评论数量、团队规模或前后对照数据，这属于经验性判断。

文末还介绍了他们开发的 AI Workspace Builder：上传已有文档，使用自己的 Anthropic API key，在 15 到 30 秒内生成 CLAUDE.md、各角色的 profile 和安装脚本，并提供一个无需银行卡的免费试用 workspace。这是产品介绍，原文没有展示生成结果的质量评估。

我的判断

我赞成把约定从聊天记录迁入仓库，尤其赞成「明确样板」和「机械检查」的组合。前者帮助助手理解团队选择，后者给可验证的要求提供稳定反馈，比每次在提示词里重述更容易共同维护。

但「模型复制样板比遵循描述可靠」没有对照数据，不能当成普遍结论。参考实现也未必始终正确：旧接口可能保留历史兼容逻辑，组件可能包含特例。指定样板时，最好说明哪些结构值得复用，避免把偶然写法升级为团队标准。

「纠正两次就是缺规则」同样适合作为排查起点，而非定论。规则可能已经存在，只是作用范围不对、表述冲突，或者助手没有遵守。继续添加重复条目，未必能解决问题。

规则文件适合承载选择和边界，自动检查适合验证能明确判定的要求。

两者互补。把长篇工程手册全部塞进 CLAUDE.md，或者只配置 formatter，都覆盖不了完整需求。

能拿来做什么

• 从本周最常重复的三条审查意见开始，把它们改成简短指令写进助手会读取的规则文件，并补上明确禁止的替代写法。
• 为常写的前端组件、Node 接口或后台任务各选一个参考实现，注明路径和需要遵循的部分，后续修改样板时一起检查规则是否仍然适用。
• 把可验证的约定放进现有检查流程；使用 Claude Code 的团队可以进一步评估编辑后运行 hooks，让反馈更早出现。
• 在修复重复问题的同一个 PR 中更新规则，同时检查原有条目是否冲突。先维护好少量真实有效的约定，再考虑从工程手册批量生成。