Claude Code 团队协作指南：交接、评审与权限边界

Claude Code 个人使用时很快能带来效率提升：调查代码、修改实现、补测试都更顺。但团队采用后，真正的难点会变成流程问题：谁批准了哪个命令，Claude 看过哪些文件，哪些地方还没有验证，AI 的建议是否已经由人确认。

这篇文章给出一套适合 2 到 10 人开发团队的落地做法。它覆盖团队交接、PR 预评审、CLAUDE.md 规则、权限边界、新人上手、故障交班和沟通失败模式。这里的“权限边界”指 Claude Code 可以读取、编辑、运行的范围；“评审回执”指 PR 中记录 AI 建议如何被人处理的短说明。

flowchart LR
  A["开发者请求"] --> B["CLAUDE.md 和规则"]
  B --> C["Claude Code 工作"]
  C --> D["测试与差分检查"]
  D --> E["评审回执"]
  E --> F["人工 PR 评审"]

先固定四个团队位置

团队流程不能只靠某个人记住好用提示词。规则要放进仓库中可复用的位置。

位置	目的	是否提交
CLAUDE.md	项目约定、禁止事项、测试命令	是
.claude/settings.json	团队共享权限、deny 规则、hooks	是
.claude/settings.local.json	个人沙箱地址、临时设置	否
.claude/prompts/*.md	交接、评审、调查模板	是

官方文档说明了 Claude Code 记忆、设置、权限 和 安全 的分工。站内可继续参考 CLAUDE.md 最佳实践、Claude Code hooks 指南 和 GitHub Actions 高级用法。

用例1：从开发者交接给评审者

最常见的失败是 PR 里只写“Claude 已经修了”。评审者真正需要的是：Claude 看了哪些文件，批准了哪些命令，测试是否失败，还有哪些判断必须由人决定。

创建 .claude/prompts/handoff.md：

# 生成团队交接说明

请读取当前差分，并按下面格式写交接说明。

## 目标
- 本次修改要解决的问题:

## 变更范围
- 已修改文件:
- 未修改但可能受影响的文件:

## 验证情况
- 已执行命令:
- 通过/失败:
- 失败日志摘要:

## 评审者重点关注
- 产品判断:
- 安全:
- 性能:
- 测试缺口:

## 下一位负责人
- 需要先确认:
- 可以稍后处理:

准备好差分后运行：

claude -p "读取 git diff，并按照 .claude/prompts/handoff.md 的格式生成团队交接说明"

把结果贴进 PR 正文。这样评审者可以从风险点开始看，而不是重新猜测上下文。跨时区或异步团队尤其需要这种可追踪交接。

用例2：用 AI 做 PR 预评审

Claude Code 不应该替代人工批准。它更适合做预评审，先抓明显 bug、缺测试、安全风险和不一致修改，让人工评审把注意力放到设计判断上。

创建 .claude/prompts/pr-review.md：

# PR 预评审

请按以下角度评审差分：

1. 可能导致 bug 的分支、null/undefined、边界值
2. 授权、输入校验、秘密信息暴露
3. N+1 查询、过度重新渲染、沉重同步处理
4. 是否违反 CLAUDE.md 规则
5. 缺少的测试用例

输出格式:
- 严重度: 高 / 中 / 低
- 文件:
- 行或函数:
- 原因:
- 修改建议:

仅凭推测的指摘必须标注“需确认”。

本地可以配合 GitHub CLI 执行：

gh pr diff 123 | claude -p "$(cat .claude/prompts/pr-review.md)"

如果用 GitHub Actions 自动化，只让它发表评论，不让它决定是否可合并。

name: Claude PR pre-review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  pre-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install tools
        run: npm install -g @anthropic-ai/claude-code
      - name: Run Claude Code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          gh pr diff "$PR_NUMBER" > /tmp/pr.diff
          claude -p "$(cat .claude/prompts/pr-review.md)

          差分:
          $(cat /tmp/pr.diff)" > /tmp/claude-review.md
          gh pr comment "$PR_NUMBER" --body-file /tmp/claude-review.md

官方的 common workflows 也介绍了评审和测试辅助流程。团队规则要写清楚：AI 评论只是参考，最终批准必须由人完成。

用例3：新人上手

新人最常卡住的不是语法，而是“哪个命令安全”“业务规则在哪里”“第一天应该看什么”。Claude Code 很适合先生成一份仓库导览。

claude -p "
请为新成员解释这个仓库。
必须包含：
- 主要目录及职责
- 本地启动、lint、test、build 命令
- 最先阅读的 3 个文件
- 修改前需要确认的业务规则
- 常见失败和规避方法
- 30 分钟内可以完成的练习任务

不确定的内容不要猜测，请列为需确认。
"

不要直接发布 AI 输出。让熟悉项目的人花 30 分钟补上 Claude 不可能知道的内容：生产约束、团队历史、运维风险。大型调查可以结合 subagent 使用模式 把探索和总结分开。

用例4：故障调查和交班

故障期间，Claude Code 可以帮助摘要日志、整理假设。但风险也更高：把秘密信息贴进提示词，把未验证假设当事实传播，或者换班时丢失“已经试过什么”。

把下面模板保存为 .claude/prompts/incident-handoff.md：

# 故障交班

## 现象
- 从什么时候开始:
- 影响范围:
- 用户影响:

## 已观察到的事实
- 日志:
- 指标:
- 复现步骤:

## 已尝试
- 命令:
- 结果:
- 失败的假设:

## 剩余风险
- 数据破坏:
- 安全影响:
- 回滚状态:

## 下一位负责人
- 先看的画面/日志:
- 绝对不要执行的命令:

给 Claude Code 的日志要先遮盖邮箱、访问令牌和客户 ID。安全文档也提醒了权限审批和提示词注入风险；团队应把日志当生产数据处理。

有效的 CLAUDE.md 规则

CLAUDE.md 用来放团队反复说明的事实。它应该短、具体、可检查。

# Claude Code 项目指令

## 开始前
- 编辑前先运行 `git status --short`。
- 不要回滚已有的用户修改。
- 产品行为不明确时，在 PR 中写“需确认”。

## 代码规则
- 所有 API 输入都要校验。
- 数据库写入要明确事务边界。
- 新增 UI 文案前优先复用已有翻译 key。

## 测试
- 逻辑变更要补单元测试。
- bug 修复要补 1 个回归测试。
- 无法执行的测试要说明原因。

## PR
- 写明变更内容、验证内容、剩余风险。
- Claude Code 的建议必须经过人工确认后才采用。

如果仓库已有 AGENTS.md，可以在 CLAUDE.md 中导入，避免重复维护。

@AGENTS.md

## Claude Code 专用规则
- 计费、认证、删除流程要先用 plan mode 给出作业方针。
- `git push`、生产部署、迁移执行由人完成。

用 settings 固定权限边界

团队采用时最危险的是为了方便而放大权限。建议先写 deny，再写最小 allow。

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm test)",
      "Bash(git diff *)",
      "Bash(git status *)",
      "Edit(src/**)",
      "Edit(tests/**)"
    ],
    "ask": [
      "Bash(npm install *)",
      "Bash(git commit *)",
      "Write(.github/**)"
    ],
    "deny": [
      "Read(.env*)",
      "Read(**/secrets/**)",
      "Bash(git push --force*)",
      "Bash(rm -rf *)",
      "Bash(npm publish*)"
    ]
  }
}

hooks 可以在编辑后运行检查，也可以阻止危险命令。上线前请阅读官方 hooks reference。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --quiet"
          }
        ]
      }
    ]
  }
}

这个例子要求项目里存在 npm run lint。大型 monorepo 不适合每次编辑后跑全量 lint，应改成文件级检查或交给 CI。

在 PR 中留下评审回执

AI 评审最危险的地方，是没人记录哪些建议被采用、哪些被拒绝。把下面内容放进 PR 模板。

## Claude Code 评审回执

- 使用的提示词:
- Claude Code 查看过的差分:
- 已采用的建议:
- 未采用的建议及理由:
- 人工追加确认:
- 已执行测试:
- 剩余风险:

最终判断人:

没有使用 Claude Code 时写“未使用”即可。重点是不要让 AI 辅助过的 PR 透明度更低。

具体失败和对策

失败	影响	对策
CLAUDE.md 过期	旧命令和废弃 API 被继续使用	每月基于真实失败更新一次
权限过宽	秘密信息和生产级操作离 AI 太近	先写 deny，再写最小 allow
只靠 AI 批准	产品判断和责任人消失	PR 批准必须由人完成
口头交接	第二天无法追踪原因	交接说明贴到 PR 或 Issue
/clear 删除上下文	修改理由丢失	reset 或 compact 前先保存摘要
hooks 太重	成员开始绕过流程	用文件级 hooks 或 CI

沟通失败也很常见。“帮我改好”会让 Claude Code 猜完成条件。更好的写法是：“只改这个函数”“不要碰 schema”“先读失败测试日志”。

最小团队检查清单

• CLAUDE.md 写了命令、禁止事项和 PR 规则
• .claude/settings.json 区分 allow、ask、deny
• .claude/settings.local.json 已加入 .gitignore
• 交接、PR 评审、故障交班提示词已共享
• PR 模板包含评审回执
• 最终人工判断人明确
• 新成员有 30 分钟练习任务

ClaudeCodeLab 会持续更新这类 AI 团队开发模板。如果你想更快推进内部导入和模板整理，可以参考 ClaudeCodeLab 产品。

总结

Claude Code 的团队协作不是寻找神奇提示词，而是建立共享指令、狭窄权限、可追踪交接和可审计评审回执。

个人使用时，记住几个好提示词就能提升效率。团队使用时，更重要的是别人能复现流程，失败时能追踪原因，并把 Claude Code 的建议与人的判断分开记录。

Masa 在一个小型验证仓库中试用这套流程后，最明显的改善来自 PR 里的交接说明和评审回执。评审者少问了很多“你确认过什么”。反而每次编辑后跑全量 lint 的 hook 太慢，放到 CI 更现实。建议先从 CLAUDE.md、PR 预评审提示词和评审回执这三项开始。