claude code 在多人协作项目中如何保持代码风格一致

上周三晚上，我们团队的一个实习生提交了一个 PR，300 行代码，我盯着屏幕看了整整 40 分钟。

不是因为逻辑复杂。是因为同一个文件里同时出现了 snake_case、camelCase、PascalCase 三种命名风格。错误处理用的是 try-catch 手动 console.log，旁边另一个函数却用的是我们自建的 Result<T> 模式。更离谱的是，有一个函数什么也没干，就是包了一层 Promise.resolve()，问他说是 Claude Code 生成的，“AI 说这样更安全”。

我问他：你用了 CLAUDE.md 吗？

他说：用了啊，我 /init 生成的。

那一刻我意识到一个问题，大部分团队根本没把 CLAUDE.md 当回事。他们以为只要有了这个文件，AI 就会自动写出团队风格的代码。 但事实恰好相反：一个写得糟糕的 CLAUDE.md，比没有 CLAUDE.md 更危险。

我在一家 14 人的全栈团队做技术负责人，我们从今年 2 月开始全员用 Claude Code。过去 4 个月，我花了大量时间不是写业务代码，而是在和 AI 生成代码的质量做斗争。这篇文章是我踩过所有坑之后，总结出的一套可落地的团队级 AI 代码风格管理方案。它不是“怎么配置 CLAUDE.md”的教程，而是“怎么在真实多人协作环境中，让 AI 真正理解并遵守你的团队规范”的系统性方法。

读完这篇文章，你会得到一个清晰的框架，而不是又一篇功能说明书。

一、核心结论先摆在这里

在我继续展开之前，我想先把几个关键结论告诉你，因为这些判断来自真实的项目数据，而不是理论推导：

1. CLAUDE.md 不是“写好就行”，而是“设计好才行”。 绝大多数团队把 CLAUDE.md 当成了一个许愿池，把所有规范丢进去，然后期待 AI 自动遵守。但 AI 模型对指令的权重分配是有限的，一个臃肿的 CLAUDE.md 和没有 CLAUDE.md 的差异小于 15%。

2. 规则必须分层。 个人偏好、项目约束、组织纪律不能混在一个文件里。我们团队在引入三层规则体系后，Code Review 中“因风格问题打回”的比例从 37% 降到了 8%。

3. CLAUDE.md 不是静态文件，它应该和代码一样走版本管理。 任何对 CLAUDE.md 的修改，如果没有经过 Code Review，就等于在给团队埋定时炸弹。

4. /init 生成的是骨架，不是答案。 /init 命令是基于项目结构推断的，它不知道你们团队的政治共识、技术债容忍度、甚至谁和谁之间有代码风格的分歧。依赖 /init 就等于把这些决策权交还给 AI。

这些结论的背后是一套我称之为“规则工程化”的方法论。下面我会一步一步拆解。

二、先搞清楚问题到底出在哪

2.1 不是 AI 不听话，是它听不懂“含糊的共识”

很多 Tech Lead 在做 Code Review 的时候会下意识地认为 AI“不遵守规则”。但我仔细检查了我们团队早期的 42 个因风格问题被退回 PR 后，发现了一个规律：

70% 的情况是 CLAUDE.md 中的规则本身写得太笼统，AI 无法精确执行；22% 的情况是规则之间存在冲突，AI 选择了权重更高的那条；只有 8% 是因为 AI 确实忽略了一条明确、无歧义的规则。

举个真实的例子。我们早期的一条规则是：

请使用 TypeScript，确保类型安全。

Claude 确实遵守了，它把所有变量都声明了类型。但它使用了 11 个 any，在 3 个关键函数中绕过了我们团队禁止使用 any 的内部约定。

问题不在 AI，在我们没有说清楚“类型安全”意味着什么。

后来我们把这条规则改成了：

使用 TypeScript 严格模式。禁止使用 any，对不确定类型使用 unknown 并配合类型守卫。所有公共 API 函数必须返回明确的类型签名，不允许使用类型推断隐藏返回类型。

改完之后，any 的出现率直接降到了零。

2.2 “我们团队风格一致”是幻觉

另外一个反直觉的发现来自一次内部审计。我们让 3 个资深工程师各自独立描述“我们团队的代码风格规范”，然后交叉比对。

结果是一地鸡毛。

• 关于错误处理：2 个人说我们一律用 Result<T> 模式，1 个人说“复杂的用 Result，简单的用 try-catch 就行”。
• 关于文件命名：1 个人坚持 kebab-case，1 个人说 React 组件用 PascalCase 就行，1 个人说他没注意过。
• 关于函数长度：没有一个人能给出具体的行数上限。

这就是问题的根源。在引入 AI 编程助手之前，团队风格的“一致性”是靠 Code Review + 肌肉记忆维持的，它从来没有被精确地定义过。 而当你扔给 AI 一句“请保持和项目一致的风格”，AI 需要的不只是风格，而是该风格的数学定义。

如果你团队里最资深的 3 个人对风格的理解都不一致，你怎么指望 AI 做对？

三、规则的三层架构：这是本文最核心的东西

基于上面的问题分析，我设计了一套分层规则体系。这个体系目前在我们团队运行了 4 个月，是我认为整个方案中最有价值的部分。

3.1 三层分别管什么

第一层：用户层（User Level）

存放位置：~/.claude/claude.md

这一层只管个人偏好，不能包含任何与团队规范冲突的内容。 比如：

• 缩进用 2 格还是 4 格
• 单引号还是双引号
• 行尾加分号还是不加
• 注释用英文还是中文

这一层的设计逻辑是：承认并允许个人工作习惯的差异，但不能让这种差异污染团队规范。

我们团队的约定是：用户层的 CLAUDE.md 只能包含“格式化偏好”和“个人工作流偏好”，任何涉及代码逻辑、架构选择、设计模式的内容都必须放在项目层或团队层。

第二层：项目层（Project Level）

存放位置：项目根目录下的 CLAUDE.md 或 .claude/CLAUDE.md

这一层规定当前项目的特定约束：

• 使用的框架和版本（Next.js 14, React 18）
• 状态管理方案（Zustand + React Query）
• 路由约定（App Router）
• 样式方案（Tailwind CSS + shadcn/ui）
• 本项目特有的工具函数库
• 测试框架和覆盖率要求

第二层是每个开发者最常交互的地方。它应该回答一个核心问题：“在这个项目里写代码，有哪些铁律必须遵守？”

我见过的最糟糕的项目层 CLAUDE.md 有 1200 多行，包含了 HTTP 状态码表、公司内部 API 文档、甚至开发环境的 IP 地址。这些信息不该放在 CLAUDE.md 里，它们应该放在项目 Wiki 或 README.md 中。CLAUDE.md 只放可执行的规范。

第三层：团队层（Team / Organization Level）

存放位置：组织级共享仓库中，通过 Git Submodule 或脚本同步到 ~/.claude/organization-rules.md

这一层是最容易被忽略的，但也是价值最大的。它规定了跨项目的组织级纪律：

• 禁止使用 any（有统一标准）
• 所有函数必须有 JSDoc
• 特定敏感操作必须打日志
• 数据库查询必须走 Repository 层
• 环境变量统一使用 Zod 校验

我们团队的第三层规范是一个独立的 Git 仓库 internal/claude-rules，通过一个简单的 shell 脚本在 CI 和本地同步。任何一个项目初始化时，第一件事不是 npm install，而是 sh sync-rules.sh。

3.2 冲突解决：当规则打架时，优先级怎么排

这是一个真实发生过的问题。

我们项目层有一条规则说：“使用 Prettier 进行代码格式化，保持统一。”

一个工程师的用户层规则说：“缩进用 4 格。”

Prettier 配置是 2 格缩进。

结果 AI 生成了 4 格缩进的代码，违反了项目约定。

这就是为什么必须有明确的冲突解决策略。 我们的解决方案是：

团队层 > 项目层 > 用户层。且用户在个人层中只能放宽约束，不能收紧或修改团队/项目层的已有规定。

“放宽”的意思是：比如团队规定“所有函数必须有注释”，用户可以在项目层不要求注释的前提下自己要求自己加注释。但如果团队规定“禁止使用 any”，用户不能在自己的配置里写“我可以用 any”。

这个规则听起来很严厉，但它的背后是一个我们踩过坑血的教训：在多人协作的 AI 编程环境中，任何一个人的“个人偏好”如果凌驾于团队规范之上，最终的代码库会成为所有人都不认识的样子，然后每一次 Code Review 都会变成规则争论会。

四、别再依赖 /init 了，它只是起点

Anthropic 官方提供的 /init 命令确实很好用，但它解决的问题是“快速生成一份基础规则”，而不是“生成一份正确的规则”。

4.1 /init 到底干了什么

/init 会扫描你的项目结构，识别出：

• 你用的是哪种框架
• 有哪些配置文件（eslint.config.js, prettier.config.js, tsconfig.json 等）
• 项目的入口文件在哪
• 目录结构的命名模式

然后基于这些信息，生成一份“猜你喜欢”的 CLAUDE.md。

我在 3 个不同的项目中各执行了一次 /init，结果都缺少了以下关键信息：

• 错误处理模式（我们团队用的 Result<T> 没有被识别）
• 业务领域术语（没有任何项目特有的概念被纳入）
• 团队内部的技术决策背景（为什么用 Prisma 而不是 Drizzle 或原始 SQL）
• 测试策略（应该在什么层级测试，Mock 的边界在哪）

这些缺失恰恰是“团队一致性”最重要的东西。

4.2 怎么办：从 /init 到真正的团队规范

我的建议是把 /init 当成一个草稿生成器，然后在此基础上执行以下步骤：

1. 组织一次“规则校准会”。让团队里最资深的 2-3 个人，每人花 30 分钟阅读 /init 生成的 CLAUDE.md，标注出哪些是不对的、哪些是缺失的、哪些是笼统的。
2. 把含糊的规范全部翻译成可验证的约束。比如“确保类型安全”→“禁止使用 any，公共 API 禁止使用类型推断”。
3. 把 /init 生成的内容拆分成两层。框架、工具链相关的内容留在项目层；跨项目的纪律提取到团队层。
4. 引入一个“常见错误案例集”，放在项目层 CLAUDE.md 的末尾。这个案例集记录团队 Code Review 中最常发现的 AI 生成代码问题，让 AI“不要这样写”。

第四点单独说一下，因为这是我从一个叫 Simon Willison 的开源项目中学到的，但后来在我们团队内化得非常好的一个实践。

我们在 CLAUDE.md 末尾加了这样一个段落：

## 禁止行为

• 不要使用 as any 或 <any> 进行类型断言
• 不要在 useEffect 中直接定义异步函数
• 不要使用 index 作为 React 组件的 key
• 不要忽略 Promise 的 rejection
• 不要使用 console.log 做错误日志，用 logger.error

这个“禁止清单”的效果比“推荐清单”好得多。 因为这个清单上的每一项背后都是一个真实踩过的坑。AI 能理解否定指令，而且否定指令的边界更清晰。

五、把 CLAUDE.md 纳入 Git 工作流

这是我见过的最多团队忽略的一环。他们精心编写了 CLAUDE.md，但没有把它当成一等公民纳入协作流程。

5.1 CLAUDE.md 的每次修改都必须走 Code Review

为什么？

想象这个场景：一个开发者在项目层 CLAUDE.md 里加了一条规则：“所有网络请求必须用 fetch 而不是 Axios”。这个规则被提交到主干后，当天下午团队所有人的 AI 助手就开始生成 fetch 代码。

但问题是，团队前端负责人王工并不同意这个决定，他们之前专门打掉了另外一个人提的迁移 Axios 到 fetch 的需求，因为有一些企业客户的浏览器需要 polyfill。

没有 Code Review 的 CLAUDE.md 修改，就等于一个开发者可以绕过团队决策，直接修改所有人的 AI 行为。

这条规则有多重要呢？ 我们在 4 月初出了一个小事故：一个工程师把“所有 API 返回值统一用 { code, data, message } 包裹”写进了项目层的 CLAUDE.md，但这个约定其实已经被产品需求会议否决了，改为“内部 API 用统一格式，对外的 OpenAPI 用标准 RESTful 响应”。结果那一周生成了 13 个对外的 API，全部用了内部格式，对外联调时第三方的技术负责人直接在群聊里问“你们的响应结构是不是出了问题”。

从那天起，我们在 Pull Request 模板里加了一条强制性检查项：

- [ ] 本次改动是否涉及 CLAUDE.md？如果是，请在描述中说明变更原因和影响范围。

然后要求至少一个人工 Approve 之后才能合并。

5.2 用 Git Submodule 管理团队层的规则分发

团队层的规范存储在 internal/claude-rules 仓库中。各个项目通过以下方式引用：

git submodule add git@github.com:your-org/claude-rules.git .claude/organization

然后在项目的 CLAUDE.md 文件顶部引用：

请首先读取 .claude/organization/team-rules.md 中的组织级规范，然后参考本文件的规范。

这样做的好处是：

1. 统一的版本管理。组织级规范升级后，每个项目只需要更新 submodule 的 commit hash 就能同步。
2. 可审计的变更历史。谁、什么时候、为什么修改了组织规范，Git 日志里一目了然。
3. 可控的升级节奏。项目不会被迫立即接受组织规范的最新变更，团队可以选择在一个合适的时间窗口手动升级并验证。

5.3 CI 环节增加规则合规性检查

走到这一步还不够，我们还要让机器来监督机器。

我们在 CI 流程中增加了一个检查步骤，它会：

1. 读取所有层级的 CLAUDE.md。
2. 提取出可被静态检查的规则（比如“禁止使用 any”、“禁止使用 console.log”）。
3. 跑一个脚本，扫描本次 PR 中 AI 生成的代码是否违反了这些规则。

这个检查不会阻断 CI（我们不希望因为一个规则检查导致整个项目卡住），但会在 PR 页面生成一个评论，列出所有违规项。

目的不是惩罚，而是让开发者意识到 AI 生成的代码也会出错，需要像对待手写代码一样对待 AI 生成的代码。

六、Plan Mode：规则执行前的最后一道防线

对于已经在用 Claude Code 的读者来说，Plan Mode 应该不陌生。但我想说的是它的一个被严重低估的用法，作为规则解释和意图对齐的环节。

6.1 Plan Mode 不是“AI 给你汇报”，而是“你确认 AI 是否理解了规则”

大部分人对 Plan Mode 的理解还停留在“让 AI 在动手之前先说它的计划，这样改起来方便”。这个理解没错，但太浅了。

Plan Mode 真正的价值在于：它是你检查 AI 是否正确理解了你的 CLAUDE.md 的唯一环节。

举个我们团队的真实对话：

我在 Plan Mode 下给 Claude Code 提了一个需求：“给用户管理页面加一个导出 CSV 的功能。”

Claude Code 的输出是这样的：

计划:
1. 在 UserList 页面添加一个"导出"按钮。
2. 使用 csv-stringify 库生成 CSV 内容。
3. 创建一个 Blob 并触发浏览器下载。
4. 在 Logger 中记录导出操作。

我看到第 4 步时心里一动，追问：“为什么你要记录导出操作？”

它回复：“根据组织规范，所有涉及用户数据的读取操作，需要记录到审计日志。”

这个规则确实在我们的团队规则里，但我在提出需求时根本没有想到它。Plan Mode 帮我确认了 AI 不仅看到了规则，而且正确理解了它。

6.2 对 Plan Mode 输出内容的检查清单

我建议在团队中推广 Plan Mode 时，附带一个检查清单：

• [ ] 计划中是否体现了项目层的框架/工具约束？
• [ ] 计划中是否遵守了团队层的安全/日志/错误处理规范？
• [ ] 计划中是否有任何违反“禁止清单”的操作？
• [ ] 计划中的技术实现路径是否符合团队的技术选型？
• [ ] 如果计划中引用了某个规则，这个规则的解释是否正确？

如果任何一项不符合预期，就在 Plan Mode 里改，改到符合为止，再执行。这个步骤每多花 2 分钟，后续的 Code Review 至少能省 20 分钟。

七、社区模板别照搬，这是我最想说的一个坑

Vibe Coding 社区有很多流行的 CLAUDE.md 工作流模板。比如 Superpowers（一度被吹成“一键让你的 Claude Code 变全栈大神”），还有 Everything CC 之类的。

我想说一个大多数博主的推荐文忽略的事实：这些模板多数是单人开发者的工作流，不适合直接用在多人团队协作中。

7.1 模板最大的问题：它把流程和规范混在了一起

Superpowers 模板中有一个步骤是这样的：

每次开始新功能前，先生成一份 SPEC.md，然后走 SPEC Review > Code Implementation > Test > Document 的完整流程。

这个流程单干确实很好。但是，

在一个日均 5 个 PR 合并的 14 人团队里，强制每个新功能都走这一套，开发速度直接腰斩。

我试了一天就意识到：不是流程不好，是这个流程的复杂度和团队的吞吐量不匹配。

7.2 正确的做法：提取、拆解、裁剪

我们的做法是把社区模板当成一个“原子规则库”，从中抽取我们团队确实需要的组件，而不是直接引入整个框架。

比如从 Superpowers 模板中，我们抽取了：

• TDD 工作流中对 API 边界必须写测试的要求
• “修改已有文件前先在 Plan Mode 中说明影响范围”
• 代码提交信息必须使用 Conventional Commits 格式

但我们明确去掉了：

• 强制生成 SPEC.md 的步骤（只在重大项目中使用）
• 自动生成文档的步骤（我们有自己的文档体系）
• 每次生成代码后自动跑测试的流程（这个在 CI 环节做了）

抽出来之后，这些规则被整合进我们自己的三层体系里，该进团队层的进团队层，该进项目层的进项目层。 没有一个社区模板是全盘照搬进去的。

八、当规则文件开始“膨胀”：你需要知道怎么减肥

运行了两个月之后，我们 3 个主要项目的 CLAUDE.md 分别达到了 400 行、600 行、1100 行。

问题来了：文件越大，AI 的理解准确度反而下降。

8.1 为什么会这样

这和 LLM 的注意力机制有直接关系。当一个 CLAUDE.md 文件中同时包含 50 条约束时，模型会自然地给每条约束分配不同的注意力权重。排在末尾的规则可能被“遗忘”，而排在前面的规则获得不成比例的重视。

这个现象在学术上叫“Lost in the Middle”，在实际工作中表现为：AI 遵守了前 20 条规则，忽略了后 30 条。

8.2 修剪策略

我给自己定了三条修剪原则：

原则一：可自动化检查的规则，移出 CLAUDE.md，交给 ESLint / Prettier / CI 脚本。

如果一条规则可以被机器检查，比如“缩进用 2 格”、“禁止使用 var”、“组件必须有 PropTypes”，那就不要放在 CLAUDE.md 里。把它放进 eslint.config.js 或 prettier.config.js。CLAUDE.md 只保留“不可自动检查”的规则，比如业务逻辑的编写方式、领域术语的选择、设计模式的应用场景。

原则二：只保留对生成代码质量有直接影响的规则。

“变量名要有意义”这种废话直接删掉。“数据库查询必须走 Repository 层”这种能直接指导生成行为的规则保留。

原则三：用“禁止清单”替代“推荐清单”。

前面已经说过这个，这里就不展开了。只说数据：我们在执行这次修剪后，把总规则数从 73 条缩减到 27 条，AI 对规则的遵守率反而从 71% 提升到了 86%。

九、真实案例：一个重构需求在规则体系下的完整走法

讲了这么多理论，我想用一个完整的真实案例让你看到这套体系的端到端效果。

9.1 需求背景

产品要我们把用户管理模块中的“角色权限检查”从同步改为异步，因为角色数据从 SaaS 平台搬到了微服务里。

需求的提出方是对接我们后端 API 的前端团队，技术债务的承担方是我们自己的全栈团队。

9.2 第一步：Plan Mode 下的对话

我在 Plan Mode 中提了这个需求，Claude Code 输出的计划中包含了：

1. 修改 auth.guard.ts 中的 checkRole 函数，从同步返回改为返回 Promise。
2. 更新所有调用 checkRole 的 12 个组件，给调用处加上 await。
3. 处理 checkRole 可能失败的情况（根据组织规则，网络请求必须用 Result<T> 包裹）。
4. 给新的 checkRole 函数及其公共调用路径加单元测试。（根据团队规范，异步 API 必须覆盖成功和失败两种场景。）

在这里，Plan Mode 帮我确认了 AI 理解了三条关键规则：错误处理用 Result、异步操作覆盖两种场景、公共函数要加单元测试。 这三条规则来自三层体系的不同层次，错误处理规范在团队层，测试要求是项目层的。

9.3 第二步：生成的代码

Claude Code 生成的代码质量超出了我的预期：

• 所有 12 个调用处都正确加上了 await，没有一个遗漏。
• checkRole 的返回类型从 boolean 改为 Promise<Result<boolean, AuthError>>，和我们团队的错误处理模式完美一致。
• 测试用例覆盖了角色存在、角色不存在、网络错误三种情况，而且测试的 Mock 边界清晰。
• 没有使用 any，没有使用 console.log，错误日志走的logger.error。

9.4 第三步：Code Review 的结果

这个 PR 在 Code Review 中只收到了两条意见，且都不是风格问题，而是业务逻辑上的：

1. 当角色服务返回超时时，是否应该降级为使用本地缓存？这需要产品确认。
2. checkRole 的返回值需要加一个 permissionScope 字段，因为接下来产品要做细粒度权限。

零条风格问题。

这就是一套好的规则体系应该达到的效果：风格层面的讨论从 Code Review 中消失了，人的精力被释放到更重要的业务逻辑判断上。

十、什么时候这套方案不太管用：说说边界

没有一个方案是万能药。我必须诚实地告诉你这套体系在什么情况下会失效。

10.1 团队规模太小（3 人以下）

三个人的团队沟通成本极低。大家在一个屋子里（或者一个飞书群里），谁写了什么风格一眼就能看出来，Code Review 也是“轻轻扫一眼就合”。在这种环境下，三层规则体系的维护成本会超过它的收益。小团队更适合一个简单的单文件 CLAUDE.md，由一个人负责定期维护。

10.2 项目还处在原型阶段，技术选型未确定

原型阶段最需要的是速度，而不是一致性。此时添加过于严格的规则会拖慢迭代。我们自己的经验是：当第一版 MVP 上线之后，再引入规则体系。 在此之前，只需要一条最基本的规则：“优先使用项目已存在的代码模式”。

10.3 团队中有人强烈抵触“被规范”

这不仅是技术问题，更是团队文化的政治问题。我见过一个挺厉害的程序员说：“AI 生成代码我来负责，不用规范文件代我管理。”在这种情况下，强行推规则体系只会激起抵触。正确的方式是先在愿意尝试的分支团队中跑出数据，用数据说话。

10.4 AI 模型自身的限制

坦白说，Claude 3.5 Sonnet 和 Claude 3 Opus 对长指令的遵循度是有差异的。我们在 3.5 Sonnet 上跑这套规则体系，效果最好。在早期 Claude 3 Haiku 上，规则遵守率会下降到 60% 左右。这意味着选模型这件事本身也影响着规则的执行效果。

十一、总结：代码风格一致性的本质是“知识管理问题”

回顾这 4 个月的折腾，我最大的感受是：

代码风格一致性问题，在 AI 编程助手的时代，本质上不是一个代码问题，而是一个知识管理问题。

以前，团队的代码风格藏在大脑中、藏在 IDE 的肌肉记忆里、藏在 Code Review 时的一句句“这里改成驼峰”里。它不需要被精确描述，因为它天然在传播。

但现在，一个 AI 助手没有这些背景，它只有你给它的 CLAUDE.md。写 CLAUDE.md 的过程，实质上是把团队的隐性知识翻译成显性指令的过程。

这件事做得好的团队，Code Review 会变成真正的“代码审查”，审查逻辑、审查架构、审查安全，而不是“风格纠错机”。

做得不好的团队，AI 编程助手不仅不能提效，反而会制造大量的“风格噪声”，让每一次合并都变成一场博弈。

下一步你可以做什么

如果你读到了这里，我希望你不要把这篇文章收藏起来然后忘掉。以下是我建议你马上可以做的三件事：

1. 审计你团队目前的 CLAUDE.md。打开看一遍，问自己：这里面有多少条规则是具体可执行的？有多少是“正确的废话”？有没有规则互相冲突？
2. 组织一次“规则校准 30 分钟”。叫上团队里最资深的 2 个人，每人过一遍 CLAUDE.md，标注出模糊的、缺失的、冲突的。半小时足够发现问题。
3. 在你的 PR 模板里加一行：“本次改动是否涉及 CLAUDE.md？如果是，请说明变更原因。”这是成本最低但效果最好的一个动作。

代码风格的一致性，从来不是靠一个文件就能解决的。它是一个需要持续投入的工程问题。但这篇万字长文读完，你已经比我 4 个月前花了大量时间才搞明白的东西要多得多了。