第 19 章 · 团队协作规范
本章目标：建立团队级 Claude Code 使用规范——共享 CLAUDE.md 模板、code review 流程、MCP/Skills 配置管理与新成员 onboarding，让整个团队"用同一种方式与 AI 协作"。
19.1 团队 CLAUDE.md 模板
个人使用的 CLAUDE.md 可以随心所欲，但提交到仓库的版本是团队的契约——它决定了每个成员（以及 CI 中的 agent）的行为一致性。
一个经过实战检验的团队模板：
# CLAUDE.md
## 项目概述
电商平台后端，Node 20 + TypeScript + PostgreSQL 15。
## 环境与命令
- 安装: pnpm install
- 测试: pnpm test（单文件: pnpm vitest run <path>）
- 构建: pnpm build
- Lint: pnpm lint && pnpm format
## 代码规范
- 函数优先于类；导出函数必须带 JSDoc
- 数据库操作一律通过 src/db/ 的 repository 层
- API 错误响应统一用 AppError 类
- 禁止 any 类型；unknown 需收窄后使用
## Git 约定
- 分支名: feat/<ticket> / fix/<ticket>
- Commit message 用 Conventional Commits
- PR 标题 = commit subject
## 注意事项
- 不要修改 migrations/ 下已应用的迁移文件
- .env.local 包含本地密钥，永远不要读取或修改它版本控制策略
CLAUDE.md 和 .claude/settings.json 提交到 git；.claude/settings.local.json 和 .claude/credentials 加入 .gitignore。前者是团队契约，后者是个人偏好。
多层 CLAUDE.md
Monorepo 中可以在子目录放置额外的 CLAUDE.md：
repo/
├── CLAUDE.md # 全局规范
├── packages/api/CLAUDE.md # API 特有约定
└── packages/web/CLAUDE.md # 前端特有约定Claude 会自动加载当前工作目录及其祖先的所有 CLAUDE.md，实现"全局规范 + 局部覆写"。
19.2 Code Review 流程集成
PR 审查辅助
Claude Code 最有价值的团队场景之一：自动化初步审查：
# 在 feature 分支上生成变更摘要供 reviewer 参考
claude -p "对比 main 分支，总结这个 PR 改了什么、有什么潜在风险" \
--allowedTools "Read" "Bash(git diff*)" \
> pr-summary.mdGitHub Actions 自动审查
在 CI 中集成 Claude 进行第一轮审查：
# .github/workflows/claude-review.yml
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Claude Review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
npm install -g @anthropic-ai/claude-code
claude -p "审查此 PR 的代码变更。关注：安全问题、逻辑错误、性能隐患。
以 markdown 列表输出发现的问题及严重程度。" \
--allowedTools "Read" "Bash(git diff*)" \
--output-format text >> review-comment.md
- name: Post Comment
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const body = fs.readFileSync('review-comment.md', 'utf8');
await github.rest.issues.createComment({
...context.repo,
issue_number: context.issue.number,
body
});定位
AI 审查是初筛不是终审——它能捕获格式违规、明显 bug 与遗漏测试，但架构决策仍需人类判断。团队应明确标注"Claude 已审"标签避免重复劳动。
19.3 共享 MCP 与 Skills 配置
项目级 MCP 配置
将 MCP 服务器配置写入项目根目录的 .mcp.json 并提交：
{
"mcpServers": {
"database": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "${DATABASE_URL}"
}
},
"figma": {
"command": "npx",
"args": ["-y", "@anthropic/mcp-figma"]
}
}
}团队成员克隆仓库后运行 claude mcp list 即可看到所有预配置的服务器——零配置上手。
团队 Skills 目录
把常用技能放在 .claude/skills/ 中随仓库分发：
.claude/skills/
├── deploy-checklist/SKILL.md # 发版检查流程
├── db-migration/SKILL.md # 迁移文件编写规范
└── api-endpoint/SKILL.md # 新端点脚手架任何成员的 agent 在匹配到相关任务时都会自动加载这些技能，确保输出遵循同一套流程。
19.4 新成员 Onboarding
传统 onboarding 需要 1–2 周；有了完善的 Claude Code 配置，可以压缩到数天：
Day 1: 克隆仓库 → claude 启动 → agent 自动加载 CLAUDE.md
问 Claude："这个项目的架构是什么样的？核心业务流是什么？"
（比看 Wiki 快得多——agent 直接读代码回答）
Day 2: 用 /init 或手动完善 CLAUDE.md（新人视角常能发现文档盲区）
尝试第一个 good-first-issue，全程与 Claude 结对
Day 3+: 提交 PR → 触发 Claude Review → 学习团队的 code review 标准关键洞察：新成员改进 CLAUDE.md 的过程本身就是最高效的学习过程——为了让 AI 理解，你必须先理清自己的理解。
19.5 团队反模式清单
| 反模式 | 后果 | 解法 |
|---|---|---|
| 每人维护自己的 CLAUDE.md 不共享 | 行为不一致，review 成本高 | 统一入 git，个人偏好放 local |
| 把密钥写进 settings.json 提交 | 密钥泄露 | 密钥走环境变量或 apiKeyHelper |
| AI 审查意见全盘接受不人工复核 | 幻觉建议被合入 | AI 标注为"建议"，merge 由人决定 |
| Skills/MCP 配置散落在各人文档里 | 无法复现 | 全部收敛到 .claude/ 和 .mcp.json |
本章小结
- CLAUDE.md 是团队契约：提交到 git，个人偏好用
settings.local.json； - Monorepo 利用多层 CLAUDE.md 实现"全局 + 局部"的规则叠加；
- GitHub Actions +
claude -p可搭建自动化初审流水线； .mcp.json与.claude/skills/让工具和知识随仓库分发；- 新成员通过"阅读并改进 CLAUDE.md"完成最高效的 onboarding。
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. 团队使用 Claude Code 时，哪些文件应该提交到 git？
2. Monorepo 中根目录和 packages/api/ 各有一个 CLAUDE.md，Claude 如何处理？
3. 关于 AI 代码审查在团队中的定位，最合理的态度是？
4. 为什么说"让新成员改进 CLAUDE.md"是高效的 onboarding 方式？
🛠️ 动手实践
- 为你的团队仓库编写一份完整的 CLAUDE.md（技术栈+约束+命令），提交后让两位成员分别测试同一任务的输出一致性。
- 搭建本章的 GitHub Actions 审查流水线，对一个真实 PR 运行一次，评估 Claude 发现问题的质量与误报率。
- 编写一个
.claude/skills/deploy-checklist/SKILL.md，内容为你团队的发版检查步骤，验证它在提到"部署"时会被自动触发。