团队如何管理 CLAUDE.md 和项目规范

团队 CLAUDE.md 治理教程：谁维护项目记忆、写什么、不写什么、如何评审更新、如何避免规则过时和冲突。

团队里的 CLAUDE.md 不是个人备忘录。

它会影响每个成员使用 Claude Code 时的项目理解、任务边界和代码风格。如果没人治理，CLAUDE.md 很快会变成过时规则、临时记录和个人偏好的混合物。

团队 CLAUDE.md 应该写什么

适合写：

• 项目结构说明。
• 运行和检查方式。
• 代码风格和目录约定。
• 安全边界和禁止事项。
• 常见任务流程。
• 测试和验收要求。
• 团队约定的汇报格式。

不适合写：

• 临时需求。
• 个人待办。
• 密钥、账号、Token。
• 过时命令。
• 未确认的猜测。
• 太长的业务背景故事。

谁来维护

建议明确角色：

不要让每个人都随手往 CLAUDE.md 追加内容。

一条规则能不能写进去

判断一条内容是否适合写进 CLAUDE.md，可以问 5 个问题：

1. 这条规则是否长期有效？
2. 是否能被代码、文档或团队约定证明？
3. 是否会影响多数成员使用 CC？
4. 是否足够具体，能指导行动？
5. 未来过时后是否容易发现？

如果只是某次任务的临时要求，就不要写进 CLAUDE.md。可以放在任务描述、PR 描述或临时交接文档里。

更新流程

1. 提出规则更新原因。
2. 说明影响哪些任务。
3. 标明规则来源：代码、团队约定、文档还是经验。
4. 经过 Review。
5. 合并后通知团队。

规则更新也应该像代码一样可审查。

建议每次更新都写清：

• 新增了什么规则。
• 为什么需要它。
• 影响哪些任务。
• 是否替换旧规则。
• 是否需要通知团队。

不要用“补充一些规范”这种模糊提交说明。

让 CC 帮忙审查 CLAUDE.md

请审查当前 CLAUDE.md 是否适合团队长期使用。

重点检查：
1. 是否包含临时任务。
2. 是否包含敏感信息。
3. 是否有过时命令或路径。
4. 是否和项目代码实际情况冲突。
5. 是否过长或重复。
6. 哪些内容应该拆到其他文档。

只做审查，不要直接修改。

团队 CLAUDE.md 模板

# 项目协作规则

## 项目概览
项目类型、技术栈、核心目录。

## 常用检查
启动、构建、测试、lint。

## 任务边界
哪些任务可以小步修改，哪些必须先评审。

## 安全规则
密钥、生产数据、隐私、权限边界。

## 代码约定
目录、命名、组件、接口、错误处理。

## 汇报格式
计划、改动、验证、风险。

多团队协作时怎么拆

如果项目很大，不要把所有规则塞进一个文件。可以拆成：

根目录只放全局规则，模块规则放到对应位置。这样 CC 读到的上下文更准确，也更容易维护。

规则冲突怎么处理

团队里经常会出现新旧规则冲突。比如旧规则说用某个目录，新代码已经迁移到另一个目录。

让 CC 帮忙找冲突：

请检查 CLAUDE.md 中是否存在互相冲突的规则。

重点看：
1. 同一件事是否有两种说法。
2. 规则是否和当前目录结构冲突。
3. 命令是否已经不可用。
4. 是否有重复、过时或互相覆盖的约定。
5. 每个冲突给出证据。

只做审查，不要直接修改。

发现冲突后，不要让 CC 自己决定保留哪条。应该由模块负责人或项目负责人确认。

过时规则怎么处理

不要让旧规则静静留着。

可以定期让 CC 做检查：

请根据当前项目文件，检查 CLAUDE.md 中是否有过时规则。

要求：
1. 每条过时规则给出证据。
2. 不确定的标为待确认。
3. 不要直接删除。
4. 给出建议更新版本。

定期治理节奏

团队可以按这个节奏维护：

CLAUDE.md 不是写完就结束，它要跟项目一起演进。

验收标准

一个团队级 CLAUDE.md 至少应该做到：

• 新成员能看懂项目基本结构。
• CC 能知道哪些文件和命令重要。
• 高风险任务有明确边界。
• 不包含密钥、临时任务和个人待办。
• 规则和当前代码一致。
• 更新经过 Review。

如果做不到这些，CLAUDE.md 就不是团队记忆，而是新的噪音源。