一、十二个工具装完之后shop团队开了一次自动化建设讨论会气氛很好。会上列出了一份清单格式化工具、静态检查、类型检查、接口契约测试、覆盖率统计、性能基准、依赖漏洞扫描、密钥扫描、提交信息检查、文档链接检查、数据库迁移检查、代码复杂度检查。理由是这些都是成熟工具装上只有好处。两天的接入工作之后仓库的 CI 从两分钟变成了十一分钟每次提交平均会触发三到五条不同的告警其中大部分是历史遗留问题有人开始说CI 太慢先跳过吧一个月后重活了一份检查被关掉理由写得很实在——“它一直在报老问题没人看了”。这个结局几乎是注定的和工具有没有用无关和接入的顺序有关。工具的价值等于它制止的错误减去它带来的成本。一次性装十二个等于把十二份成本同时压在一次提交上而每份收益都要等到真的有人去修才显现。两者时间上不对齐团队体验到的就只有成本。这一篇讲的是怎么选第一个用三个维度给候选工具排序——重复发生的错误、影响程度、可检测性——从最高分的一个开始装一个、用两周、再装下一个。二、先把几个词讲明白套件一组配合使用的工具。它不等于所有能装的东西而是一组有明确分工、覆盖主要风险的工具组合。门禁自动的、强制性的检查点——不通过就不让合并。门禁和提示的区别在于是否有阻断力没有阻断力的检查很快会被忽略。可检测性某类错误能不能被自动、稳定地发现。能就是高可检测性只能靠人看就是低可检测性。误报工具报了问题但实际不需要处理。误报率高的工具会让所有告警失去可信度。噪音不重要的告警和信息。噪音的问题不在多而在于它会淹没真正重要的信号——当一次提交里同时亮起十个提示时人只会全部忽略。接入成本把它跑起来需要的工作量写配置、改现有代码、加 CI 步骤、写文档。历史项目里改现有代码往往是大头。维护成本接完之后持续的花费规则更新、误报处理、依赖升级、以及每次运行的时间。信号密度一次检查里真正需要处理的问题占全部输出的比例。信号密度高的检查值得留在门禁里低的应该先降级成报告等清理干净再升级。三、为什么一次只装一个3.1 三个维度的排序逻辑候选工具之间怎么比较与其比较功能列表不如用三个维度给它们打分第一个维度是重复发生的错误这类问题在这个项目里出现得频繁吗如果同样的麻烦反复出现、每次都有人返工就可以算高频。第二个维度是影响程度出现之后代价有多大——只是评审时多花一点时间还是上线后才发现数据不对。第三个维度是可检测性这类问题能不能被自动、稳定地检测出来误报多不多。三个维度的乘积决定优先级高频 × 高影响 × 可检测 最值得先做。用乘积而不是加法是因为三个条件缺一不可只影响大但不常发生收益有限只频繁但影响小修不修都行频繁且影响大但检测不了装工具也没用。乘积会自然地把三项都相对不错的候选推到前面。3.2 为什么可检测性是最容易被忽略的一项前两项靠直觉就能填第三项常被跳过很多人选工具时想的是我想防住什么错误而不是这个工具能不能真的抓住它。可检测性差的表现有三种需要人读代码才能判断比如命名要统一检测结果不稳定同样的代码有时报有时不报误报太多需要人工二次确认比如某些模糊的安全扫描。可检测性差的规则并非没有价值但它不适合作为第一批。原因和门禁的机制有关门禁的力量来自结果可靠——一旦通过团队就默认这件事没问题。如果一条检查经常误报人会习惯性地忽略红灯而这个习惯会扩散到其他检查。第一批装的东西应当是从不误报、失败了就一定是问题的那一类。3.3 三类成本要提前算进去任何工具都有三类成本选型时最好显式写出来。接入成本配置、改遗留代码、加 CI 步骤。历史项目里最容易被低估的是改遗留代码——一个只在新增代码上生效的检查通常比全仓库立刻生效更容易落地因为它不需要你一次修复所有历史问题。运行成本每次提交要多等多久。这一项直接影响使用意愿检查如果明显拖慢提交跳过检查的诱惑就会上升。常见的折中是分级运行——提交时跑快检查合并前跑慢检查。维护成本规则更新、误报处理、依赖升级。这一项最隐蔽因为它在时间上分散一次误报要打断手头工作一次规则冲突要额外讨论加起来就成了这个工具很烦的印象。降低维护成本的方法之一是选择配置面小的工具默认规则能用的就不自定义需要维护的东西越少越好。3.4 一个具体的排序原则先修红色再防未来还有一个和排序有关的现实问题第一批工具应该先解决已经存在的问题还是防止未来出现的问题经验做法是先做能立刻变绿的那一类。比如一个能自动修复格式的工具接入之后仓库立刻干净CI 立刻能通过团队第一次体验到门禁是绿的而一个检出两百处历史问题的检查接入之后长期处于红色需要排期修复两边的体验完全不同。先用一个低成本、能立刻通过的工具建立习惯再逐步引入需要清理历史债务的工具成功率更高。这条原则也可以推广到检查粒度上先在新代码上生效再逐步覆盖历史代码。很多工具都支持这类范围控制按目录、按变更范围、按时间用起来比全量开关平滑得多。3.5 套件不是目录而是一条命令还有一个和形态有关的建议整套检查的入口最好收敛成一条命令。比如仓库里放一个脚本把格式检查、静态检查、测试按顺序跑一遍本地开发和 CI 都调用它。这条命令带来三个好处团队和人、代理只需要记住一个入口CI 与本地跑的是同一套检查不会出现本地过了、CI 不过新增检查时只需要改脚本一处文档和 CI 不需要跟着变。收敛成一条命令还有利于分级脚本可以支持快慢两档提交用快档、合并前用全量而调用方不需要知道两者的差异。这样一来“检查套件从一个工具箱变成了一条流水线入口稳定内部可以持续演进。对于使用自动化代理的团队这一点尤其重要——代理只需要知道运行这条命令、看退出码”而不必理解套件里每一项工具的细节。四、完整例子shop 项目的第一次选型4.1 列候选不列愿望团队先把想要的能力翻译成具体候选一共五个格式与静态检查ruff、类型检查对 Python 项目常见的选择是引入类型标注检查工具、接口契约测试校验响应结构符合约定、覆盖率门槛例如新增代码覆盖率不低于某个比例、依赖漏洞扫描。注意每个候选都要能落到一条可执行的命令上如果一条能力没有对应命令它就不属于这一轮选型。4.2 打分三个维度各用高、中、低三档然后相乘。下面是团队的打分示例具体结论依项目而定候选重复发生影响程度可检测性综合说明格式与静态检查高低高高几乎每次提交都有小问题影响小但自动修复容易接口契约测试中高高高出现过响应字段漂移失败信息明确依赖漏洞扫描低高中中影响大但不常发生告警需要人工判断覆盖率门槛中中中中数值容易催生为覆盖而覆盖需要配套断言质量检查类型检查历史代码中中中中历史代码报错多需先限定范围示例打分。两列高的组合把格式检查与契约测试同时推到了前面。接下来必须做一次取舍因为这一轮只装一个团队选了格式与静态检查。4.3 为什么先装格式与静态检查理由有三条都来自前面的原则。第一它能立刻变绿使用自动修复跑一遍仓库当场干净不需要排期修历史问题。第二它可检测性高格式化结果确定、误报极低失败信息直接指出文件与行。第三它运行快全仓库检查很快就能跑完放进每次提交不会引起等待焦虑。反过来说契约测试虽然影响更大但它需要先补齐契约定义哪些字段、哪些枚举这属于要排期的工作漏洞扫描的告警需要人工判断不适合作为第一批门禁。这两个不是被否决只是排到了后面。4.4 接入方式写清楚选定之后接入动作固定成三个部分写进任务单示例1. 命令ruff check . 与 ruff format --check . 2. 范围全仓库先跑一次自动修复把历史问题清掉 3. 门禁CI 在提交与合并请求更新时运行失败阻止合并 4. 记录AGENTS.md 的怎么验证段新增这两条命令 5. 回滚条件若出现无法在十分钟内定位的失败先降级为报告模式并记录原因第 5 条经常被省略却很重要任何检查都可能有意外版本升级带来的规则变化、误报提前写好降级条件可以避免要么全开、要么全关的极端处理。降级不是失败它是让检查留在体系里的方式——报告模式仍然产生证据只是不再阻断合并。4.5 两周后的观察接入两周后团队看了四个指标示例检查是否真的拦住过问题、平均运行时间、有没有出现需要手动干预的误报、以及有没有人提出跳过检查。四个指标的用法不同——第一个衡量收益后三个衡量成本。收益明显、成本可接受就进入下一步成本明显偏高比如运行时间过长、误报频繁先优化再考虑加第二个。这两周里最值得记录的是拦住过什么。一次具体的拦截比如某次提交因为格式问题被拦下、五分钟后修复比任何抽象收益都有说服力它也是下一次选型时最有力的材料——你能说清这个检查实际阻止了什么。4.6 第二个怎么选两周之后进入第二轮候选池里第一名的格式检查已经在线剩下的继续按同一套打分。这一次契约测试的分数最高原因和上次一样直观它有明确的失败信息、影响面大曾经出现过响应字段漂移而且补齐契约定义的工作量是可控的只覆盖最常用的三个接口。第二轮接入时多了一个动作把第一轮的观察结果写进决策记录为什么先装这个、为什么现在装第二个。这一步使用前面几篇的做法——决策和代码一起评审。三轮下来团队会得到一个有据可查的套件每一项工具都能回答为什么是它、为什么是现在。4.7 三种常见候选的排序建议如果不想从零打分可以参考三类工具的常见位置示例参考仍需按项目调整。格式与静态检查通常在第一批可检测性最高、接入成本最低、能立刻全绿。类型检查要看历史代码的状态新项目可以直接全量接入老项目建议先限定在新增与改动的文件上。契约与结构校验适合放在第二批它能防住接口悄悄变了这类影响面大的问题但需要先写清契约。覆盖率门槛建议靠后并且优先用新增代码的形态全量门槛会一次性制造大量历史债务而新增代码覆盖率通常更容易满足也更直接对应本次改动的质量。漏洞与密钥扫描的告警需要人工判断适合先以报告形式存在等清理到低噪声之后再考虑升级为门禁。这个建议的排序逻辑和前文一致先做能立刻变绿、失败信息明确、运行快的再做需要排期清理、需要人工判断的。顺序不是价值排序而是落地顺序——价值高的工具如果落地失败等于没装。4.8 一次失败的第一批长什么样同样值得记录的是一次失败案例示例另一个项目第一次选型时挑了完整测试套件 覆盖率门槛 性能基准三件一起装。三周后的状态是测试套件因为历史用例不稳定被标记为仅参考覆盖率门槛先是从某个比例下调后来干脆关掉性能基准因为环境差异每天产生两三条告警最后改成每周手动跑一次。三件工具都还在仓库里但没有一件在真正阻止问题。复盘时找出的原因有三条都很典型。第一候选选择基于想要什么而不是哪里出错三件工具对应的是质量、覆盖、性能三个愿望而不是具体的三次事故。第二可检测性被高估历史用例不稳定这件事在接入前就有迹象本地跑过两次结果不同但被当作以后再修。第三没有预留清理时间覆盖率从某个比例起步需要先修一批老用例而这项工作量没有进任何人的计划。这次失败后来转化成了三行经验写进了团队文档先装能立刻变绿的历史用例不稳定时先修稳定性再谈门槛任何需要先清理历史的检查必须先在计划里安排清理时间再谈接入。三行经验比任何工具介绍都有用因为它们来自一次真实的代价。4.9 把检查接成一条命令、两个档位接入的形态建议是一条命令、两个档位。示例脚本放在仓库里示例#!/usr/bin/env sh# scripts/check.sh —— fast 用于提交时full 用于合并前set-ecase$1infast)ruff check.;;full)ruff check.ruffformat--check.pytest-qtests/orders;;*)echousage: scripts/check.sh fast|full;exit2;;esac运行结果示例$ scripts/check.sh fast All checks passed! $ scripts/check.sh full All checks passed! All checks passed! 5 passed两个档位把提交要快、合并要全落成了两条具体命令。文档里写运行scripts/check.sh fastCI 也调用同一个脚本于是命令的单一事实源只有这一处新增一项检查时改脚本文档和流水线都不用动。这个形态还有一个附带好处它把套件从一堆工具名变成了一个稳定入口。新成员和代理只需要记住一条命令和退出码的含义不必逐项了解内部工具内部怎么演进——换工具、调档位、拆步骤——都不影响入口。五、反例与代价五种让工具变成负担的做法5.1 反例一一次性装全套做法开会列十二个工具一次性全部接入理由是早装早受益。它为什么看起来能行清单上的每一项确实都有价值而且很多工具配置一次就能长期使用。最后的代价是成本同时到达、收益分散到达。CI 从两分钟变到十一分钟每次提交亮起多条告警历史问题与新问题混在一起团队的体验是提交变难了而收益要在具体某次拦截之后才被感知。结果通常是两种一部分检查被关掉并且再也不会被打开或者所有人都学会绕过 CI 直接合并。前者是浪费后者更糟——它破坏了门禁的可信度让后面想认真加检查的人也难以推动。5.2 反例二按热门或者功能多来选做法挑社区里最流行的、功能覆盖最全的工具理由是别人都在用。它为什么看起来能行热门工具通常质量不错文档齐全遇到问题时也容易搜到答案。最后的代价是它和你项目的实际痛点不匹配。一个功能强大的工具可能主要解决你不常发生的问题而它带来的配置复杂度、运行时间、误报处理却每一样都要付。选型的起点应该是你自己的错误清单最近三个月出现过哪些问题、各出现几次而不是工具的排行榜。把错误清单写出来排序会自动给出答案出现次数最多、影响最大、又容易被检测的那一类对应的工具就是第一个。5.3 反例三装了却没人看告警做法工具接进 CI但告警以提示形式存在不阻断合并或者虽然阻断但失败信息里没有指向具体位置。它为什么看起来能行检查确实在跑记录里能看到结果形式上是有覆盖的。最后的代价是噪音化。当告警不阻断、也不指向具体位置时它就从信号变成了背景音几周之后没人会点开看。修复方式有两条把真正重要的检查升级为阻断并且保证它不误报以及在失败信息里给出定位文件、行号、失败断言、期望与实际。如果这两件事暂时做不到就先不要把它放进门禁而是放进每日报告等条件成熟再升级——放在门禁里却没人理比不装更糟因为它稀释了其他检查的可信度。5.4 反例四只加配置不清理历史做法接入全仓库检查立刻面对几百个历史告警决定慢慢修。它为什么看起来能行不修历史也能接入配置一提交就有了覆盖看起来是零成本启动。最后的代价是长期的红色状态。检查从第一天起就是失败的团队要么对失败麻木要么被迫在提交时加豁免标记——而豁免会越来越多直到检查名存实亡。更稳的做法是先限定范围新增代码、改动文件、指定目录把历史问题清单化并排期等清理到一定程度再扩大范围。范围控制不是妥协它是让检查从第一天起就是绿的的唯一现实方式而绿色状态是团队愿意继续投入的前提。5.5 反例五忽略运行时间做法所有检查都塞进每次提交运行时间从两分钟涨到十分钟以上。它为什么看起来能行跑得越全越安全多等几分钟不算什么。最后的代价是使用行为的改变。等待超过一定时长后人会开始一次提交多个改动、在等待期间切换任务、或者干脆跳过检查直接合并——这些都是等待太久的自然反应而不是纪律问题。修法是把检查分级提交时跑快检查格式、静态检查、受影响的测试合并前跑慢检查完整测试、契约校验、扫描。分级之后快速反馈保护了开发节奏慢检查仍然守住了合入质量。5.6 五种反例的共同点五种做法有一个共同特征它们都在预算之外做了决定。一次性装全套是忽略了运行与维护的预算按热门程度选是忽略了和自身痛点匹配这一层判断装了不看告警是忽略了人的注意力预算不清理历史是忽略了清理工作的时间预算不顾运行时长是忽略了开发节奏的预算。工具本身没有问题问题在于把它们当作配置动作而不是要长期运行的检查。按这个视角选型的前置问题就变成了一句很朴素的话这项检查打算占用多少预算用什么换回来能回答这个问题选型就不会一次装十二个回答不了装多少都会在几周内回到原样。5.7 一条容易被忽略的纪律先修一次再装还有一个细节能显著提高存活率接入某个检查之前先用它的报告模式跑一次看看输出里有多少真实问题和多少误报。这一步通常很快但它能提前回答两个关键问题——现在的问题是多还是少误报的比例能不能接受答案如果是问题很多、误报不少那这次的接入动作就不应该是加配置而应该是清理排期否则检查从第一天起就是红的。先跑一次还有一个附带收益你会拿到一份真实的问题清单。把它按目录、按类型归类往往能看出集中在哪几个模块——这可能直接影响范围的划定比如先只对订单模块启用。检查是给整个仓库装的但把它调成绿色通常需要理解它到底在报什么。这一次观察能省下后面反复的争论。5.8 一套组合动作选、装、看、留把这一篇的动作压成四个字选用三维打分选出第一个、装写清范围、门禁位置、回滚条件、看两周四个指标、留把拦截案例和决策理由记下来。四个字里最容易省掉的是看和留——装完就忙下一个工具结果既不知道它有没有用也没有材料支撑下一次选择。而这两件事的成本其实很低看是过一段时间后回看几个信号留是写一行决策记录。如果团队里有人问我们要不要也把某某工具装上这四个字就是一个现成的回答先看它在三个维度上的得分再算三类成本然后按选、装、看、留走一遍。流程固定下来之后工具数量的增加会变得克制而有据而不是开会时的灵光一现。第一个门禁装好之后你会发现自己对哪里容易出错的认识清晰了很多——下一轮的候选清单往往就是从这个认识里长出来的。这也解释了为什么第一个值得认真选它不只是多了一条检查它会改变团队对自动化的预期。一个跑得快、误报少、真的拦住过问题的检查会让后面每一次要不要加检查的讨论都容易得多反过来一个拖慢流程、经常误报的检查会让团队在很长时间里把自动化等同于麻烦。第一印象在工具这件事上同样成立。六、落地步骤选出第一个门禁第零步先记下现在的基线。写下两个数字当前 CI 从提交到出结果用多久本地跑一次测试用多久。为什么先记接入之后才知道新增了多少时间。没有基线时感觉变慢了和确实变慢了无法区分讨论只能停留在感受上。怎么检查把两个数字写在任务单开头两周后各对照一次。如果新增时间超过预期优先优化范围与档位而不是立刻拆掉检查。第一步列错误清单不列工具清单。回看最近两到三个月的问题评审里反复指出的、线上出过的、返工最多的。每一条写清出现次数和代价。为什么先做这一步因为选型的依据是你的项目在什么地方出错不是世界上有什么工具。怎么检查清单里每条都是具体事件而不是代码质量不高这类概括。第二步把错误翻译成可检测的信号。对每条错误问它能不能被自动发现如何发现如果发现不了标记为暂不处理。为什么必须翻译因为想防住什么和能防住什么是两件事选型要站在后者上。怎么检查每条可检测的错误都能写出一句当……时检查会报错。第三步用三维打分排序。重复发生、影响程度、可检测性各给高中低做乘法。为什么要写成表格因为排序争论通常发生在感觉层面而表格让分歧落在具体某一格上——你觉得影响是高还是中比我们该先装哪个更容易达成一致。怎么检查表格里每一格都有简短理由。第四步检查三类成本。给排在最前面的候选各写一行接入要做什么是否需要改历史代码、每次运行多久、需要维护什么规则、误报、依赖。为什么要单列因为成本决定它能不能活下来选择运行快、维护少的候选是把成功率放在收益之前。怎么检查接入动作能不能在一个下午完成运行时间能否控制在可接受范围。第五步接入并写清范围与回滚条件。命令、范围、门禁位置、失败信息要求、降级条件五件事一起写进任务单。为什么降级条件必须提前写因为意外总会发生版本升级、误报事先约定能避免关掉算了这种极端处理。怎么检查把配置给一个没参与的同事看他能不能复述出这五件事。第六步观察两周并记录四个指标。拦住过什么、平均运行时间、误报次数、是否有人提议跳过。为什么记录拦住过什么因为它是收益的唯一实证也是推动第二个工具的材料。怎么检查两周后能不能讲出至少一个具体拦截案例。第七步再选下一个并写下为什么。重复第 1 到第 6 步同时把为什么是这个、为什么是现在写成一行决策记录。为什么不跳过这一步因为套件的顺序本身就是项目知识——半年后有人问为什么先装格式检查而不是契约测试你需要一个能回答的地方。怎么检查每次新增工具都能在决策记录里找到对应条目。模板候选工具/检查名 重复发生高/中/低近三个月出现约 n 次 影响程度高/中/低具体代价 可检测性高/中/低误报情况、失败信息是否明确 综合排序乘积结果 接入成本改动范围、预计时间 运行成本每次提交增加的时长 维护成本规则/误报/依赖 范围全仓库 / 新增与改动 / 指定目录 门禁位置提交时 / 合并前 回滚条件什么情况下降级为报告七、常见问题问如果只能装一个应该装哪个多数项目的答案是格式与静态检查。原因不在于它最重要而在于它最容易活下来运行快、误报低、能自动修复、能立刻全绿。它带来的直接收益diff 干净、评审不再讨论空格也许不大但它建立的是门禁是可靠的这个前提——后面每个更复杂的检查都要靠这个前提才推得动。例外情况是如果你的项目已经全绿了那么第一个就选错误清单里分数最高的那个候选。问三个维度里哪个维度权重最高可检测性。理由和门禁的机制有关门禁的价值来自通过即放心一旦检查结果不可靠这个前提就崩了。影响程度排第二因为它决定收益重复发生排第三因为它最容易观察也最容易高估——很多经常发生的问题其实只是经常被提到实际代价很小。如果三档打分难以取舍可以先把可检测性作为硬性门槛可检测性为低的候选这一轮不谈。问历史项目里遗留问题很多怎么开始先用范围控制把检查变成绿色。三种常见范围只检查新增与改动的文件、只检查指定目录、或者先把历史问题用自动修复处理掉再全量接入。选哪种取决于问题的性质格式类可以一次性自动修复成本最低逻辑类比如类型错误建议先限定范围结构性类比如分层依赖需要先整理清单再排期。关键指标只有一个接入后的第一周检查是不是绿的——不是绿的说明范围还太大。问CI 已经很慢了还要加检查怎么办先做一次时间盘点把现有步骤按耗时排序看有没有可以并行、可以缓存、或者可以只在合并前运行的。很多项目在这一步就能腾出足够空间。然后遵守分级原则提交时只跑很快的检查合并前跑完整检查。最后再考虑这个检查值不值得占用这些时间——用它拦住过什么回答。如果它长期也不会拦住一次问题那它更应该留在报告里而不是门禁里。问误报多但看起来有价值的工具能不能装能装但不要装成门禁。装成报告模式不阻断合并、定期汇总设定一个清理周期比如每月看一次把真实的告警修掉把误报配置成基线。什么时候升级为门禁标准是最近一个月的告警里误报为零或接近零。这个标准听起来严格但它是保护整套门禁可信度的方式——一个频繁误报的检查会训练团队忽略红灯而那个习惯的转移成本远高于这条检查本身的收益。问怎么判断一个检查是不是值得留用两个问题过去一个季度它拦下过几次真实问题它每次运行花多长时间、需要多少人工判断第一个问题的答案如果为零检查应该降级或者移除第二个问题如果答案是每次都要人花不少时间判断检查应该优化失败信息或者调整范围直到不需要人工判断为止。定期比如每季度做一次这样的盘点可以让套件保持精简——套件变大是自然的保持精简需要主动维护。问Agent 写代码的场景下选型有什么不一样有两个差别。第一检查的收益更高人和代理都会犯的错检查一次就能挡住两类执行者而且代理不会因为忙而跳过——它按流程办事只要流程里写着。第二失败信息更重要代理修复问题依赖失败输出的质量包含文件、行号、期望与实际的失败信息能显著提升它的自修复成功率而模糊的报错会让它反复猜测。因此在这类场景里优先选择失败信息具体的检查比优先选择覆盖面广的检查更划算。问套件建到什么时候算够了当新增一个检查的边际收益明显低于它的运行与维护成本时就差不多了。一个可用的判断方式是看错误清单如果最近三个月的真实问题里没有任何一类能够被新检查挡住说明现有套件已经覆盖了主要风险。另一个信号是讨论的变化——如果团队讨论的焦点从要装什么工具转向怎么把某个规则写得更容易检查说明套件已经到位工具是手段规则才是内容。问如果团队在先装哪个上争论不下怎么办把争论转成两个具体动作。第一个动作是各自写错误清单谁主张先装某个工具就写清它要防的问题在最近三个月出现过几次、每次代价多大。两份清单摆在一起多数分歧会自然收敛——因为争论的往往是重要性而清单提供的是发生频率和代价。第二个动作是给候选各写一行成本接入多久、运行多久、维护什么。如果两轮下来仍然并列选成本更低的那一个先做——反正两个都要装先做容易的能更快建立信任。问工具装多了之后怎么定期做减法每季度做一次在役盘点对每个检查问三个问题过去一个季度拦截过几次真实问题平均运行时间是多少误报需要多少人工介入三问的答案会形成四类高拦截低成本的保留并前置放在提交阶段高拦截高成本的优化失败信息或者拆分范围低拦截低成本的可以保留在合并前阶段低拦截高成本的降级为报告或者移除。减法的价值不仅在节省时间更在于保护团队对红灯的敏感度——红灯太多的时候它就不再是红灯了。问怎么让新成员理解这套工具为什么存在给他们看错误清单而不是工具清单。做法是选一到两个历史问题讲清楚三件事当时发生了什么、代价是什么、现在哪个检查能挡住它。真实案例比任何解释都有效同时它也让新成员知道这些检查不是形式主义每一条都对应一次真实的代价。更进一步的做法是把错误清单本身放进仓库比如docs/quality-history.md每次新增检查时追加一条长期下来它就成了这套套件的说明书。问第一个检查要不要立刻设成必须通过才能合并要但前提是它稳定、且接入后是绿的。门禁的价值来自通过即放心一条长期红的检查会让这个前提失效。如果历史问题太多就先限定范围或者以报告模式运行等它连续一段时间保持绿色、误报接近零再升级成阻断。升级的判断标准可以写得很具体最近一个月的输出里没有需要人工判断的告警失败时能直接指向文件与行号。两条都满足就把它变成门禁还满足不了就继续留在报告模式不要急着让它拦人。问拦截案例记在哪里记在仓库里例如一个docs/quality-history.md一行一条日期、问题是什么、代价多大、现在由哪个检查挡住。放在仓库而不是聊天记录里是因为读它的时机恰好是有人问为什么要装这些检查的时候。这份记录还有第二个用途季度盘点时它是这个检查拦下过几次真实问题的依据。没有它盘点只能凭印象而印象通常偏向那些最近被讨论过的工具不是真正干活的那几个。问团队只有一两个人这套流程还用走吗用走但可以压到最简。错误清单写三条就够打分表不一定要画出来心里排序也行三类成本只写一行它会不会拖慢我。有三个动作不要省装一个、用两周、留一行决策理由。它们防的是同一个风险——装了之后没人用、也没人知道为什么装。人少的团队里这个风险其实更大因为忙起来就跳过检查没有人来提醒只有检查自己的成本足够低才留得住。问第一个检查装完之后多久装第二个等观察期结束、四个指标都看过之后再装。两周是一个实用的默认长度短于两周样本太少长于一个月容易拖成以后再说。不要因为顺手就提前加第二个。加检查的边际成本要在运行和告警上体现好几天才会显现而它在接入当天只表现为一次配置动作。等观察数据出来后第二轮的排序才有依据——这也是一次只装一个真正的含义。问候选里有个人人都说该装的工具但没有对应的错误记录怎么办放进待观察清单先不装。给它一个明确的触发条件如果它要防的问题在接下来的三个月里真的出现过一次就按三维打分把它纳入下一轮如果一次都没出现说明它防的是想象出来的风险。这条纪律听起来冷但它挡住的正是最常见的扩张方式——“以防万一”。这类工具的成本是确定的接入、运行、维护收益却可能永远不出现。把决定推迟到问题真的发生之后判断会容易得多那时你还有现成的案例支撑排序。八、动手练习与小结练习为你自己的项目选出第一个门禁这道练习的产出只有一份东西一张打分表和一个明确结论——第一个装什么、为什么是它。第一步写错误清单。回看最近两到三个月评审里反复被指出的问题、线上出过的问题、返工最多的问题。每条写清出现次数和代价多花了多少时间、影响了谁。清单控制在十条以内只写真实发生过的。第二步把清单翻译成可检测的信号。逐条问能不能自动发现用什么命令或者检查发现失败信息会包含什么翻不成可检测信号的条目移出本轮候选单独记录它们可能对应流程改进而不是工具。第三步给候选打分。三个维度各给高中低相乘排序同时在旁边写出每格的简短理由。做完之后前三名应该已经很清楚了。第四步给前三名各写三类成本接入要做什么、运行多久、维护什么。如果第一名在成本上明显偏高而第二名成本低得多、排序接近那么选择第二名通常是更稳的起点。第五步接入第一名并观察两周。写清命令、范围、门禁位置、回滚条件两周后记录四个指标拦住了什么、运行时长、误报次数、是否有人提议跳过。第六步写一行决策记录为什么选它、为什么是现在、什么情况下重新评估。这一行就是下一轮选型的起点。做完之后你得到的不是装了一个工具而是建立了一套可以重复的选型方法——第二轮、第三轮照做即可。小结选第一个门禁的方法可以压成三句话。第一从错误清单出发不从工具清单出发你的项目在什么地方出错决定你该装什么。第二用三个维度排序——重复发生、影响程度、可检测性——相乘选优其中可检测性是硬门槛因为它决定门禁可信不可信。第三把三类成本提前算清楚接入、运行、维护优先选择运行快、维护少、能立刻变绿的候选因为落地成功率比理论收益更重要。两个操作习惯值得带走接入时写明范围与回滚条件并用两周观察 四个指标验证效果每新增一个工具留一行决策记录说明为什么是它、为什么是现在。这两件事让套件从一堆配置变成有据可查的选择结果。和前后篇的关系这一篇处理的是工具选择的顺序问题也是这一组文章的收束——前面几篇分别处理了规则怎么写、怎么改、在哪一层落地、理由怎么保存这一篇回答的是从哪一项开始把规则变成自动检查。一个自然的继续是把每次拦截记录下来形成你自己的错误清单——那份清单会比任何工具列表都更能指导下一步。最后一张可以贴在墙上的清单选型四问 1. 这类问题最近三个月出现过几次 2. 出现一次要付出多大代价 3. 它能不能被稳定地自动检测误报少、信息准 4. 接入、运行、维护三项成本加起来能接受吗 落地四件 [ ] 范围全仓库 / 新增与改动 / 指定目录 [ ] 门禁位置提交时 / 合并前 [ ] 回滚条件什么情况下降级为报告 [ ] 观察指标拦截案例、时长、误报、跳过提议四个问题决定装什么四件事决定装得住。两者都做到第一个门禁大概率能长期活着而一个活着的检查价值远高于十个装上又关掉的。