团队落地：配置、评审与度量 - AI 编程的工程方法

一个团队里，三个人把智能体用得出神入化，三个人偶尔试试，还有一个人长期开着 --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：

{
  "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 描述模板

## 做了什么 / 为什么
（一两句话，说明意图，而不是复述 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 消耗排行榜	会误导	古德哈特定律：指标一变成目标，就不再是好指标

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

四、推广路径与新人培训

试点到铺开

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

新人培训路径

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

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

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

常见反模式

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

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

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

从三个角度输出报告：

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

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

小测

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

小测

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

动手清单

0/5

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

延伸阅读：Claude Code 精通：权限、Skills、Hooks、Headless 与 CI。到这里，工程方法路径就走完了。接下来可以回到实战：测试与评审，把规范在真实项目里跑一遍。