S01-A04 · 工具选型的 ADR 与工程效能度量

适用读者：要拍板"用哪个工具/怎么定标准"，并且要为结果负责的人。
前置：S01-A01（标准化）、S01-A02（制品治理）、S01-A03（文档平台）。
版本基线：ADR 格式（adr.github.io 社区惯例）、DORA 四指标（2024 版口径）。
覆盖旧文：无（本篇为 E 驱动，属方法论）。
新增扩展：E-S01-032（ADR 模板与评审清单）、E-S01-033（效能度量口径）。
上一篇：S01-A03 · 文档与知识库平台架构
下一篇：S02 · 计算机与网络基础（下一系列）。

1. 一句话结论

决策不记录，就会被重复讨论；度量不对齐，就会变成 KPI 游戏。

这一篇是本系列的方法论收尾，只讲两件工具：

工具	解决	用在
ADR（Architecture Decision Record）	"为什么当初这么定？"	每次不可逆或高昂的选择
度量口径	"变好是什么样？"	每次改进的前后对比

2. ADR：一页纸，四段话

2.1 模板

# ADR-0007 · 统一使用 mvnw 而非手装 Maven

- 状态：已采纳 ｜ 日期：2026-11-05 ｜ 决策者：平台组
- 影响范围：全部 Java 仓库 ｜ 相关：ADR-0005（版本矩阵）

## 背景与问题
各人 Maven 版本不同（3.6/3.8/3.9），同一 commit 在不同人机器上构建结果不一致；
插件默认版本随 Maven 变化，已出现"某台机器构建失败、另一台成功"。

## 决策
所有 Java 仓库提交 `mvnw`（wrapper 3.3.4+），`maven-wrapper.properties` 锁定 Maven 3.9.9；
CI 与本地一律用 `./mvnw`。

## 备选方案与被否原因
1. **文档要求大家装 3.9.9** —— 依赖自觉，无法验证；已试过 1 年，失败。
2. **CI 强制检查 `mvn -v`** —— 能查但麻烦，且无法解决"本地与 CI 打包差异"。
3. **只锁插件版本** —— 必要但不充分（Maven 本身的行为也会变）。

## 后果
- 正面：构建可复现；新人无需装 Maven。
- 负面：仓库多两个文件；wrapper 首次运行要下载 Maven（需镜像可用）。
- 回滚：删除 `mvnw`/`.mvn`，恢复手装；代价是回到不一致状态。

## 验证
同一 commit 在两台机器与 CI 上 `./mvnw -B verify`，产物 sha256 一致。

2.2 什么是"值得写 ADR"的决策

特征	例子	写不写
不可逆或回滚昂贵	选数据库、定制品仓库	✅
影响多人日常	版本矩阵、分支策略	✅
有争议且被否过	"为什么不用 X"	✅（记录被否方案最重要）
纯个人偏好	主题色、编辑器字体	❌
可随时换	某个 CLI 小工具	❌

ADR 的价值 80% 在"备选方案与被否原因"。只写"我们决定用 A"的 ADR，半年后等于没写——因为没人知道"为什么不选 B"。

3. ADR 评审清单（评审人用）

#	检查项	不合格表现
1	问题陈述是否具体到"能判断是否解决"	"提升开发效率"（无法验证）
2	是否至少有 2 个备选方案	只有 1 个 → 说明没比较
3	被否方案的原因是否可检验	"B 不好用"（主观）vs "B 在 500 篇文档时构建 > 5 分钟"（可测）
4	负面后果是否写清	只写好处 → 不诚实，日后打脸
5	回滚路径是否存在	没有回滚 = 不可逆决策，风险等级要提高
6	验证方式是否可执行	"大家觉得快了" vs "构建耗时 P50 从 4:10 降到 2:30"
7	是否有负责人与复审时间	无人负责的决策会烂尾

4. 度量：四个指标 + 三条纪律

4.1 DORA 四指标（工程效能的事实标准）

指标	定义	反映
部署频率	单位时间成功发布次数	交付速度
变更前置时间（Lead Time for Changes）	commit → 上线的时间	流程摩擦
变更失败率	发布导致需回滚/热修的比例	质量
恢复时长（MTTR）	故障到恢复的时间	韧性

S01 相关的补充指标（工具链层面的先行指标）：

指标	为什么它是"先行"的
环境类工单占比	工具链问题会在交付指标恶化之前先冒出来
构建一致率（同 commit 重跑一致）	不一致 → 变更失败率的根因之一
新人 D0 首个 PR 率	反映标准化是否真的可用
CI 平均时长	直接影响前置时间

4.2 三条纪律（避免度量变味）

纪律	说明
度量系统，不度量个人	用"部署频率"评估团队流程，不用"个人提交数"评估工程师——后者必然导致刷量
先有基线，再谈改进	没有基线数字的"提升"无法证明（也容易被汇报包装）
指标要能被行动改变	如果某个数字无论怎么做都不动，它就不是指标，是噪音

4.3 度量陷阱

陷阱	表现	后果
用 LOC/提交数衡量产出	大提交、拆小提交刷数	代码质量下降
把"前置时间"算成"从提测开始"	数字好看，实际问题（等待评审）被藏起来	改进方向错
只测平均值	平均值掩盖长尾（P99 才是痛）	优化错对象
指标过多	20 个 dashboard 没人看	等于没有度量

推荐做法：1 个北极星 + 3 个辅助 + 季度复审。北极星建议用"变更前置时间"（它同时反映流程、自动化、协作）。

5. 一次完整的决策演练（把 S01 的内容串起来）

场景	用 ADR 记录什么	用度量验证什么
引入 `mvnw`	§2.1 的样例	构建一致率、CI 时长
上 devcontainer	环境方案对比（A01 §2）	D0 PR 率、环境工单占比
私服收口 + 阻断高危 CVE	供应链方案（A02）	CVE 追溯时长、构建失败率变化
文档站换 VitePress	平台方案（A03 §3）	搜索零结果率、构建时长、404 率

这张表的用法：任何一次工具链变更，左边写 ADR、右边留度量。半年后复盘时，你有一份"当初为什么"和"后来怎么样"的完整对照——这是团队最值钱的资产之一。

6. 验收条件（本系列方法论的验收）

#	验收项	判据
1	ADR 可查	仓库里有 `docs/adr/`，编号连续，最近 6 个月至少 3 篇
2	被否方案有记录	随机抽 1 篇，能看到 ≥2 个备选与原因
3	度量有基线	每个改进项都有"改前数字"
4	指标不过量	一个页面能看完（≤6 个）
5	有复审机制	ADR 有"复审日期"，到期会被重新打开

7. 自测（架构师版）

为什么"备选方案与被否原因"比"最终决策"更重要？
哪些决策不值得写 ADR？举两个例子。
DORA 四指标里，哪一个最能反映"工具链拖慢交付"？
用"个人提交数"做度量会发生什么？给出一个具体反例。
你的团队现在有基线数字吗？如果没有，第一个该测什么？

8. 系列收尾

S01 到此结束（24 篇）。下一篇进入 S02 · 计算机与网络基础（23 张旧卡），从"网络分层与 HTTP"开始，为后续 Java 后端与分布式系列打地基。

本篇属于系列《S01 · 开发环境与工具链》，架构师层第 4 篇。扩展点 E-S01-032/033。