多人协作的CLAUDE.md治理：共享与个人怎么分、改动要不要走PR、规则冲突听谁的

摘要：一个人用CLAUDE.md怎么写都行，一旦变成五六个人共用，问题立刻冒头：有人把自己的本地路径塞进共享文件，有人在根目录偷偷加规则没人知道，两条规则互相打架AI随机挑一条执行。CLAUDE.md到了团队场景，本质是一份要进版本控制、要走评审、要分清谁负责的工程配置。这篇文章把团队治理拆成六件事——共享与个人怎么分、本地文件怎么隔离、改动要不要走PR、规则冲突听谁的、monorepo各团队怎么互不干扰、组织红线怎么硬性强制，给出每一条的官方机制和落地做法。

保哥去年接过一个跨境独立站团队的咨询，他们五个开发加两个外包，刚把Claude Code铺开三个月，CLAUDE.md就乱成了一锅粥。根目录那份文件里，有人写着指向自己Mac上某个绝对路径的测试数据位置，换台机器就报错；有人为了图方便把“跳过所有测试直接提交”塞了进去，结果全队的AI都学会了不跑测试；最离谱的是同一份文件里，第40行说“状态管理用Redux”，第180行又说“一律用Zustand”——这是两个人先后加的，谁都没删对方那条。

为什么单人没事、一到团队就翻车？因为单人场景下，CLAUDE.md的作者、使用者、维护者是同一个人，所有上下文都在你脑子里，写得再随意你自己也清楚每条规则的来龙去脉。团队一上来，这三个角色就分裂了：写规则的人、被规则影响的人、该删规则的人不再是同一拨，每条规则背后的“为什么”散落在不同人的记忆里，甚至随着人员流动彻底丢失。于是文件只增不减、个人偏好混入公约、矛盾规则共存——这些都不是谁粗心，而是缺乏治理机制的必然结果。

这些问题没有一个是CLAUDE.md语法层面的错误，全是治理层面的失控。单人使用时CLAUDE.md是你的私人备忘录，团队使用时它是一份共享的工程契约——契约就得有归属、有评审、有冲突解决机制。这篇专讲多人协作下怎么把它管好，和此前那篇CLAUDE.md极简写法互补：那篇管“一个人怎么写得精简”，这篇管“一群人怎么写得不打架”。

哪些规则该共享，哪些只属于你自己？

团队治理的第一刀，是把“所有人都该遵守的”和“只是你个人习惯的”切开。Claude Code的四级作用域天然就是为这件事设计的，关键是别放错层。

那个团队的第一个错，就是把本地级的内容写进了项目级。指向个人机器的测试数据路径，本质是“只属于你自己、当前项目”的东西，它该进CLAUDE.local.md，绝不该进随源码同步给所有人的./CLAUDE.md。判断标准很简单：问一句“这条规则换个人、换台机器还成立吗？”成立就放项目级共享，不成立就放本地级或用户级。

举个具体的例子感受一下分层。同样是关于测试的规则，可能要分到三个不同的层：“提交前必须跑通单元测试”是全队铁律，放项目级；“我习惯把测试数据放在本机的/tmp/testdata目录”是你这台机器的事，放本地级；“我个人写测试偏好用表驱动的写法”是你跨所有项目的习惯，放用户级。三条都跟测试有关，但归属截然不同。混在一起写进共享文件，结果就是别人的AI被你的/tmp/testdata路径搞懵、被你的个人测试风格带跑偏。分层不是洁癖，是让每个人只承受该承受的那部分规则。

还要记住一个机制前提：这四级不是互相覆盖，而是按官方内存机制文档所述全部拼接进上下文，从组织级到本地级依次叠加。这意味着团队共享的项目级规则，永远会和每个人的用户级、本地级规则共存，所以共享文件里只该放真正的团队公约，把个人色彩的东西留给个人作用域，叠加起来才不会互相打架。四级作用域各自的完整规则，CLAUDE.md记忆术那篇拆得很细，这里只谈团队视角下怎么分。

CLAUDE.local.md怎么用才不会污染团队？

CLAUDE.local.md是团队协作里最该用好、却最常被忽略的一个文件。它的定位很清楚：放在项目根目录，加载方式和CLAUDE.md完全一样，但它是你个人的、不该进版本控制的那部分。

用好它只需记住三步。第一，创建后立刻把它加进.gitignore——这是底线，漏了它就会被提交，你的本地路径、个人偏好就污染了整个团队。如果你用/init并选了个人配置那个选项，它会自动帮你把这件事做掉。第二，只往里放真正私有的东西：你本地起的测试服务地址、你偏好的调试数据、你个人这个阶段在调的某块实验代码。第三，别拿它当“逃避评审的后门”——把团队该知道的规则偷偷写进本地文件，等于绕过了协作，迟早出问题。

这里有个容易踩的坑值得专门提：如果你同时在同一个仓库的多个git工作树（worktree）里干活，被.gitignore忽略的CLAUDE.local.md只存在于你创建它的那一个工作树里，别的工作树根本看不到。想让个人偏好跨工作树通用，正确做法不是到处复制，而是把它放进你的主目录，再用@import引用：

# 个人偏好
- @~/.claude/my-project-notes.md

这样无论在哪个工作树打开项目，都能加载到同一份个人笔记，又不会把它提交进仓库。多工作树并行开发的团队，这一招能省掉不少“为什么我这边AI行为不一样”的扯皮。

还有个团队层面的常见困惑：既然有了本地文件，是不是每个人都该各写一份藏着不给别人看？恰恰相反。本地文件是用来装“纯私有、给别人没意义”的东西的，不是用来藏“怕被评审的规则”的。一个健康的团队，绝大多数有价值的约定都应该躺在共享的项目级文件里、经过评审、所有人可见；本地文件里只剩下那些真正鸡毛蒜皮的个人化设置。如果你发现自己的本地文件越写越长、塞进去的东西越来越像“团队该知道但我懒得提PR”的规则，那就是个危险信号——说明你在用本地文件逃避协作，这些规则迟早会因为别人不知道而引发冲突。本地文件该是很薄的一层，厚了就说明治理出了问题。

CLAUDE.md的改动，要不要走代码评审？

要，而且必须走。这是保哥给那个乱套团队开的第一剂药，也是见效最快的一剂。

道理很简单：CLAUDE.md里的每一条规则，都会实打实地改变全队AI的行为。一个人在根目录悄悄加上“跳过测试直接提交”，效果等同于偷偷改了团队的CI配置——只不过它伪装成一份不起眼的markdown，没人会盯着看。把它纳入版本控制、让每次改动都走Pull Request评审，就是让这些隐形的行为变更重新变得可见。

具体怎么做，把CLAUDE.md当成和源码同等重要的文件就对了：

• 任何对项目级CLAUDE.md的改动都通过PR提交，至少一个人review，不能直接push到主分支。
• review时重点看三件事：这条规则是不是真的全队适用（不是某人的个人偏好）、它和现有规则有没有矛盾、它是事实约束还是该抽走的多步骤流程。
• 把“为什么加这条”写进commit信息或PR描述。半年后有人问“这条诡异的规则哪来的”，能查到来龙去脉，而不是没人敢删。
• 用块级HTML注释给维护者留备注。官方机制会在注入上下文前把<!-- 维护备注 -->这类块级注释剥掉，所以你可以放心写给同事看，不消耗AI的上下文token。

那一份该被打回的CLAUDE.md改动PR长什么样？实战里见得最多的有三类。一类是“夹带私货型”：在一堆正经改动里混进一条指向自己机器的本地路径，review时一眼就该揪出来让它挪去本地文件。一类是“规则太软型”：加了句“代码要写得优雅一点”，这种没法验证的指令对AI毫无约束力，该被要求要么具体化、要么删掉。还有一类最危险，是“偷改行为型”：表面上只动了一行，比如把“谨慎使用强制推送”改成“可以直接强制推送”，实质是松动了一条安全约定——这种改动恰恰最该被严格审，因为它的破坏力和它的不起眼程度成反比。

走评审还有个隐性好处：它天然拦住了“规则只增不减”的熵增。没有评审时，每个人都倾向于加规则、没人负责删，文件越滚越大；有了评审，新增一条会被问“真有必要常驻吗”，文件才能保持健康。

两个人的规则打架了，到底听谁的？

先说一个让很多人意外的事实：当CLAUDE.md里出现两条矛盾的规则，AI不会智能地选更合理的那条，而是可能随机挑一条执行。官方文档对此说得很直接——如果两条规则互相矛盾，模型可能任意选一个。这就是那个团队里“Redux还是Zustand”乱象的根源：不是AI蠢，是你给了它互相打架的指令，它只能掷骰子。

解决冲突的核心原则只有一个：每个决策点只能有唯一的权威来源。状态管理用什么、API错误怎么返回、测试要不要必跑，这种二选一的事，全队范围内只能有一条规则说了算，发现两条就当场删掉一条。

落地上要建立两道防线。第一道是前面说的PR评审，新增规则时主动检查它会不会和已有的打架。第二道是定期审查——官方明确建议周期性地翻一遍你的CLAUDE.md、子目录里嵌套的CLAUDE.md、以及.claude/rules/下的规则文件，把过时的、冲突的清理掉。建议把这件事固定成团队的月度例行，半小时就能做完，但能避免规则库在不知不觉中腐烂。冲突不会自己消失，只会在某次AI莫名其妙的行为里突然爆发。

这份共享文件，到底该谁负责维护？

规则冲突的更深层根源，是“无主之地”问题：当一份文件人人都能改、却没人专门负责，它的质量必然向下漂移。每个人都倾向于加上自己急需的那条，没人有动力去删别人留下的过时规则，时间一长就成了垃圾堆。给CLAUDE.md指定明确的所有权，是治理里容易被忽略却极其有效的一步。

所有权不是说只有一个人能改，而是说有一个人（或一个小组）对它的整体健康负责。落地有两种常见做法。一种是用仓库的代码所有者机制，把CLAUDE.md和.claude/目录纳入CODEOWNERS，这样任何对它的改动都会自动请到指定的负责人来review，从流程上保证没有规则能绕过把关者悄悄进去。另一种是在团队里明确一个“CLAUDE.md管家”角色，通常由最熟悉项目全貌的人担任，负责主持月度审查、拍板规则冲突、把控文件不要膨胀。

但要避免一个误区：指定所有权不等于把责任全推给一个人。健康的模式是“所有权集中、贡献人人有责”——任何人发现AI因为某条规则犯错，或者发现该补一条新约定，都应该主动提PR，由所有者把关合入。所有者管方向和质量，全员管发现和贡献，这样CLAUDE.md才能既不失控、又持续贴合项目的真实状态。一份没有主人的CLAUDE.md，和一段没有主人的代码一样，最终都会腐烂。

monorepo里各团队的规则怎么互不干扰？

大仓库、多团队是CLAUDE.md治理的高难度场景。前端、后端、数据三个团队挤在一个monorepo里，谁的规则都不该污染别人——后端改接口时，不该被前端的样式约定刷屏；你调构建脚本时，不该背上数据团队的发布规范。

有三件武器配合使用。第一，善用子目录加载机制。Claude Code会自动发现工作目录下子目录里的CLAUDE.md，但它们不是启动就全量加载，而是当Claude真正去读那个子目录里的文件时才加载进来。所以让每个团队在自己的子目录里维护各自的CLAUDE.md，天然就实现了“各管各的”。

第二，用路径作用域规则做更细的隔离。把规则放进.claude/rules/并加paths前缀，让它只在匹配特定路径的文件被操作时才触发。这比往子目录堆大文件更精准，具体写法在极简那篇里讲过，团队场景下它的价值是让“规则随代码区域自动切换”。

第三，也是monorepo专属的一招：用claudeMdExcludes主动跳过别的团队那些与你无关的CLAUDE.md。把它写进你本地的设置文件，就能屏蔽掉上层目录里那些不相关的指令：

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

这条配置的妙处在于它是个人本地生效的，你嫌某些祖先目录的规则碍事，自己排除掉即可，不影响别人。在层级很深的大仓库里，这往往是让上下文回归清爽的关键一步。

monorepo治理还有一条容易被忽视的归属原则：每一份CLAUDE.md都该有清晰的“管辖边界”，写它的人要清楚它会被谁加载。根目录那份是全仓库公约，只该放真正所有团队都适用的极少数规则；各业务子目录那份归各团队自己负责，写自己领域的约定。最忌讳的是在根目录写满某个团队的专属规则——因为拼接机制下，根目录的内容会出现在所有人的上下文里，等于让后端团队天天背着前端的样式规范。一个简单的自检：打开根目录CLAUDE.md，逐条问“这条规则，数据团队的人需要吗？”但凡有一条某些团队用不上，它就该往下沉到对应的子目录或路径作用域里。边界清楚了，各团队才能真正井水不犯河水。

组织级的红线，怎么强制所有人都遵守？

到了公司层面，有些东西不能靠“希望大家自觉”。数据合规、安全策略这类红线，需要一种个人改不动、关不掉的强制方式。这就是组织管理级CLAUDE.md的用武之地。

它部署在系统的管理策略目录（不同操作系统位置不同），由IT或DevOps通过设备管理工具统一下发，加载优先级在用户级和项目级之前，而且不能被任何个人设置排除掉——前面说的claudeMdExcludes对它无效。这保证了公司级指令在每台机器、每个仓库都生效。如果不想单独维护文件，也可以把内容直接写进管理设置文件的claudeMd字段。

但这里有个更重要的判断，很多团队搞混了：CLAUDE.md管的是“行为引导”，真正的“技术强制”要靠设置文件，两者不能互相替代。下面这张对照表是关键：

为什么这个区分对团队这么关键？因为团队规模一大，总会有人有意无意地试探边界——新来的不知道规矩、外包想走捷径、赶工期时有人想绕过检查。如果你的安全防线只写在CLAUDE.md里，它本质上是在“拜托大家别这么干”，而模型在某些上下文压力下真的可能配合用户绕过它。只有把红线落进设置文件的强制层，才是真正焊死的护栏，不依赖任何人的自觉，也不受模型当下判断的影响。团队越大、成员越杂，这条“行为引导归CLAUDE.md、技术强制归设置文件”的分工就越是安全的命脉。记牢这条线：管理设置文件里的规则由客户端强制执行，不管模型怎么想都拦得住；CLAUDE.md只是塑造模型的行为倾向，没有强制力。所以“绝对不能读.env”“绝对不能删生产库”这类零容忍约束，必须写进管理设置的permissions.deny，而不是CLAUDE.md。把硬约束误放进CLAUDE.md，是团队安全治理里最常见也最危险的误判。关于权限白名单和提示注入防护怎么配，Claude Code安全那篇里讲得更系统。

新人入职，怎么靠CLAUDE.md快速上手？

治理做好了，CLAUDE.md会顺带变成团队最好的onboarding文档。官方给的“何时该往CLAUDE.md里加东西”的触发条件里，有一条特别适合团队：当一个新队友需要同样的背景才能高效干活时，就把它写进去。

换句话说，CLAUDE.md应该回答“一个刚加入的人（或AI）需要知道哪些这个项目独有、又没人会主动告诉他的事”。构建命令、目录约定、那些踩过的坑——这些既是给AI的，也是给新人的。一份治理良好的CLAUDE.md，新人clone下来跑一遍，就大致摸清了项目的脾气，比口口相传可靠得多。

实操上，让新人入职时第一件事就是读项目的CLAUDE.md，遇到看不懂的规则当场问，问出来的答案如果有普适价值，就补进文件——这样它会随着团队成长持续保鲜，而不是变成一份没人维护的化石。至于具体怎么把规则写得结构清晰、措辞可执行，CLAUDE.md怎么写才听话那篇有完整的模板和措辞规范。

这里藏着一个反过来的检验视角，很值钱：把CLAUDE.md当作onboarding文档来审视，能反向暴露出它治理上的毛病。如果一个新人读完还是一头雾水，要么说明它写得太抽象（全是“遵循最佳实践”这种空话），要么说明它塞了太多噪音（新人根本分不清哪条是关键约束）。一份合格的团队CLAUDE.md，应该让一个有经验但不熟这个项目的人，读完就能避开80%的坑。每次有新人加入，其实都是对你CLAUDE.md治理水平的一次免费体检——他卡在哪里，哪里就是你该补或该精简的地方。把新人的困惑当成治理的输入，比闭门造车强得多。

本土化：跨境团队和外包协作里，CLAUDE.md治理怎么落地？

回到开头那个跨境独立站团队。保哥给他们做的治理改造，其实就是上面这套东西的组合拳，落到他们的具体场景里。

第一步是清场：把根目录那份混乱的CLAUDE.md按作用域重新分配。个人路径、个人偏好全部下放到各自的CLAUDE.local.md并加进.gitignore；项目通用的架构和约定留在项目级；那条“跳过测试”被直接删掉，改成一个PreToolUse钩子在提交前强制跑测试——因为这是零容忍的红线，不能靠CLAUDE.md自觉。

第二步针对外包。两个外包不在公司的统一管理体系里，没法用组织管理级CLAUDE.md下发。解决办法是把必须遵守的安全约束写进项目级的管理设置文件，随仓库一起给到外包，用permissions.deny从技术层面挡住他们不该碰的目录和命令，而不是指望他们读了CLAUDE.md就乖乖照做。信任要有，但护栏得是硬的。

第三步是防漂移。跨时区协作最怕规则各写各的，半年后又长成一团乱麻。他们定了两条规矩：所有CLAUDE.md改动走PR、每月第一周做一次规则审查清理冲突。另外，因为他们的外包同时还用别的AI编程工具，保哥建议他们把通用规则写进AGENTS.md这个跨工具开放标准，再用一行@AGENTS.md导入到CLAUDE.md里，一份规则两边通用，省掉双重维护。改造完三个月回访，那种“AI行为时好时坏说不清原因”的玄学问题基本绝迹——因为规则终于变得可见、可审、可追责了。

最后提醒一句关于节奏的事：治理的力度要匹配团队的规模，别一上来就上全套。两三个人的小团队，把项目级和本地级分清楚、约定改动走个PR，基本就够了，引入CODEOWNERS和组织管理级反而是负担。等团队涨到七八人、或者开始接外包、跨时区，再逐步加上明确的所有权、月度审查；真到了公司层面多团队共用大仓库，组织管理级CLAUDE.md和管理设置的强制层才变得不可或缺。治理是为了让协作更顺，不是为了堆流程——在合适的规模上用合适的机制，才是真正的治理智慧。

常见问题解答

团队共享的CLAUDE.md该放进版本控制吗？

项目级CLAUDE.md必须进版本控制，它是团队公约，要随源码同步给所有人。但个人专属的CLAUDE.local.md相反，要加进.gitignore绝不提交，否则你的本地路径和个人偏好会污染整个团队。一句话：共享的进库走评审，私有的进gitignore。

CLAUDE.local.md和~/.claude/CLAUDE.md有什么区别？

作用范围不同。CLAUDE.local.md是当前这个项目的个人偏好，只在这个项目生效；~/.claude/CLAUDE.md是你的用户级配置，对你所有项目都生效。本地的放项目特有的私货（如本项目的测试数据），用户级的放跨项目通用的个人习惯（如提交信息风格）。

为什么CLAUDE.md里两条规则矛盾AI会乱来？

因为CLAUDE.md对模型只是行为引导，没有优先级仲裁。官方明确说两条规则矛盾时模型可能任意挑一条执行。所以每个决策点必须只有唯一权威来源，发现冲突当场删一条，并靠PR评审和月度审查防止冲突累积。

monorepo里怎么不让别团队的规则刷屏？

三招配合：让各团队在自己子目录维护CLAUDE.md（按需加载，不进根目录）；用.claude/rules的paths作用域让规则随代码区域自动切换；用claudeMdExcludes在本地设置里主动排除上层那些与你无关的CLAUDE.md，且这个排除是个人生效不影响别人。

怎么强制全公司遵守某条安全红线？

分两层。行为层面用组织管理级CLAUDE.md，部署在系统管理策略目录由IT统一下发，个人无法排除。但真正的硬约束（禁读密钥、禁删库）要用管理设置的permissions.deny做技术强制，它由客户端执行不受模型判断影响。CLAUDE.md引导方向，设置文件守底线。

团队的CLAUDE.md越来越大怎么办？

这通常是治理缺失的症状，不是写法问题。引入PR评审拦住只增不减的熵增，每月审查清理过时和冲突规则，把多步骤流程抽成Skill、把领域规则用paths作用域下放到子目录。靠流程而非靠某次大扫除，文件才能长期保持精简。