用 CLAUDE.md 统一团队 AI 编程规范

dev.to · AI#Claude Code#团队协作#上下文管理

Editor brief · 编辑速览

文章介绍如何通过仓库级 CLAUDE.md 向 Claude Code 提供共享上下文，明确日志库、测试约定和分支规则。团队将该文件纳入版本控制与 PR 审查，使不同开发者的智能体遵循一致规范。

文章思维导图

Knowledge map

拖拽缩放

Full translation

完整中文译文

大多数开发者初次使用 Claude Code 时，走的都是同一条路：打开一个 repo，让它修改代码，得到一个差不多正确的结果。代码能编译，但用错了日志库，没遵守团队约定的测试规范，还把 PR 提交到了错误的分支。

问题不在模型，而在上下文。除非你把团队的情况写下来，否则 Claude Code 对你的团队一无所知。而这些信息，就写在一个叫 CLAUDE.md 的文件里。

这篇指南讨论的是：当这个文件供整个团队共享，而不只是一个人使用时，里面应该写什么，以及哪些错误会让它在一个月后失去作用。

CLAUDE.md 到底有什么用

Claude Code 会在每次会话开始时自动读取 CLAUDE.md。你不需要粘贴文件内容，不需要引用它，也不需要提醒 Agent。只要文件放在项目根目录，它就会进入上下文。

这个文件可以放在三个位置：

对团队来说，最重要的是 repo 级别的文件。它会纳入版本控制，像代码一样接受审查，每个开发者的 Agent 读取的都是同一套规则。

如果你还没创建过这个文件，可以在 Claude Code 中运行 /init。它会扫描 repo，生成一份初始文件。这份初始文件涵盖了代码层面的信息，却没有涵盖团队层面的信息，而后者正是你需要补上的。

团队 CLAUDE.md 必备的五个部分

如果文件里没有答案，Agent 就无从询问「支付代码该由谁来审查？」

## Ownership
| Area | Owner | Reviews required |
|---|---|---|
| payments/ | Payments team | 2, one from payments |
| api/ | Platform team | 1 |
| web/ | Frontend team | 1 |

光是这一点，就能避免一整类不合适的建议，比如在一个 PR 里跨越团队职责边界重构模块。

2. 如何升级处理决策

写清楚任务触及某条边界时，Agent 应该怎么做：停下来询问、创建 issue，还是继续执行。

## Escalation
- Schema changes: never apply directly. Write the migration, open a PR, tag the platform team.
- Anything touching billing: stop and ask before writing code.
- Dependency upgrades: allowed for patch versions only.

简短的命令句比叙述性文字更有效。相比「我们通常希望 schema 变更经过审查」，Agent 更能可靠地遵守「绝不直接应用」。

3. 准确的命令

逐字列出构建、测试和 lint 命令。否则，Agent 就会编出一些看似合理的命令，但看似合理不等于正确。

## Commands
- Install: `pnpm install`
- Test one package: `pnpm --filter <pkg> test`
- Lint: `pnpm lint` (must pass before any commit)
- Never run: `pnpm db:reset` (wipes the shared dev database)

最后这一行，已经让不止一个团队免于度过一个糟糕的下午。

4. 在这里，怎样才算「好」

每个团队都有一些自己觉得理所当然、外人却无从得知的标准。把具体数字写下来。

## Standards
- Test coverage on new code: 80% minimum
- API responses: p95 under 300 ms
- No new `any` types in TypeScript
- Commit messages: Conventional Commits (feat:, fix:, chore:)

5. 工具与系统

使用哪个 issue 跟踪工具、哪套 CI、日志存在哪里、有哪些环境。Agent 在解释下一步该怎么做时，会引用这些信息，所以它们必须符合实际情况。

按角色配置 profile：一个文件不够用时怎么办

当团队成员需要不同的默认行为时，单个 CLAUDE.md 就不够用了。技术负责人希望 Agent 提醒架构风险，新同事希望它解释团队规范，PM 则希望它完全不要碰代码。

一种效果不错的做法是：把共享规则保留在 CLAUDE.md 中，再为每个角色添加一份简短的 profile，由使用者在会话开始时加载。

profiles/
  tech-lead/profile.md
  backend-engineer/profile.md
  product-manager/profile.md

每份 profile 都说明这个角色如何思考、优先考虑什么，以及哪些原则绝不妥协。共享文件保持简短，角色之间的差异则由 profile 承载。

让它失效的四个错误

文件越写越长，最后没人读。超过几屏之后，重要规则就会淹没在琐碎信息里。如果某个部分只与一个文件夹有关，就把它移到那个文件夹里的 CLAUDE.md 中。

只描述，不下指令。「我们团队重视整洁的代码」不会带来任何改变。「超过 40 行的函数，需要用注释解释原因」才会。

内容逐渐脱离实际。文件里说测试用 Jest 运行，但 repo 在三月份已经迁移到了 Vitest。于是，Agent 开始自信地犯错。审查相关代码时，也要一起审查描述这些代码的文件。

只由一个人写一次。最好的 CLAUDE.md，是每个发现 Agent 出错的人都会参与修改的文件。把 Agent 给出的错误建议，当作针对这个文件的一份 bug 报告。

更快写出第一版的方法

团队 CLAUDE.md 需要的大部分信息，其实已经存在于某个地方：入职文档、工程手册，或是记录职责分工的 Notion 页面。真正费时间的，是把这些叙述性文字变成简短、可执行的规则。

我们开发 AI Workspace Builder，就是为了解决这个问题。你上传团队已有的文档（PDF、Markdown、Word 文件或 Notion 页面），它就会提取角色、流程、指标、工具和升级处理路径，然后生成 CLAUDE.md、每个角色的 profile，以及团队级文件。整个过程需要 15 到 30 秒，免费档提供一个试用 workspace，无须绑定银行卡。

无论使用这个工具，还是手动编写文件，原则都一样：Agent 能做得多好，取决于你告诉了它多少团队信息。把这些信息写下来，保持简短，并确保它始终符合实际。

你的 CLAUDE.md 里，哪条规则带来的改变最大？欢迎在评论区分享。

如需进一步处理，可以考虑屏蔽此人和／或举报滥用行为。