主题
最佳实践与质量保障
一句话：AI Coding 的瓶颈不在生成速度，而在验证速度——十条原则、四维度量、三层审查，本质都是把“验证”做成流程，让 AI 的产出以已知的风险进入主干。代价是前置投入和审查开销，收益只在验证能力跟得上时才成立。
为什么需要
引入 AI 后最常见的两个现象：个人觉得快了很多，团队交付周期没变；合并速度上去了，回滚和线上缺陷也跟着上去。原因不复杂——生成变便宜了，验证没有变便宜。过去写代码占大头，现在评审、跑测试、排查“看起来对但逻辑错”占大头。
如果继续用“谁写得快”评价团队，就会系统性奖励“生成得多、验证得少”，把成本推到线上。治理要解决的不是“怎么让 AI 写得更多”，而是“怎么让每一段 AI 代码都以已知的风险被验证过”。
核心机制
十条原则：每条都在补一个失效点
| 原则 | 没有它会怎样 | 怎么做 | 代价 |
|---|---|---|---|
| 规格先行 | 空白处由模型自行补全，返工发生在 CR 甚至上线后 | 先写验收标准再让 AI 动手，规格进仓库（见 03-SDD规格驱动） | 每个任务多 30–60 分钟前置思考，琐碎改动不划算 |
| 小步快跑 | 千行 diff 没人能真审，错误定位从分钟级变小时级 | 一个任务对应一条验收标准，PR 控制在 300 行内 | 拆任务本身要花时间，上下文切换变多 |
| 测试是安全带 | 代码能跑但不敢改，第一次重构就回归 | 生成实现时同时生成测试，先让测试红 | 写测试可能比写实现更久，而且测试也会写错 |
| 上下文是氧气 | 模型编造不存在的 API，风格与仓库不一致 | AGENTS.md + 相关文件 + 真实报错一起给 | 拼上下文要时间与 token，给太多反而稀释注意力 |
| 不信任只验证 | “看起来对”的代码直接上线，缺陷延后暴露 | 测试、CR、实际运行三关都过 | 验证成本决定净收益，这是 AI 提速的真实上限 |
| 项目宪法 | 每个人的 AI 风格不同，CR 都在吵格式 | AGENTS.md 固化技术栈、命令、约定、禁区 | 规则要维护，过长会被忽略，过时会误导 |
| 人决策 AI 执行 | 架构由“哪个方案更常见”决定，债务半年后爆发 | 人定接口、数据模型、边界，AI 填实现 | 人成为瓶颈，且必须能审自己没写的代码 |
| 安全底线 | 注入、越权、密钥硬编码随生成速度一起放大 | CI 挂 SAST/SCA，认证支付加密类双人审 | 误报拖慢合并，扫描多花几分钟 |
| 持续迭代规则 | 同一个错误全团队重复犯 | 每次 AI 犯错复盘成一条 AGENTS.md 规则 | 规则膨胀、互相冲突，需要定期删 |
| 度量驱动 | “感觉快了”，实际是缺陷搬到了线上 | 四维看板，按周看趋势不看单点 | 采集有成本，指标一旦进绩效就会失真 |
十条可以归成三组：1–5 管单次生成的质量，6–7 管团队一致性，8–10 管长期运行。跳过任何一条，失效都不会立刻显现，而是在两周到两个月后以返工、事故或“大家又回到手写”的形式出现。
度量：四个维度，缺一个就会被刷
生成速度是最容易被感知、也最容易失真的指标。只看它，团队会去优化代码行数和 PR 数。四维一起看，才能判断收益是真的还是搬了家。
| 维度 | 指标 | 定义与采集方式 | 内部基线（先采集 2–4 周自身数据） |
|---|---|---|---|
| 效率 | PR 周期 | 首次提交到合并的中位小时数；Git 平台 PR API 按周聚合，用标签区分是否 AI 参与 | 相对自身基线下降 30–50% |
| 效率 | 代码接受率 | AI 建议在 N 天后仍保留的行数占比；插件埋点或 diff 存活分析 | > 60% |
| 效率 | 补全使用率 | 接受的补全次数 / 展示次数；IDE 插件埋点 | > 30% |
| 效率 | 任务完成时间 | 同类任务从开工到可交付的时长；任务系统打标加抽样复核 | 标准化任务下降 40–60% |
| 质量 | Bug 密度 | 每千行变更引入的缺陷数，按引入 PR 归属；缺陷系统与 PR 关联 | 不高于人工代码基线 |
| 质量 | 新增代码覆盖率 | 本次 diff 的行/分支覆盖率，不是全仓；CI 覆盖率报告 | ≥ 80% |
| 质量 | CR 意见数 | 每个 PR 的有效评论数，去掉风格类与机器人评论；平台 API | 趋势下降 |
| 质量 | 高危漏洞数 | SAST/SCA 报出且确认可利用的高危项；CI 扫描报告 | 0 |
| 质量 | 变更失败率（change failure rate） | 发布后需回滚或热修的比例；发布系统与缺陷系统关联 | 先采 2–4 周基线，看趋势 |
| 质量 | 交付前置时间（lead time） | 首次提交到上线的时长；Git 与发布系统按周聚合 | 相对自身基线下降 |
| 质量 | 平均恢复时间（MTTR） | 故障发生到恢复的时长；告警与事故系统 | 相对自身基线下降 |
| 成本 | token / 人 / 天 | 输入加输出 token 总量；网关或代理日志按人聚合 | 设阈值告警，不设目标 |
| 成本 | AI 成本 / 功能点 | 一个需求消耗的模型与工具费用；需求单关联会话 ID | 趋势下降 |
| 成本 | 订阅 ROI | 节省工时折算 / 工具总费用；季度抽样工时加财务数据 | 仅参考，不作考核目标 |
| 满意度 | 开发者 NPS | 推荐意愿 0–10 分，推荐者占比减贬损者占比；月度匿名问卷 | 仅参考，不作考核目标 |
| 满意度 | 周活跃率 | 一周内至少一次有效使用的开发者占比；插件或网关日志 | > 80% |
| 满意度 | 学习曲线 | 新人独立跑完一次完整 AI 工作流所需天数；入职跟踪 | < 2 周 |
读法：效率指标必须与质量指标同向解读——PR 周期降了但 Bug 密度升了，不是提效，是把返工推给下游。成本要看单功能点而不是总量，总量会随使用人数自然上涨。ROI>3x、NPS>40 只是社区口径，不是考核目标；先采集 2–4 周自身数据形成内部基线，再谈提升。
反模式
| 反模式 | 后果 | 替代做法 |
|---|---|---|
| 把 AI 当自动补全 | 收益停在打字速度，工作流没变 | 按任务用 Agent 或规格驱动，补全只做局部 |
| 无规格直接生成 | 结构由模型即兴决定，推到重来 | 先写验收标准，再拆任务 |
| 盲目追求覆盖率 | 测试为数字而写，断言空转 | 看新增代码覆盖，配合突变测试检验断言有效性（见 04-TDD与测试质量） |
| 全自动合并 | 没有人对语义负责 | 自动化只挡机械问题，语义必须有人签字 |
| 只测正常路径 | 异常与边界上线才暴露 | 边界、超时、依赖失败优先于 happy path |
| 全团队一刀切同一工具 | 部分人效率反而下降 | 统一模型与规范，工具让开发者自选 |
| 只看速度不看质量 | 交付快了，技术债同步暴涨 | 四维度量，质量不下降是底线 |
这些反模式共同点是“把 AI 的输出当成终点”。它们的代价都要过一段时间才显现，靠感觉纠正不了，只能靠流程和度量兜住。
成熟度：判据是“约束有没有进系统”
分界线不是用了多少工具，而是约束从“人记”变成“系统拦”。L2 到 L3 的关键是门禁，没有门禁的规范只是建议；L3 到 L4 的关键是能证伪，没有基线的度量只是报表。跳级最常见的后果是有工具、没门禁，返工把收益吃回去。
三层审查：机械问题不进人眼
自动化层的作用是把机械问题挡在人工之前，让人只花时间在业务语义上；顺序反过来，人会先被格式和类型错误耗掉注意力。分级的意义是审查成本随风险上升——所有 PR 都套最重的流程，结果一定是大家开始绕过流程。超过 1000 行退回拆分，是因为超大 diff 的审查质量会断崖下降，名义上审过、实际没人看完。工具类别可按功能组合：CodeRabbit 类 PR 评论、SonarQube 类规则扫描、CodeQL 类语义查询、Snyk 类依赖漏洞扫描，只按功能列，不排名。
CR 意见要可执行，包含三件事：定位到行或函数、说清不改的后果、给出改法。这里写得不好 等于把问题退回给作者；第 42 行把 userId 拼进 SQL，存在注入，改为参数化查询 db.query("... WHERE id = ?", [userId]) 才能直接改。AI 生成的 CR 意见同样按这三条筛，只说“建议优化”的一律不采纳，并把这类样本拿去调提示词。
实战场景
事故复盘：AI 写的测试全绿，上线当天挂了
某团队让 AI 实现优惠券叠加逻辑并在同一对话里补全测试：CI 全绿，新增代码覆盖率过门禁阈值，正常合并。上线第一天，两张券叠加时折扣被重复计算，监控告警爆发。回查发现：实现对每张券都在“已打折”的中间态上重复应用；而测试把折扣应用函数整个 mock 掉，只断言调用次数和顺序——测试验证的是实现的结构，不是业务行为，所以计算规则怎么错，测试都是绿的。代价：半天回滚加订单数据修复；伤害更大的是团队险些据此得出“AI 不能写测试”的结论，退回全盘手写。
关键部位还原：
python
# 实现节选：每张券都在上一轮的中间价上重复应用折扣
result_price = price
for c in coupons:
result_price = apply_discount(result_price, c)
# 测试节选：断言的是调用结构，不是金额
apply_discount = Mock(return_value=90)
assert apply_discount.call_count == 2 # 实现换成上面那版错误逻辑，这里照样全绿复盘把情绪和机制分开：测试全绿来自“生成与验证同源”——AI 写实现和写测试时理解的是同一个（错误的）行为，自洽一致。人写测试同样会踩这个坑，只是 AI 的高速生成把“顺着实现写测试”的错误放大了。修复是两条纪律：
- 先红后绿：AI 一次生成实现加测试后，先临时删除或回退实现，确认测试变红，再恢复实现。红不起来的测试判为无效，不允许进合并。CR 清单里“测试能失败”一条写的就是这件事，但纪律要落在提交之前，而不是等 CR 来补。
- 变异测试抽检：每迭代抽核心函数，人为把实现改成错误但可编译的版本（边界取反、条件翻转），看测试能否抓住；全绿说明断言空转。做法见 04-TDD与测试质量，抽检比例可从核心链路函数的 10%–20% 起步（经验值，需按团队校准）。
这对应十条原则里“测试是安全带”与反模式“盲目追求覆盖率”：覆盖率度量的是代码被执行过没有，不是行为被断言过没有。挡不住上线当天翻车的，从来是测试的失败能力。
场景：Code Review 被 AI 产出量压垮
全面放开 AI 后，闸口先出现在评审环节：人均日 PR 从 1.5 个升到 4 个，PR 平均规模从 200 行以下涨到 700 行以上（经验值，基线因任务类型而异）。三周后三个指标同向恶化：有效 CR 意见数首次下降、Bug 密度上升、评审人平均响应时长翻倍。抽查发现，800 行以上的 PR 评审人均只花 11 分钟——不够读完一遍 diff，就按“AI 生成且测试绿”签了字。
这正是“生成变便宜、验证没有变便宜”打在人身上的形态，要求评审人“快一点”没有用。修复是配额式实践，而不是提高产量：
| 实践 | 规则 | 依据 |
|---|---|---|
| 小批量 | 一个 PR 对应一条验收标准；超 300 行要求拆分说明，超 1000 行退回拆分，落进 CI 与 PR 模板 | 三层审查分级、“小步快跑”原则 |
| 可验证单元 | PR 描述必须含变更文件清单、对应验收标准、验证命令与输出；缺项不进评审队列 | “不信任只验证”——AI 说完成不算证据 |
| 评审预算 | 单 PR 人工评审以 30 分钟为上限（经验值）；超出说明拆任务失败，退回而不是硬审 | 把拆分成本压回作者，而非评审人兜底 |
执行三周：人均 PR 数量回落，PR 周期中位数反而下降——因为返工和回滚减少了。这正是四维度量的读法：效率指标必须与质量指标同向解读，单看速度上升而质量恶化，只是把返工推给了下游。
案例：一次提示词资产化的收益
一个 8 人前端团队的问题很具体：每个人和 AI 对话时都要口头交代同一套项目约定——组件目录结构、请求封装的用法、错误码展示规则、禁用库。交代过，但没人交代得完全一样；结果 PR 风格四散，CR 讨论集中在约定而非业务。回溯两个月内 20 个 AI 参与的 PR，6 个的返工直接源于约定违反（经验值，样本小，只看趋势）。
资产化动作不大，但每一条都有约束：
- 只写已经踩过的坑：首版 AGENTS.md 31 行，只含技术栈与版本、安装/测试/lint/类型检查四条命令、6 条可判定的禁止项；没写任何“理论上应该”的条款。方法来自 02-对话编程基础：先不写，按重复失败追加。
- 每次返工追加一条：约定类返工复盘后写成一条可判定规则，附反例位置，能进 CI 的同步进 CI。半年后文件稳定在 78 行。
- 明确不进文件的约定：易过期细节——临时 feature flag 清单、进行中的接口字段变更、待升级的依赖备忘——放任务单或规格，不进仓库约定文件。能存活三个月以上的可判定条款才配占用上下文预算，写进去的易过期内容过期后就是误导源。
收益量化按度量一节的方法：先采 2–4 周自身基线再对比。半年后抽样中约定违反类返工占比从 30% 降到 10% 以下，约定类 CR 意见接近清零，评审注意力回到业务语义。同时边界没有丢：AGENTS.md 是提示不是权限——6 条禁止项里可自动化的全部落进了 CI，剩下的仍靠 CR 兜底。文件替代的是重复交代，不是门禁；这正是“持续迭代规则”与“安全底线”两条原则必须搭配使用的原因。
最小上手
把下面的清单贴进 PR 模板，AI 参与的 PR 逐项勾选，任一项为“否”不合并。它覆盖自动化查不出来的部分，机械检查交给 CI。
markdown
<!-- AI 代码 CR 清单 v1：适用于 AI 参与生成的 PR -->
- [ ] 每条验收标准都有对应代码和测试，没有需求之外的「顺手加」
- [ ] 边界齐全：空值、空集合、0、负数、最大值都有明确行为
- [ ] 异常路径明确：超时、依赖失败、重试与降级不会静默吞错
- [ ] SQL、shell、文件路径中的外部输入已参数化或转义
- [ ] HTML / 富文本输出已转义；使用 `dangerouslySetInnerHTML` / `innerHTML` 时有白名单或消毒
- [ ] 文件路径拼接前校验，拒绝 `../` 与绝对路径穿越
- [ ] 每个接口都校验资源归属，既防水平越权（改他人 ID）也防垂直越权（低权限调高权限）
- [ ] 事件监听、定时器、订阅在卸载或销毁时清理，避免内存泄漏与重复回调
- [ ] 测试彼此独立：不依赖执行顺序、共享可变状态或真实外部服务
- [ ] 无硬编码密钥，日志不打印 Token、手机号、身份证
- [ ] 循环内无数据库或远程调用（N+1）；新增查询走索引且未 SELECT *
- [ ] 外部 API 与库函数已对照官方文档确认存在、参数与版本正确
- [ ] 测试能失败：临时删掉实现后测试应报错；Mock 未替代被测逻辑
- [ ] 符合 AGENTS.md 的命名、目录、错误码与依赖约定
- [ ] 变更量 ≤ 300 行，超出已拆分并说明理由AI 代码 CR 特殊注意点
| 注意点 | 典型表现 | 审查动作 |
|---|---|---|
| 自信地写错 | 术语、流程、边界都说得通，结论却反了 | 关键断言回到代码、测试或日志验证，不看语气 |
| 幻觉 API | 调用了不存在的库函数、参数或版本 | 对照官方文档与仓库锁文件，跑一次真实构建 |
| 忽略 AGENTS.md | 命名、目录、错误码、依赖与项目约定不符 | 把约定变成 CI 检查；CR 先看 diff 是否绕开规则 |
| 假测试 | 断言空转、Mock 掉被测逻辑、只覆盖 happy path | 临时删实现看测试是否变红；检查断言对象与边界 |
生产动作
- 试点选择：挑 2–3 个任务边界清楚、有测试基础、失败可回滚的模块，不要从核心交易链路开始。参与者选愿意公开自己工作流的种子用户，不做行政指派；试点两周只回答一个问题——同类任务的验证时间有没有下降。
- 门禁：按上表落到 CI，只留少量硬规则——新增代码 diff 覆盖率低于阈值阻断，SAST 高危阻断，单 PR 超 300 行要求拆分说明，超 1000 行必须拆。门禁只拦机械问题，语义留给人和架构评审，规则一多就会被绕过。
- 度量复盘：周看效率与质量，月度看成本与满意度，季度算 ROI。复盘只问三件事：哪个指标恶化、对应哪类任务、要不要改规则。指标异常先核对采集口径，再怀疑人。
- 推广节奏：试点 → 标准化 → 规模化 → 治理。标准化是把试点里的提示词、AGENTS.md、清单固化成模板；规模化按团队铺开，工具自选、模型与规范统一；治理是看板加定期规则清理。每阶段用判据退出而不是按日历推进——标准化的判据是新团队照模板能独立跑通。
边界
- 探索性原型和一次性脚本不必套全套：规格与测试的投入可能大于收益，验证到“能跑通、无外部输入”即可。
- 度量有反身性。指标一旦进绩效，就会被优化而不是被改善；看趋势、看组合，不把单一指标挂到个人考核。
- 三层审查的成本随团队规模上升。五人以下团队用自动化加一人 CR 就够，硬套三层只会让人绕过流程。
- 清单会过期。每季度删掉已自动化或不再发生的条目，超过 15 条就没人看。
- 成熟度不是越高越好。L4、L5 依赖平台和数据基础，业务方向不稳定时，把 L2、L3 做扎实比追新更有价值。
讲清楚
AI Coding 真正改变的不是写代码的速度，而是成本结构：生成几乎免费，验证仍然昂贵。所以治理的核心是把验证流程化，而不是催着大家多用 AI。十条原则分别补的是单次生成、团队一致性和长期运行三类失效点，其中最关键的是“不信任只验证”——净收益等于生成节省的时间减去验证增加的时间，验证跟不上，提速就是零甚至为负。度量要四个维度一起看，只看 PR 周期会把返工推到线上；成熟度看的是约束有没有进系统，而不是用了多少工具。落地时从边界清楚、可回滚的模块试点，用门禁挡住机械问题，用三层审查分配人的注意力，再按判据逐级推广。
适用：2026 年企业级 AI Coding 治理 | 初稿 2026-10