最近好几个团队负责人跑来问我同一个问题个人 CLAUDE.md 确实好用可我们十个人共用一个仓库每个人的 CLAUDE.md 都不一样AI 到底该听谁的这个问题的答案就是这篇要聊的核心——共享团队 CLAUDE.md把它打造成统一的项目智能指南。要理解这件事的价值得先分清楚一个概念AI 编程助手在个人场景下是贴身助理服务的是你的个人习惯在团队场景里它必须升级成项目级向导服务的是一整套团队约定。前者可以很个性后者必须很克制。这篇我会把我们团队过去三个月沉淀下来的做法完整展开包括内容清单、文件拆分、审查流程、冲突仲裁规则适合正在用 Claude Code 这类 AI 编程工具、并且已经过了一个人闷头写阶段的团队直接参考。先说结论团队 CLAUDE.md 最值钱的不是让 AI 变得更聪明而是让所有人都按同一套上下文说话。这个文件不是写给 AI 看的教条是写给人看、再让 AI 执行的团队契约。1. 为什么团队级 CLAUDE.md 不能靠复制粘贴1.1 个人偏好会以代码污染的方式扩散我见过最典型的翻车现场团队里一位前端同事个人 CLAUDE.md 里写了一条代码风格优先使用可选链不要写 判断。他个人用这套写得很爽后来团队项目引入 CLAUDE.md有人觉得这条规则不错原封不动粘进了项目级文件。结果是什么AI 面对沉淀了三年的老代码库大面积把原有判断条件改写成可选链表达式。那次 PR 的 diff 上千行代码审查基本没法做最后只能让 Git 回滚。问题不在可选链好不好而在于个人偏好被当成团队规则后AI 会拿着它去动它本不该动的东西。个人 CLAUDE.md 的主语是我团队 CLAUDE.md 的主语必须是我们。团队文件里每一条规则都要问一句这条规则是为了让团队产出稳定还是为了让某个人写得顺手只服务个人的留在本地文件里别进公共仓库。1.2 信息被改坏的两条典型路径路径一模糊指令。比如代码要优雅命名要简洁。这类形容词在 CLAUDE.md 里危害极大AI 会把你随口写的简洁理解成把所有变量名都改短。我见过一次实际事故有人在文件里写保持命名简洁AI 把 userName 改成了 user把 isUserLoggedIn 改成了 logged整个代码库的命名风格被彻底搅乱。路径二把个人好恶包装成团队规范。我不喜欢 try/catch 吞异常这种话个人文件里写没问题一旦进了团队文件AI 在处理新增代码时就不再写异常处理线上日志开始出现大量裸奔错误。它不是不写 try/catch而是干脆不处理错误因为它的理解是这个团队不允许 try/catch。还有一条更隐蔽的路径信息优先级混乱。仓库根目录一份 CLAUDE.md子模块一份个人本地一份AI 按什么顺序读取团队没约定时全局规则和局部例外会混在一起AI 在不同模块里做出矛盾决策。我们最终的约定是本地文件 子目录文件 根目录文件本地文件只放个人工作流偏好且不提交 Git子目录文件只放模块专属规则根目录文件只放全仓库通用的硬性约定这个顺序必须在团队里明示并写进文档本身。1.3 团队文档的天职是固定事实团队级 CLAUDE.md 的工作重点是固定三类事实统一术语、锁定命令、固化架构边界。它不该承担展示个人品味的功能。你可能会觉得这是废话但真去翻团队仓库就会发现大量 CLAUDE.md 里塞满了个人风格偏好、临时解决方案、甚至还有吐槽注释。这些东西对 AI 来说都是指令它分不清哪些是认真的、哪些是随手写的。所以我们的第一个落地动作就是存量清理把现有文件里所有我觉得我习惯尽量最好这类词全部摘出来逐一判断去留。留下来的必须改写成无主语的事实陈述删掉的单独放进个人 local 文件。这一步做完AI 的行为稳定性立竿见影。2. 一份合格的团队 CLAUDE.md 该装什么2.1 六层内容模型与可直接抄的模板经过几个项目的迭代我把团队 CLAUDE.md 固定成了六层结构每一层解决一类问题。直接上一份我们的模板骨架# 项目身份 一句话说清楚项目是做什么的、给谁用、部署在什么环境。 示例该项目是面向中小商户的库存管理后端服务端渲染 Web 应用生产环境部署在 AWS ECS。 # 技术栈与命令 后端Python 3.11 FastAPI PostgreSQL 15 前端React 18 TypeScript 5 Vite 运行单测pytest tests/ -x 启动本地服务uvicorn app.main:app --reload # 架构约束 - app/ 下按业务模块分包禁止在 controllers 里直接写 SQL - services 层负责事务边界外部依赖统一封装在 gateways 目录 - 新增外部调用必须先经接口评审禁止绕过 gateways 直达 HTTP 客户端 # 领域术语表 - SKU库存最小单位一个商品可有多个 SKU - 渠道仓逻辑仓不对应物理库房只做库存归集 - 调拨单仓库间转移库存的业务单据状态机见 docs/transfer.md # 工作流约定 - PR 必须附带运行通过的测试命令输出 - 提交信息前缀feat / fix / refactor / docs / chore - 数据库迁移脚本只允许追加不允许修改历史迁移文件 # 禁忌清单 - 禁止在非 gateways 目录直接使用 httpx 请求外部服务原因是外部接口变更需统一收敛。 - 禁止修改 db/migrations 目录下已发布的历史脚本原因是生产环境校验和依赖历史链条。 - 禁止使用 SELECT * 查询生产库原因是显式字段保证索引命中与网络包可控。这六层顺序是经过考虑的先让 AI 知道这个项目是什么再告诉它用什么工具、跑什么命令然后才是代码该怎么组织最后是绝对不能做什么。前两层建立坐标系后四层划定行为边界。AI 读文件时是顺序解析的前面信息越准确后面的约束被执行得越好。2.2 信息压强精确到命令而不是形容词我反复强调一个词信息压强。同样一条规则两种写法效果完全不同。低信息压强的写法是注意性能问题避免 N1 查询。AI 知道 N1 不好但它不知道这个项目的具体边界在哪里于是它会自行判断有时候过度优化有时候又漏掉明显问题。高信息压强的写法是列表接口禁止在循环内访问数据库必须通过查询一次性载入关联数据复杂聚合查询优先使用 JOIN避免内存分组。这种写法把触发条件、推荐方案、禁止行为都钉死了AI 的输出行为高度可预期。写 CLAUDE.md 的时候你可以拿一句话自测如果这句话换成两个人当面沟通对方还需要追问两个以上问题才能执行那它就是信息压强不够。原则就一条多用可验证的命令和路径少用形容词和副词。2.3 千万别把所有内容塞进一个文件团队 CLAUDE.md 最常见的失败形态就是一个根目录文件写到五六百行包含从项目简介到按钮颜色的所有内容。AI 的上下文窗口虽然越来越宽但指令太长会导致两个问题一是关键规则被稀释AI 抓不住优先级二是文档维护成本飙升每次更新都像在改一本长篇小说。我们当前的文件拆分方案是这样根目录 CLAUDE.md全局纲领只放全仓库通用规则控制在 150 到 300 行。子目录 CLAUDE.md模块专属比如 modules/auth/CLAUDE.md 只放权限模块的约定一个模块 30 到 60 行。CLAUDE.local.md个人本地文件不提交 Git用来覆盖个人偏好比如提示词风格、常用命令别名。判断规则该进哪个文件我们有一条朴素标准这条规则是否适用于仓库所有模块适用进根目录只对某个模块有意义进子目录只对某个人有影响进 local 文件。一旦根目录文件超过 300 行我的第一反应不是删而是检查哪些规则其实只属于某个子模块。2.4 每条规则背后必须写明 Why这是我认为团队 CLAUDE.md 最重要的一个细节规则必须带头 Why。比如禁止修改 db/migrations 目录下的历史脚本如果只写到这AI 会遵守但新人看到会一脸疑惑这规则凭什么存在更重要的是当团队争议产生时没有 Why 的规则会被轻易推翻。带 Why 的写法是这样的禁止修改 db/migrations 目录下的历史脚本——迁移脚本以追加方式变更历史版本已发布到生产环境修改文件会导致环境间校验和不一致。AI 在遇到特殊情况时能判断边界人在争论时也有据可依。我们在模板里增加了 owner 标注比如Owner: alice。这个标注既给 AI 一个求助方向也给团队一个问责对象规则出了问题先找 owner而不是开一场无休止的讨论会。3. 从一人改到多人改git 流程、审查与冲突仲裁3.1 把 CLAUDE.md 当成代码来审查团队落地 CLAUDE.md 后第一个逃不掉的问题就是谁来改、怎么改、怎么审我的回答是把它当成代码走完整的合入流程。有人会问一份文档而已需要这么隆重吗需要因为 CLAUDE.md 的每一次修改都会改变 AI 在仓库里的全部行为比改一行代码的影响面大得多。我们内部执行的是 PR 审查制审查清单是这几条diff 里是否混入了个人偏好句式比如我个人认为。是否出现应该尽量追求这类模糊副词出现即打回重写。规则里的命令、路径是否还有效命令失效比规则删除更危险。被删除的规则是否有替代写法还是纯粹消失。每条新增规则是否附带 Why 和 Owner缺一不可。审查 CLAUDE.md 的 diff和审查代码有个本质区别代码 diff 关心的是逻辑有没有问题文档 diff 要先问这条规则会不会让 AI 改变它本不该碰的东西。审查时我会重点看规则的作用域一条规则如果影响面超过 80% 的代码库就必须经过架构评审而不是某个人顺手就能合入。3.2 冲突仲裁规则争论的终结机制团队一大规则争论是必然的。最典型的就是接口返回一律用 DTO和小服务直接返回 dict之争。我见过有团队在群里吵了两个小时最后不了了之CLAUDE.md 里两条规则同时并存AI 每次都在做掷骰子式决策。我们现在的仲裁机制分四步第一步规则顶部必须有 owner 标注争议时先由 owner 给初判。 第二步修改必须走 PRPR 描述里说明旧规则在哪些场景失效新规则覆盖哪些场景。 第三步争议解决不了记录成 issue放在每周的技术例会上复议不在即时通讯里拉扯。 第四步必要时让 AI 基于两份候选规则各生成一段示例代码团队对比实际效果再做决定。这个机制真正解决的核心问题是把争论变成决策。CLAUDE.md 不是投票箱它是决策记录。哪怕某条规则不够完美只要它是明确的、有 owner 的、有理由的AI 的行为就是稳定的最怕的不是规则不好而是没有规则。3.3 更新节奏别让文档变成每日变更有一个隐藏的坑必须提醒CLAUDE.md 不是越新越好它需要稳定。我们团队早期踩过坑有人觉得某个说法不顺眼当天就改了结果 AI 的行为跟着频繁摇摆同一个模块这周一个风格下周一个风格。后来我们定了更新节奏新项目启动时统一建一次团队 CLAUDE.md。架构决策定案后补充对应规则其他时间不主动修改。每次变更走 PR合并后由 owner 在周会上同步变更摘要。每两周代码走查时留十五分钟专门看 CLAUDE.md 的 diff而不是谁想改就改。这套节奏执行下来AI 输出的稳定性明显提升。文档慢半拍没关系AI 编程本来就不是追求极致实时而是追求可预期。让 AI 基于一个稳定的团队上下文工作比让它每次都用到最新规则重要得多。4. 让 CLAUDE.md 从写到用的配套动作4.1 新人上车CLAUDE.md 是最好的入职材料团队 CLAUDE.md 写完之后最直接的受益者其实是新人。以前带新人要讲一遍架构、过一遍命令、强调几个禁忌至少花掉一下午现在我把 CLAUDE.md 丢给他半小时看完再按里面的命令跑一遍本地服务基本就能上手干活了。我建议新人的 onboarding 就这么走第一件事读根目录 CLAUDE.md不要求记住但要知道规则在哪。第二件事跑一遍文档里的最小验证命令跑不通就是文档失效当场提 PR 修。第三件事给 AI 布置一个真实小任务比如按照架构约束新增一个 health 接口然后对照 CLAUDE.md 检查 AI 的输出是否符合约定。这个过程不只是教新人更是检验 CLAUDE.md 的成色。新人提的第一个 PR 往往就是修文档这太正常了因为他会用一种没有任何先入为主的视角去审视规则最容易发现过时命令和歧义表述。我们团队的经验是每来一个新人CLAUDE.md 的质量就上一个台阶。4.2 用 CI 和代码审查给文档担保只写文档、不给 AI 配执行反馈机制文档很快就会变成僵尸指南。AI 编程和传统开发的本质区别在于AI 不会自己意识到违反了规则它需要外部信号。我们的做法是三层担保第一层CLAUDE.md 本身写清楚规则让 AI 在生成代码时就有正确倾向。 第二层CI 里跑 lint、类型检查、单测把不合规的行为挡在合并之前。 第三层PR 审查时要求 AI 生成的改动附带我遵循了 CLAUDE.md 第几条的证据。比如你改了 gateways 目录PR 描述里就写新增外部接口统一收敛在 gateways/third-party 下。很多团队只做了第一层就觉得 AI 编程落地了后来发现 AI 偶尔还是会乱来就怪工具不行。其实问题出在缺少第二层和第三层的反馈闭环。AI 编程不能只靠告诉它必须配合挡住它和审查它。这里分享一个我们亲测有效的技巧挑几条最贵的规则比如禁止修改历史迁移脚本直接在 CI 里加一个脚本守卫检查 diff 是否触碰了受保护路径碰了就自动打回。CLAUDE.md 写得再清楚也不如一个自动化的硬性检查来得可靠。把最不能违反的规则变成代码级别的护栏是团队 AI 编程落地的基本功。4.3 谁说 CLAUDE.md 只有工程师才能用最后想破个圈。一说到 CLAUDE.md很多人默认它只是给开发团队用的。但我们尝试下来测试、产品、运维同样能从这个文件里受益。举例来说QA 团队把测试环境的数据准备命令和账号约定写进 CLAUDE.mdAI 在生成测试用例时就会自动使用正确的环境不再出现测试代码往生产链接上打的问题产品团队把用户术语表放进去AI 在生成功能说明时用词和产品口径一致省掉了大量来回修改。团队 CLAUDE.md 的真正定位是整个项目所有角色的共享上下文不是工程师的自留地。我还见过一个有意思的用法运维把发布窗口和回滚步骤写进去AI 在协助排查线上问题时提交的变更提案会自动规避发布窗口期这对稳定性保障很有价值。所以你在设计团队 CLAUDE.md 的内容清单时别只邀请后端同学参与把测试、产品、运维都拉进来问他们一句你希望 AI 帮你记住什么收集上来的答案往往是工程师完全想不到的维度。回到开头那个问题AI 到底该听谁的答案已经清晰了——听团队约定好的那套上下文通过共享 CLAUDE.md 固化下来再配合审查流程和自动护栏保证执行。我个人的体会是团队 AI 编程的落地难点从来不在工具而在组织习惯。CLAUDE.md 写不好AI 就是一把没有准星的枪写好了它就是团队记忆的外置硬盘。我们团队现在最受益的瞬间不是哪个工程师写出了多惊艳的代码而是新人在入职第一天就能和 AI 一起输出符合团队规范的改动——这件事在共享 CLAUDE.md 之前至少得等上两个星期。如果你也在团队里推进 AI 编程我强烈建议别急着堆功能先把这份项目智能指南的骨架搭起来。少写规则多写事实和原因让每个人都知道规则归谁管让最贵的规则有自动护栏。做到这三条团队 CLAUDE.md 才不会沦为摆设而是真正成为所有人和 AI 协作时那一份共同的地图。