# 团队落地：配置、评审与度量

> 一个人用得好不等于一个团队用得好。本课讲共享配置怎么进仓库、AI 生成代码的评审规范与责任归属、哪些度量指标有意义而哪些会误导、新人培训路径，以及推广中最常见的反模式。

- 网址：https://coding.chengyu.dev/learn/engineering/team-adoption/
- 学习路径：AI 编程的工程方法
- 预计用时：35 分钟；核实日期：2026-10-25
- 官方来源：[Settings files and precedence（Claude Code 官方文档）](https://code.claude.com/docs/en/settings)，[Explore the .claude directory（Claude Code 官方文档）](https://code.claude.com/docs/en/claude-directory)，[Set up Claude Code for your organization（Claude Code 官方文档）](https://code.claude.com/docs/en/admin-setup)，[Configure permissions（Claude Code 官方文档，工作区信任）](https://code.claude.com/docs/en/permissions)，[Connect Claude Code to tools via MCP（Claude Code 官方文档）](https://code.claude.com/docs/en/mcp)，[Code Review（Claude Code 官方文档）](https://code.claude.com/docs/en/code-review)，[Track team usage with analytics（Claude Code 官方文档）](https://code.claude.com/docs/en/analytics)，[Manage costs effectively（Claude Code 官方文档，试点与基线）](https://code.claude.com/docs/en/costs)，[Set up Claude Code in a monorepo or large codebase（Claude Code 官方文档）](https://code.claude.com/docs/en/large-codebases)，[Best practices for Claude Code（Claude Code 官方文档）](https://code.claude.com/docs/en/best-practices)，[Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity（METR）](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/)，[2025 DORA State of AI-assisted Software Development（DORA）](https://dora.dev/research/2025/dora-report/)

## 学习目标

- 能把项目级设置、Skill、MCP、Hook 放进仓库，并区分哪些该共享、哪些该留给个人
- 能制定 AI 生成代码的评审规范和 PR 描述模板，明确责任归属
- 能选出有意义的度量指标，并识别会被刷高或造成误导的指标
- 能设计团队试点与新人培训路径，避开常见的推广反模式

一个团队里，三个人把智能体用得出神入化，三个人偶尔试试，还有一个人长期开着 `--dangerously-skip-permissions`。每人都有私藏的提示词。评审的人开始抱怨：PR 越来越大，描述越来越空，「这段是 AI 写的」成了没人负责的话。

团队落地的难点从来不是工具，而是**把个人技巧变成团队资产，同时让责任不因为 AI 而变模糊**。这一课分四块：共享配置、评审规范、度量、推广路径。

## 一、共享配置：让仓库本身就是上手指南

Claude Code 的配置分作用域，决定了谁能看到：

| 文件 | 提交到仓库 | 用途 |
|---|---|---|
| `CLAUDE.md` / `AGENTS.md` | 是 | 项目说明，团队共有 |
| `.claude/settings.json` | 是 | 权限、Hook、插件、环境变量 |
| `.claude/rules/*.md` | 是 | 按主题或路径划分的规则 |
| `.claude/skills/`、`.claude/agents/` | 是 | 可复用的流程与子智能体 |
| `.mcp.json` | 是 | 团队共享的 MCP 服务器 |
| `.claude/settings.local.json`、`CLAUDE.local.md` | 否 | 个人覆盖，留在自己机器上 |

优先级从高到低是：托管设置、命令行参数、本地设置、项目设置、用户设置。数组类的设置（如 `permissions.allow`）是合并而不是覆盖，所以个人可以追加，不会冲掉团队的。

一份起步用的团队 `.claude/settings.json`：

```json
{
  "permissions": {
    "allow": ["Bash(npm run verify)", "Bash(npm test *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
  },
  "sandbox": { "enabled": true },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}
```

有几个官方文档里的细节，决定了你的共享配置会不会「悄悄不生效」：

- 项目里的 `allow` 规则和 `additionalDirectories` **要等每位成员信任该文件夹后才生效**；`deny` 和 `ask` 立即生效，因为它们只收紧不放宽。
- `permissions.defaultMode` 设为 `auto` 或 `bypassPermissions`，**写在项目设置里不起作用**，要在用户或托管设置里设，这是为了防止仓库替你放开权限。
- `.mcp.json` 在交互式会话中会让每个人批准；但 `claude -p`、SDK 和云端会话没法弹窗，会直接加载。CI 里要用 `disabledMcpjsonServers` 等手段显式控制。

### 软约定与硬约束要分开

官方管理员文档里一个很有用的区分：**托管 CLAUDE.md 是行为指引，托管设置才是技术强制。** 想要「无论如何不许做」的事，写进托管设置：

- `permissions.deny` 禁止某些工具、命令或路径；
- `sandbox.enabled` 强制沙箱；
- `permissions.disableBypassPermissionsMode` 关掉 `--dangerously-skip-permissions`；
- `allowManagedPermissionRulesOnly`、MCP 允许名单、插件市场白名单等。

托管设置可经管理后台、MDM 或系统目录里的 `managed-settings.json` 下发，级别高于一切本地配置，开发者能追加、但无法移除其中的数组条目。

### 把配置本身当成高危代码来评审

**`.claude/`、`.mcp.json`、Hook 脚本、说明文件，都是「会影响智能体行为、甚至会在开发者机器上执行命令」的文件。** 一条恶意或粗心的 Hook 就是一段会在每位同事机器上运行的 shell。所以：

- 用 CODEOWNERS 把这些路径指派给安全或平台负责人；
- 收到来自外部贡献者的 PR 时，先看这些文件改了什么；
- Code Review 官方设计里就体现了这条逻辑：审查指令文件 `REVIEW.md` 只从基础分支读取，**绝不取自 PR 自身的改动**，免得被审的人改写审查规则。

约定过多时，官方大仓库指南建议把共享约定打包成**插件**，放进内部市场由平台团队统一管理版本，而不是在每个目录堆说明文件。

## 二、AI 生成代码的评审规范

先立一条底线：**谁提交，谁负责。** 作者要对 PR 里每一行负责，不论是敲的、复制的还是智能体写的。「AI 写的」既不是缺陷的理由，也不是免于评审的理由。

智能体改变了评审的经济学：生成极便宜，阅读依然昂贵，所以规范的核心是**限制评审者的成本**。

### PR 描述模板

```markdown
## 做了什么 / 为什么
（一两句话，说明意图，而不是复述 diff）

## 怎么验证的
- [ ] `npm run verify` 通过（贴输出）
- [ ] 手动或浏览器验证：（步骤与结果 / 截图）
- 新增或修改的测试：（列出，并说明测试文件有无被放宽断言）

## AI 参与情况
- 使用的工具与主要任务：
- 我亲自审阅过全部 diff：是 / 否（若否，说明哪些部分没审）
- 我做的关键决定（不是 AI 做的）：

## 风险与未覆盖
- 影响范围：
- 没有测到的地方：
```

### 评审者的检查点

- **先看测试，再看实现**：测试是否有意义？有没有在这次 PR 中被放宽、跳过或删掉？
- **看范围蔓延**：改动的文件是否都与任务相关？智能体特别爱「顺手」重构。
- **看重复造轮子**：是否又写了一个项目里已有的工具函数？
- **看过度防御和过度抽象**：不会发生的分支、只用一次的接口层。
- **看依赖与配置变更**：新增的包、`.github/workflows`、权限、Hook（见第 4 课）。
- **看被删掉的东西**：被移除的校验和错误处理，常比新增代码更危险。

规模也要设规矩。把单个 PR 控制在评审者能一次读完的体量，超了就让作者拆成多个提交或堆叠 PR。

### AI 评审是第一遍，不是最后一关

官方的 Code Review（Team 与 Enterprise 版）会让多个智能体并行审查 PR，并增加一个验证步骤过滤误报，结果以行内评论呈现，**它既不批准也不阻止合并，决定权仍在你们团队**；官方也明说，「没有发现」不代表代码没问题。本地也可以用 `/code-review` 在提交前自查。我的建议：让 AI 评审抢在人之前跑，把低级问题先清掉，但**合并必须有人类评审者背书**，且不能让「AI 评审 + AI 作者」成为唯一的闸门。

## 三、度量：什么有意义，什么会误导

先看两条公开证据，它们都在提醒我们：感觉不可靠。

- **METR 的随机对照试验**（2025 年初）：16 位经验丰富的开源开发者，246 个真实任务。允许使用 AI 时，完成时间反而长了 19%；而他们事前预期会提速 24%，事后仍认为自己提速了 20%。METR 强调这只是当时工具和特定场景下的快照，并在 2026 年发布了更新说明当时结果已不能代表现状。教训不是「AI 会拖慢你」，而是**自我感觉不能当数据**。
- **DORA 2025**：核心结论是 AI 是放大器，会放大组织已有的长处，也会放大已有的问题；回报主要来自底层的系统与流程，而不是工具本身。

Claude Code 自己的分析面板能看到：已接受的代码行数、建议接受率、带 Claude Code 参与的 PR 数与占比、日活与会话数，还有排行榜。官方也说明这些数据偏保守，归因是靠把合并 PR 里新增的行与会话输出做匹配，开发者大幅改写（差异超过 20%）的代码不计入。**它们适合看采用度，不适合衡量产出。**

| 指标 | 判断 | 理由 |
|---|---|---|
| 交付周期（从开始到上线）、PR 评审时长 | 有意义 | 反映价值真的更快流到用户手里 |
| 变更失败率、回滚/热修率 | 有意义 | 速度的另一面，是 AI 代码质量的试金石 |
| 返工率（合并后一周内被改写的比例） | 有意义 | 捕捉「看起来完成」的伪效率 |
| 评审来回轮数、CI 一次通过率 | 有意义 | 反映 PR 质量与规范是否到位 |
| 新人到首个合并 PR 的天数 | 有意义 | 衡量培训路径与仓库友好度 |
| 每个合并 PR 的 token 成本 | 有参考价值 | 把成本和结果绑在一起，而不是只看总花费 |
| 生成/接受的代码行数 | 会误导 | 行数是成本不是价值，容易被刷高 |
| 建议接受率 | 会误导 | 接受不等于正确，也不等于不会被改回去 |
| AI 参与的 PR 占比 | 仅看采用度 | 一当目标就会被凑数 |
| 人均 token 消耗排行榜 | 会误导 | 古德哈特定律：指标一变成目标，就不再是好指标 |

使用原则：**先建基线，再看变化**；官方成本文档也建议先用小规模试点组摸清基线再扩大。采用度类数据用来找「谁适合当导师」，不要用来排名。再配合问卷、评审抽样、复盘等定性信息，防止漂亮的数字掩盖真实体验。

## 四、推广路径与新人培训

### 试点到铺开

1. **选一个小组试点**（3 到 5 人，最好含一位持怀疑态度的资深工程师），先记录基线：交付周期、变更失败率、成本。
2. **先整理仓库，再推工具**：一键验证命令、AGENTS.md、沙箱与权限配置（第 6 课）。
3. **沉淀共享资产**：把试点中反复用到的提示词变成 Skill、把踩过的坑写进规则、把必须强制的写进 Hook 或托管设置。
4. **立评审规范和 PR 模板**，之后才扩大范围。
5. **每月复盘**指标与摩擦清单，裁剪不再有用的配置。

### 新人培训路径

官方最佳实践提到，让智能体回答代码库问题是有效的入职方式，既缩短上手时间，也减少打扰老员工。建议的节奏：

- **第 1 天**：只读，向智能体提问熟悉项目（「日志是怎么做的」「怎么新增一个接口」），不改代码。
- **第 1 周**：修一个带复现步骤的小 bug，要求先写失败的测试，自己审阅 diff 并能口头解释每一处。
- **第 2 周**：用计划模式完成一个小功能，提交 PR，描述里写清验证证据。
- **第 3 周**：写一个 Skill 或 Hook，解决一个自己遇到过的重复问题。
- **第 4 周**：评审一个同事的 AI 参与的 PR。

对初级工程师要格外小心：智能体让产出变快，却可能让理解变慢。保持一条规则：**作者必须能解释自己 PR 里的每一处改动**，不能解释就不能合并；也可以定期安排不用智能体的练习。

### 常见反模式

| 反模式 | 症状 | 修正 |
|---|---|---|
| 把使用率当 KPI | 凑数的提示、没必要的 AI 参与 | 度量结果（周期、质量），不度量过程 |
| 巨型无主 CLAUDE.md | 越来越长、互相矛盾、没人敢删 | 指定负责人，改动走评审，定期瘦身 |
| 人人关闭权限确认 | 笔记本上 `bypassPermissions` | 用沙箱与托管设置，让安全路径同时是省事的路径 |
| 作者没读就提交 | PR 里出现作者自己也解释不了的代码 | 模板里加「我审阅过」，评审时抽问 |
| AI 审 AI 是唯一闸门 | 合并无人背书 | 人类评审者是合并的必要条件 |
| 私人提示词库 | 好用的东西只在个人手里 | 沉淀为 Skill，进仓库评审 |
| 不测量就扩大 | 说不清是否真的变好 | 先基线，后试点，再扩大 |
| 只在资深工程师中推广 | 初级的成长路径被忽略 | 配套培训与解释要求 |

**审计仓库里已提交的智能体配置**

```text
请审计本仓库中已提交的智能体相关配置，只读，不要修改任何文件。范围：CLAUDE.md、AGENTS.md、.claude/ 下的全部文件（settings.json、rules、skills、agents、hooks 脚本）、.mcp.json。

从三个角度输出报告：
1. 安全：Hook 与脚本会执行什么命令，是否访问网络或读取敏感路径；permissions 的 allow 是否过宽；是否有明文密钥；MCP 服务器的来源与权限；
2. 有效性：说明文件是否超过 200 行、是否有互相矛盾或过期的规则、哪些内容应该下沉到子目录说明文件、Skill 或 Hook；
3. 团队协作：哪些该共享却只在个人机器上，哪些是个人偏好却被提交到了仓库。

每条发现给出：文件与位置、问题、风险等级（高 / 中 / 低）、建议的改法。最后列出我应该立刻处理的前三项。
```

> 小测：团队想用数据评估引入智能体后的效果。下面哪一组指标最能反映真实的工程成效？

> 小测：一位开发者提交了一个由智能体生成的 PR，评审时发现其中一处逻辑有安全漏洞。责任最合理的归属是？

- [ ] 盘点仓库里已提交的 `.claude/`、`.mcp.json`、Hook 脚本，并用 CODEOWNERS 指定负责人
- [ ] 在团队的 `.claude/settings.json` 里加入 `deny` 规则与沙箱，并确认 `defaultMode` 没有写在项目设置里
- [ ] 把上面的 PR 模板放进仓库的 PR 模板文件，试行两周后根据评审反馈修订
- [ ] 选 3 到 5 个有意义的指标建立基线，并明确哪些指标不会用于个人考核
- [ ] 按新人培训路径为下一位入职者排一份四周计划，其中至少包含一次写失败测试的练习

延伸阅读：[Claude Code 精通：权限](/learn/claude-code/permissions/)、[Skills](/learn/claude-code/skills/)、[Hooks](/learn/claude-code/hooks/)、[Headless 与 CI](/learn/claude-code/headless-ci/)。到这里，工程方法路径就走完了。接下来可以回到[实战：测试与评审](/learn/ship/test-review/)，把规范在真实项目里跑一遍。