Claude Code 团队协作实战：统一风格、约束边界、共享配置、审查流程

四个常见痛点，四套可落地的解决方案，帮助团队从混乱到规范。

先说结论

团队用 Claude Code，最常见的四个问题：

这篇文章假设你的团队已经在用 Claude Code，有一定基础。如果你的团队还没开始用，建议先看《Claude Code 新手教程：从安装到熟练使用的完整指南》，再回来这篇。

一、代码风格统一：CLAUDE.md 为什么比文档有效

问题在哪

团队有编码规范文档，但没人看。新人入职，Code Review 时总要指出风格问题。

用 agent 之后，这个问题被放大了：agent 不会主动翻你的文档，它只看当前对话里的信息。你让它写代码，它按自己的理解来。

CLAUDE.md 为什么有效

CLAUDE.md 是项目根目录的一个文件，agent 每次启动会话都会读。

这意味着： - 不用每次提醒 agent "我们用函数组件" - 不用在每次提示里重复编码规范 - 新成员 clone 项目，规范自动生效

CLAUDE.md 把团队的隐性知识变成了显性配置。

什么该写，什么不该写

一个常见错误是把所有东西都塞进 CLAUDE.md。结果 agent 开始忽略后面的内容。

原则：写 agent 可能猜错的东西，不写 agent 能从代码推断的东西。

该写的： - 命名约定（agent 无法从代码推断团队的命名偏好） - 架构决策（为什么用这个库而不是那个库） - 禁止事项（哪些文件不能动、哪些模式不能用） - 测试命令（agent 无法猜测你的测试框架）

不该写的： - 代码风格细节（Prettier 已经格式化了） - 完整的 API 文档（应该引用文档链接） - 过时的信息（已经下线的功能）

为什么控制在 60 行以内

Claude Code 的系统提示已经占用了大量上下文。留给用户的空间有限。

更关键的是：规则越多，agent 越难全部遵守。

一个实用的做法是把规则分成"核心规范"和"详细文档"。CLAUDE.md 放核心规范，详细文档放在项目其他位置，需要时让 agent 去读。

Hooks 是兜底，不是主力

很多人把 Hooks 当成主要约束手段。但 Hooks 是事后检查——代码已经改完了，你才发现问题。

更好的思路是：CLAUDE.md 让 agent 尽量做对，Hooks 检查它有没有做错。

Hooks 适合检查那些 agent 容易忽略的事情： - 是否修改了保护文件 - 是否符合提交格式 - 是否遗漏了测试

如果 agent 总是犯同一个错误，应该在 CLAUDE.md 里加一条规则，而不是写一个更复杂的 Hook。

二、改动边界约束：agent 为什么容易改太多

问题在哪

让 agent 修一个 bug，它顺手重构了整个模块。让 agent 加一个功能，它改了十个文件。

agent 本意是帮你优化，但你给了它太大的自由度。它不知道边界在哪里，就会按自己的理解去"优化"。

为什么"禁止修改"要写清楚

agent 不懂"这个文件很重要"这种隐含意思。它只知道"用户让我修改代码，哪里有问题我就改"。

所以需要明确告诉它：哪些文件绝对不能动。

在 CLAUDE.md 里写清楚：

## 改动边界

禁止修改：

- database/migrations/* — 数据库迁移

- .github/workflows/* — CI 配置

- package-lock.json — 锁文件

写清楚"动了就报错"，agent 在规划时就会绕开这些文件，而不是等你事后发现再回滚。

Plan Mode 为什么应该成为习惯

Plan Mode 让 agent 先展示计划，你确认后再执行。

很多人觉得 Plan Mode 慢，直接让 agent 执行。但算一下账： - 改对了，Plan Mode 只多花 10 秒 - 改错了，回滚重改要花 10 分钟

Plan Mode 的价值在于确认边界——让改动在你可控的范围内发生。

团队约定：涉及 3 个以上文件的修改，必须用 Plan Mode。这能避免改错了再改回来。

为什么"一次只做一件事"很重要

agent 有个倾向：看到问题就想修，看到"不完美"的代码就想重构。

所以在 CLAUDE.md 里要明确：

## 改动类型约束

- 修 bug 就修 bug，不要顺手重构

- 新功能和修复分开提交

- 重构必须单独发起，说明范围和目标

限制的是变更的爆炸半径。一个改动只做一件事，出问题时容易定位，回滚时影响范围小。

三、团队配置共享：Git 为什么比文档可靠

问题在哪

成员 A 配置了一套好用的 hooks，成员 B 还在手动做同样的事。成员 C 改进了配置，但没告诉其他人。

团队在使用 agent，但每个人用的不是"同一个 agent"。

为什么把配置放进 Git

传统做法是把配置写在文档里，新人入职按文档配置。问题是： - 文档容易过时 - 配置步骤多，容易配错 - 更新了文档，老成员不会重新看

把配置放进 Git，意味着配置变成代码： - clone 项目就获得最新配置 - 配置变更通过 PR 审查 - 回滚配置就像回滚代码一样简单

为什么 settings.json 要分两个

Claude Code 有两个配置文件： - .claude/settings.json — 提交 Git，团队共享 - .claude/settings.local.json — 不提交，个人偏好

分开的原因：团队规范和个人习惯是两回事。

比如： - 团队规定：修改 database/migrations 必须人工确认 → 写进 settings.json - 个人习惯：我喜欢用 haiku 模型快速响应 → 写进 settings.local.json

这样团队成员各自有自己的偏好，但核心约束保持一致。

为什么 onboarding 要检查配置

很多团队 clone 项目后直接开始用，结果 hooks 没生效，规范没加载。

建议在 CLAUDE.md 里加一个检查清单：

## 新成员 Onboarding

- [ ] 运行 claude，确认无报错

- [ ] 运行一条简单命令，确认 hooks 生效

- [ ] 阅读本文件，了解团队规范

这样做能确保每个人用的是"同一个 agent"。

四、审查流程：凭感觉审查为什么不可持续

问题在哪

agent 改完代码，你看了两眼，觉得"应该没问题"，就批准了。

出问题时，不知道是谁的责任——是 agent 写错了，还是你审查不仔细。

为什么需要风险分级

改文档和改数据库，风险完全不同。但很多团队的审查力度是一样的。

风险分级的核心逻辑：把有限的审查资源，集中在风险最高的地方。

高风险变更必须两人审查。风险高的地方，一个人的盲点容易变成事故。

为什么审查清单要写进 CLAUDE.md

审查清单放在文档里，审查时没人看。放在 CLAUDE.md 里，每次 agent 完成任务后可以提醒你检查。

## 审查检查清单

必查项（所有变更）：

- 改动范围是否符合任务描述

- 是否有测试覆盖

- 是否符合编码规范

高风险额外检查：

- 是否有回滚方案

- 是否影响 API 兼容性

把清单放进 CLAUDE.md，意味着审查标准变成了配置，口头约定变成了明确规则。

为什么责任归属要明确

agent 产出，你审查，出问题了谁负责？

明确责任归属的目的，是让每个人知道自己的责任边界： - agent 产出 → 提交者负责检查 - 审查批准 → 审查者共同负责 - 上线后发现问题 → 按变更类型追溯

写在最后

团队用 Claude Code 从混乱到规范，核心是四件事：

1. 统一风格：CLAUDE.md 让规范自动生效

2. 约束边界：明确告诉 agent 哪些不能动

3. 共享配置：配置放进 Git，clone 即同步

4. 审查流程：风险分级，把资源集中在高风险变更

这四件事有先后顺序：

不要一次全上。先从编码规范开始，跑顺了再加边界约束，逐步推进。

工具再强，规范先行。团队的 Claude Code 用得好不好，取决于有没有建立清晰的协作规范。