凌晨三点监控告警把手机震得嗡嗡响。我爬起来看到内部数据处理管线连续重启三次而那一刻最让我后背发凉的不是故障本身而是我盯着修复界面居然想不起来这段代码是怎么工作的。它是我两周前用 vibe coding 快速堆出来的demo 跑通、联调也过了就顺手合并进了主干。结果等到真要修它、真有人问这个分支为什么存在的时候我面对的就是一个彻头彻尾的代码黑盒。我相信这不是我一个人的遭遇很多人正在经历同样的阶段依赖 AI 编码助手高效产出却发现自己对产出的理解能力没有同步跟上。这篇文章就写给所有在用 vibe coding 提效、但开始隐隐担心我到底提交了什么东西的开发同学也写给那些需要接手别人 vibe coding 产物的人。我会从判断黑盒、冻结基线、拆解黑盒、团队交接、流程约束五个角度把我在真实项目里的处理思路完整讲清楚。1. 先判断你手里到底是真黑盒、灰盒还是伪懂盒1.1 黑盒也有等级之分很多人把看不懂代码一刀切其实黑盒不都是一个性质。我习惯把它分成三档第一档是纯黑盒。你打开文件只有一堆函数和调用没有测试、没有注释、依赖关系一塌糊涂。团队里任何一个人看到这类代码的第一反应都是不敢动。这种黑盒通常出现在 AI 一次性生成了一大块功能、开发者又没做代码回读的场景里。它最危险因为故障发生时你连排查入口都找不到。第二档是灰盒。这其实是最常见的状态。你大体能看懂主流程若干调用关系也清楚但一旦涉及内部状态变化和异常分支你的理解和真实行为就开始分叉。典型的表现是代码的每个模块单看都合理合在一起却会在特定输入组合下做出预期之外的事。你说不清它为什么这样只知道它不该这样。第三档最迷惑我管它叫伪懂盒。你以为自己看懂了因为 AI 生成的主路径逻辑确实清晰变量命名也规范甚至你还能对着代码给别人讲一遍主流程。但等复杂输入、并发请求、边界异常一起涌上来真实行为和你的心理模型彻底脱节。你会产生一种很奇怪的反应——不是我不知道该怎么办而是我明明很懂它为什么它会这样。这种黑盒比前面两种更值得警惕因为它会给出可控的假象让你放弃对它的持续审视。我在某项目中就处理过一个典型场景一个用于线上策略排序的模块整份文件三百多行由 AI 一次性生成。那位开发同学告诉我我全看过了逻辑很顺结果这个模块跑了两周后开始出现同样的输入结果时好时坏。最终定位到的问题是模块内部早早在某个回调里修改了一个全局状态后续所有分支都基于这份被污染的状态做判断。这类问题靠通读主流程根本发现不了。1.2 半小时黑盒体检量化你的失控程度在决定怎么处理之前我建议先做一次黑盒体检控制时间在半小时左右。不需要精确到行级只需要摸清风险画像。我用的自查清单大概是这样的检查项具体做法典型风险信号依赖可见性列出全部直接依赖逐个确认来源出现大体积传递依赖且没有锁版本过长函数统计文件内函数行数分布超长函数占比高且内部存在嵌套逻辑可变状态边界搜索全局对象、缓存和单例同一个可变对象有多个写入点且没有临界区保护异常出口阅读 catch 分支的处理方式存在空 catch、无日志、吞异常但继续执行入参校验看对外入口方法/命令行入口大量接口参数没做校验就进入业务逻辑调用链深度从主入口追踪调用关系层数很深且有循环依赖或反向调用可回滚性看发布脚本和部署配置没有版本化发布线上被直接覆盖这套体检做完你基本知道自己手里是什么水平的黑盒了。如果是纯黑盒加高频变更处理优先级最高如果是伪懂盒但要上生产先把行为基线建起来再做增量修改。这里有一个很容易犯的错拿到 AI 生成代码后第一反应是重构想让它更规整。我建议你克制住这个冲动。在没有基线测试保护的时候重构黑盒本质是在改一台你不知道运行规则的机器大概率会改出新的隐性故障。2. 第一件事不是重构而是冻结行为基线2.1 先把入口和出口盘清处理黑盒我实际执行的顺序是先冻结行为再考虑优化。所谓冻结行为就是把当前代码在真实环境里表现出的输入输出关系固定下来作为后续所有修改的参照系。这个动作听上去简单做起来需要一点耐心。第一步盘点入口。你需要把代码暴露给外部的所有入口列出来命令行命令、HTTP 路径、消息队列消费者、定时调度任务、被其他模块直接 import 的函数。每找到一个入口记录它接收什么参数、依赖哪些环境变量、从哪里读写数据。这个环节的关键不在数量而在于完整性。漏掉一个隐藏入口后面所有测试都会给你错误的信心。第二步盘点出口。出口就是你能观察到的所有副作用数据库表的写入、缓存更新、文件输出、消息发送、返回值。注意返回值只是出口之一很多时候黑盒真正影响系统的是写到别处的数据。我记得有一次排查一个 AI 生成的批量处理任务代码本身没有报错返回值也正常结果它悄悄往一张共享表里插入了重复记录第二天数据质量告警才暴露问题。只看返回值根本发现不了。2.2 用数据锚点建立回归防线入口出口盘完之后立刻做数据级回归。做法很简单从生产环境取一组有代表性的历史输入把它们连同对应的输出结果一起保存下来作为回归样本。不需要追求覆盖率完美先保证你能回答一个问题我改了一天代码线上行为有没有变化我通常的做法是把这些输入输出做成一个独立的回归脚本固定在仓库里每次改动代码前跑一遍。比较对象可以是一份快照文件也可以是一个固定的校验值。这里有个细节样本数量不需要大但覆盖面要讲究。至少要包含正常输入、边界输入、已知异常输入三类。你不需要理解异常输入为什么会触发异常只需要知道它触发了怎样的结果这个结果就是锚点。2.3 把可观测性铺到关键路径上行为基线不只是测试还包括日志。黑盒之所以难排查是因为你无法从外部了解内部发生的事。所以我在冻结阶段会做一次只加日志、不改逻辑的改动。每个入口打上入参摘要每个关键分支打上出口标记每个副作用点打上写入摘要。这一步要特别注意不要在循环体内打日志不要在热点路径上打结构化日志。我踩过这个坑曾经把一条日志放在每秒调用几千次的函数里结果日志系统先被冲垮了业务倒是没出问题。正确做法是在关键节点采样或者用计数器聚合。你要的不是全量数据而是哪条路径被走了、停在了哪里。等日志铺完、回归脚本跑通你手里就有一份可以对照外部行为判断内部状态的观测镜。这时候黑盒还在但你已经不是瞎子了。3. 拆解黑盒的三个切入点输入输出契约、状态边界、可替换性3.1 给黑盒写一页纸的组件白皮书等基线稳定后我会开始给黑盒写白皮书。别一听文档就头大我要的不是几百页的接口规范而是能放进一页纸的组件行为说明。内容包括这个组件接受什么输入、返回什么输出、会产生哪些副作用、依赖哪些外部资源、有哪些已知的坑和例外。写白皮书的过程本身就是一种阅读理解。你会发现自己在追问很多之前回避的问题这个字段为空会怎样这个回调失败会走哪条分支这个缓存什么时候失效每一个问题暴露一处你此前没意识到的盲区。我自己的经验是一页纸写完黑盒的等级通常已经降了一档——从纯黑盒变成灰盒。这页纸不需要一次性写完整。你可以分批写今天写入口和返回值明天写状态变更后天写已知坑。关键是把它放在代码仓库里和代码一起维护。后续每次修改都同步更新白皮书防止它变成过期文档。3.2 状态边界是所有黑盒里最容易失控的部分代码里最危险的东西往往不是功能逻辑而是状态。我把状态分成两类看待一类是显式状态包括数据库表、缓存、本地文件、环境变量。这些东西写在代码里看得见排查时也能跟踪。另一类是隐式状态包括进程内存中的全局对象、单例缓存、闭包中共享的变量。这类状态最可怕因为它们在代码阅读时很难被发现只有在并发或异常场景下才会暴露。拆解状态边界我通常会回答四个问题谁在写这个状态如果发现同一个缓存被多个入口同时写入这是最大的警示信号。写入是否原子如果没有原子性并发来临时会出现最后一个写者覆盖前一个写者的问题。失败时能否恢复如果状态写入一半发生异常是否有补偿机制状态的生效范围是什么是进程内还是跨节点进程内状态在水平扩容时会出现各节点不一致的现象。这四个问题里任何一个回答得不清楚我都会把该状态当作高危项处理。处理方式不是立刻改架构而是在白皮书显著位置标注此状态存在多写点风险让后来者至少知道这里有雷。3.3 可替换性让黑盒不再绑架你的决策拆解黑盒的第三个切入点是可替换性。这个概念翻译成大白话就是如果明天这段代码坏了你能否在不改变外部调用方的前提下换一个实现版本如果你能做到黑盒的风险就被大幅稀释了。我测试可替换性的方法很朴素为黑盒构建一个行为等价物。它不需要性能相同也不需要实现相同的内部机制只需要满足白皮书记载的外部契约——同样的输入、同样的输出、同样的副作用。我在一个内部工具里给 AI 生成的解析模块做了这么个替换实验用一套完全手写的、逻辑简单的解析逻辑去替换它跑同一组回归样本对比结果。实验做完我并没有真的把这个手写版本上线但通过这个对比我确认了黑盒的核心契约是什么也确认了如果未来出问题我有能力绕开它。这个思路也可以反过来用。当你决定把一个模块交给 AI 生成时可以先自己定义好接口契约和验收测试再让 AI 去填实现。这样你手里拿到的就不是黑盒而是一个用契约拴住的实现。后面我会专门讲这个操作流程。4. 黑盒在团队交接时最危险无主代码的治理方法4.1 交接现场的黑盒事故黑盒的危害很少在创造者自己手里爆发它通常在团队交接那一下集中引爆。我亲眼见过一个案例一位同事用 AI 快速完成了某个数据清洗模块的初版代码合并后他就去休假了。两周后该模块所在链路上游的数据格式调整导致清洗结果全部偏差。接手的人打开那两百行代码注释全是 AI 生成的readConfig()式废话没有设计说明没有输入输出样例。更麻烦的是那位休假同事也没法提供任何背景——他自己提交完就忘得差不多了。这种局面我称之为无主代码。它比普通的技术债更可怕因为普通技术债至少有人还记得当初为什么这么做而无主代码连当初为什么都不存在。团队只能靠猜和试错来维护它效率极低。4.2 口述型注释把为什么钉在代码里面对这种情况我后来推行了一个很简单但有效的做法口述型注释。它和传统的注释不同只回答一个问题——这段代码为什么存在为什么不能换个写法。难度在于要把当时对话时才会讲出来的背景沉淀成文字。举例来说像这样的注释// 这里不能直接读最新配置因为配置刷新有1小时延迟读旧值会破坏幂等性。这就是口述型注释。相比之下AI 生成的注释往往是// 读取配置这种复读机式说明价值接近于零。我在项目里给团队立过一个规矩AI 生成的代码可以保留但合并前必须由人类补充至少三处口述型注释分别回答这个模块解决了什么问题这里为什么不走更常规的方案已知有哪些边界限制。不用多三处就够了。它逼着你至少在生成后为关键节点做一次主动思考同时也让未来接手的人不至于完全陷入真空。4.3 代码所有权必须落到具体人头上代码所有权不是一句空话。黑盒只有在有人认领的情况下才会被真正打开。我习惯在项目看板上给每个 AI 参与的模块显式标注代码责任人哪怕该责任人当前不理解模块的所有细节他也必须对持续理解这件事负责。这听上去像管理动作但在实践里很有用。责任人的存在会带来一个微妙的心理变化他开始觉得自己有义务拆掉黑盒而不是继续往里堆东西。有一些团队会担心代码所有权会拖慢节奏我的经验是恰恰相反。责任人会定期检查自己负责模块的行为白皮书是否过期会主动补测试会在代码评审时对自己的区域多花十分钟。这十分钟相当于为未来省下数小时的排障时间。团队评审时也要有针对 AI 产物的特殊关注项。普通评审看逻辑正确性黑盒评审要看这段代码的意图是否能被传记式地还原。我在 code review 环节会给评审者一个建议把自己当成三个月后第一次打开这份代码的人如果读完整份代码你能否给新同事讲清楚它的工作流程如果做不到那不是你水平的问题是代码本身的黑盒浓度过高了。5. 给 vibe coding 划边界五条铁律防止生产下一个黑盒5.1 铁律一分批生成以能整块回读为粒度上限不要一次性让 AI 生成一个完整的大功能。一次对话下来生成二百行以上几乎必然超出你的即时理解能力。我在实际操作中会把一个功能拆成若干小块每一块控制在五十到一百行之间每次生成后立刻回读确认自己理解再进入下一块。很多 AI 工具支持对话上下文持续累加但这种累加也意味着你会慢慢失去对早期内容的关注。分批生成是防止这个问题的第一道闸门。5.2 铁律二先定接口契约再让 AI 填实现这是前面提到过的方法论我对此的依赖度很高。一个模块开始编码之前先把接口契约写清楚输入参数是什么、输出是什么、在什么错误条件下抛什么异常、允许产生哪些副作用。这些内容可以用形如函数签名加注释的形式固定下来然后再交给 AI 生成内部实现。这么做的最大价值是无论 AI 生成的内部有多黑外部边界是你定的。你可以绕过对内部的完全理解通过测试来验证契约是否被满足。更妙的是如果未来要对 AI 实现进行替换只要契约不变替换成本极低。这也让黑盒从无法控制的失控代码变成带安全锁的实现细节。5.3 铁律三提交时强制附一段个人理解复述这是我最想推荐给所有人的一条纪律。每次提交包含 AI 代码的改动时在提交描述里用自然语言写一段总结大意是这段代码在做什么、它解决什么问题、我知道它的哪些限制。它不要求你逐行理解但要你用自己的话复述一遍核心行为。如果连这个复述都写不出来那就说明你不该提交。这个机制不是为了给别人看而是为了逼自己确认理解状态。我自己在实践里发现写这段复述的时间通常只需要两三分钟但它能极大提升后续排障速度。当你在一周后看到一条报错可以先读自己当时的复述快速重建上下文而不必重新打开整个黑盒。5.4 铁律四AI 生成代码也要走完整评审流程不少团队对 AI 产物存在审查豁免这是个危险的倾向。我的态度恰恰相反AI 生成的代码不仅不能免于评审反而需要额外的审查焦点。我加了一个黑盒评审环节专门回答三个问题这段代码的可测试性如何是否存在隐式状态写入如果出现故障日志能否帮我们快速定位这三个问题比逐行逻辑审查更实用。逐行审查很容易变成只在代码语法层面打转而这几个问题直接指向黑盒的本质风险。评审人员不需要理解每一行 AI 逻辑但需要确认它留下的可观测性和可测试性足够好。5.5 铁律五给反黑盒留出固定时间盒最后一条是关于节奏的。AI 提效会让人产生一种错觉产出越快剩余时间越多。实际上如果你不刻意安排时间去消化自己产出的东西黑盒累积的速度会快过你清理的速度。我采用的做法是每四个迭代周期安排一个反黑盒时间盒专门处理过去几周生成的 AI 代码补充白皮书、补测试、删掉无用分支、把长函数拆小。这个时间盒的产出并不显眼它不会带来新功能但它会持续降低整个项目的维护成本。我自己的体会是一个季度下来黑盒密度会明显下降团队对代码库的掌控感也会回来。这种掌控感带来的信心比再多新功能都值钱。根据我个人这几轮实操下来的体会vibe coding 不是原罪它只是一个速度放大器。如果你的流程足够清晰它能帮你把精力从打字挪到架构思考上如果你的流程放任黑盒累积它就会让技术债以指数级速度膨胀。我现在的习惯是每次收到 AI 生成的代码第一件事不是夸它跑得通而是问自己我是否愿意在三个月后为它负责。如果答案是犹豫那我会主动回到前面拆解五步里的某一步先把理解补上再继续。也建议你从今天这批代码开始给自己定一个最小目标每周处理一个黑盒模块写一页白皮书补一个回归测试。几个月后你回头看会发现这些动作带来的安心感远胜过所有短期提速。 
长河君 · 2026/10/26 20:25:08 · 阅读 1.2k Vibe Coding黑盒治理：从行为基线到团队交接的五步拆解法
凌晨三点监控告警把手机震得嗡嗡响。我爬起来看到内部数据处理管线连续重启三次而那一刻最让我后背发凉的不是故障本身而是我盯着修复界面居然想不起来这段代码是怎么工作的。它是我两周前用 vibe coding 快速堆出来的demo 跑通、联调也过了就顺手合并进了主干。结果等到真要修它、真有人问这个分支为什么存在的时候我面对的就是一个彻头彻尾的代码黑盒。我相信这不是我一个人的遭遇很多人正在经历同样的阶段依赖 AI 编码助手高效产出却发现自己对产出的理解能力没有同步跟上。这篇文章就写给所有在用 vibe coding 提效、但开始隐隐担心我到底提交了什么东西的开发同学也写给那些需要接手别人 vibe coding 产物的人。我会从判断黑盒、冻结基线、拆解黑盒、团队交接、流程约束五个角度把我在真实项目里的处理思路完整讲清楚。1. 先判断你手里到底是真黑盒、灰盒还是伪懂盒1.1 黑盒也有等级之分很多人把看不懂代码一刀切其实黑盒不都是一个性质。我习惯把它分成三档第一档是纯黑盒。你打开文件只有一堆函数和调用没有测试、没有注释、依赖关系一塌糊涂。团队里任何一个人看到这类代码的第一反应都是不敢动。这种黑盒通常出现在 AI 一次性生成了一大块功能、开发者又没做代码回读的场景里。它最危险因为故障发生时你连排查入口都找不到。第二档是灰盒。这其实是最常见的状态。你大体能看懂主流程若干调用关系也清楚但一旦涉及内部状态变化和异常分支你的理解和真实行为就开始分叉。典型的表现是代码的每个模块单看都合理合在一起却会在特定输入组合下做出预期之外的事。你说不清它为什么这样只知道它不该这样。第三档最迷惑我管它叫伪懂盒。你以为自己看懂了因为 AI 生成的主路径逻辑确实清晰变量命名也规范甚至你还能对着代码给别人讲一遍主流程。但等复杂输入、并发请求、边界异常一起涌上来真实行为和你的心理模型彻底脱节。你会产生一种很奇怪的反应——不是我不知道该怎么办而是我明明很懂它为什么它会这样。这种黑盒比前面两种更值得警惕因为它会给出可控的假象让你放弃对它的持续审视。我在某项目中就处理过一个典型场景一个用于线上策略排序的模块整份文件三百多行由 AI 一次性生成。那位开发同学告诉我我全看过了逻辑很顺结果这个模块跑了两周后开始出现同样的输入结果时好时坏。最终定位到的问题是模块内部早早在某个回调里修改了一个全局状态后续所有分支都基于这份被污染的状态做判断。这类问题靠通读主流程根本发现不了。1.2 半小时黑盒体检量化你的失控程度在决定怎么处理之前我建议先做一次黑盒体检控制时间在半小时左右。不需要精确到行级只需要摸清风险画像。我用的自查清单大概是这样的检查项具体做法典型风险信号依赖可见性列出全部直接依赖逐个确认来源出现大体积传递依赖且没有锁版本过长函数统计文件内函数行数分布超长函数占比高且内部存在嵌套逻辑可变状态边界搜索全局对象、缓存和单例同一个可变对象有多个写入点且没有临界区保护异常出口阅读 catch 分支的处理方式存在空 catch、无日志、吞异常但继续执行入参校验看对外入口方法/命令行入口大量接口参数没做校验就进入业务逻辑调用链深度从主入口追踪调用关系层数很深且有循环依赖或反向调用可回滚性看发布脚本和部署配置没有版本化发布线上被直接覆盖这套体检做完你基本知道自己手里是什么水平的黑盒了。如果是纯黑盒加高频变更处理优先级最高如果是伪懂盒但要上生产先把行为基线建起来再做增量修改。这里有一个很容易犯的错拿到 AI 生成代码后第一反应是重构想让它更规整。我建议你克制住这个冲动。在没有基线测试保护的时候重构黑盒本质是在改一台你不知道运行规则的机器大概率会改出新的隐性故障。2. 第一件事不是重构而是冻结行为基线2.1 先把入口和出口盘清处理黑盒我实际执行的顺序是先冻结行为再考虑优化。所谓冻结行为就是把当前代码在真实环境里表现出的输入输出关系固定下来作为后续所有修改的参照系。这个动作听上去简单做起来需要一点耐心。第一步盘点入口。你需要把代码暴露给外部的所有入口列出来命令行命令、HTTP 路径、消息队列消费者、定时调度任务、被其他模块直接 import 的函数。每找到一个入口记录它接收什么参数、依赖哪些环境变量、从哪里读写数据。这个环节的关键不在数量而在于完整性。漏掉一个隐藏入口后面所有测试都会给你错误的信心。第二步盘点出口。出口就是你能观察到的所有副作用数据库表的写入、缓存更新、文件输出、消息发送、返回值。注意返回值只是出口之一很多时候黑盒真正影响系统的是写到别处的数据。我记得有一次排查一个 AI 生成的批量处理任务代码本身没有报错返回值也正常结果它悄悄往一张共享表里插入了重复记录第二天数据质量告警才暴露问题。只看返回值根本发现不了。2.2 用数据锚点建立回归防线入口出口盘完之后立刻做数据级回归。做法很简单从生产环境取一组有代表性的历史输入把它们连同对应的输出结果一起保存下来作为回归样本。不需要追求覆盖率完美先保证你能回答一个问题我改了一天代码线上行为有没有变化我通常的做法是把这些输入输出做成一个独立的回归脚本固定在仓库里每次改动代码前跑一遍。比较对象可以是一份快照文件也可以是一个固定的校验值。这里有个细节样本数量不需要大但覆盖面要讲究。至少要包含正常输入、边界输入、已知异常输入三类。你不需要理解异常输入为什么会触发异常只需要知道它触发了怎样的结果这个结果就是锚点。2.3 把可观测性铺到关键路径上行为基线不只是测试还包括日志。黑盒之所以难排查是因为你无法从外部了解内部发生的事。所以我在冻结阶段会做一次只加日志、不改逻辑的改动。每个入口打上入参摘要每个关键分支打上出口标记每个副作用点打上写入摘要。这一步要特别注意不要在循环体内打日志不要在热点路径上打结构化日志。我踩过这个坑曾经把一条日志放在每秒调用几千次的函数里结果日志系统先被冲垮了业务倒是没出问题。正确做法是在关键节点采样或者用计数器聚合。你要的不是全量数据而是哪条路径被走了、停在了哪里。等日志铺完、回归脚本跑通你手里就有一份可以对照外部行为判断内部状态的观测镜。这时候黑盒还在但你已经不是瞎子了。3. 拆解黑盒的三个切入点输入输出契约、状态边界、可替换性3.1 给黑盒写一页纸的组件白皮书等基线稳定后我会开始给黑盒写白皮书。别一听文档就头大我要的不是几百页的接口规范而是能放进一页纸的组件行为说明。内容包括这个组件接受什么输入、返回什么输出、会产生哪些副作用、依赖哪些外部资源、有哪些已知的坑和例外。写白皮书的过程本身就是一种阅读理解。你会发现自己在追问很多之前回避的问题这个字段为空会怎样这个回调失败会走哪条分支这个缓存什么时候失效每一个问题暴露一处你此前没意识到的盲区。我自己的经验是一页纸写完黑盒的等级通常已经降了一档——从纯黑盒变成灰盒。这页纸不需要一次性写完整。你可以分批写今天写入口和返回值明天写状态变更后天写已知坑。关键是把它放在代码仓库里和代码一起维护。后续每次修改都同步更新白皮书防止它变成过期文档。3.2 状态边界是所有黑盒里最容易失控的部分代码里最危险的东西往往不是功能逻辑而是状态。我把状态分成两类看待一类是显式状态包括数据库表、缓存、本地文件、环境变量。这些东西写在代码里看得见排查时也能跟踪。另一类是隐式状态包括进程内存中的全局对象、单例缓存、闭包中共享的变量。这类状态最可怕因为它们在代码阅读时很难被发现只有在并发或异常场景下才会暴露。拆解状态边界我通常会回答四个问题谁在写这个状态如果发现同一个缓存被多个入口同时写入这是最大的警示信号。写入是否原子如果没有原子性并发来临时会出现最后一个写者覆盖前一个写者的问题。失败时能否恢复如果状态写入一半发生异常是否有补偿机制状态的生效范围是什么是进程内还是跨节点进程内状态在水平扩容时会出现各节点不一致的现象。这四个问题里任何一个回答得不清楚我都会把该状态当作高危项处理。处理方式不是立刻改架构而是在白皮书显著位置标注此状态存在多写点风险让后来者至少知道这里有雷。3.3 可替换性让黑盒不再绑架你的决策拆解黑盒的第三个切入点是可替换性。这个概念翻译成大白话就是如果明天这段代码坏了你能否在不改变外部调用方的前提下换一个实现版本如果你能做到黑盒的风险就被大幅稀释了。我测试可替换性的方法很朴素为黑盒构建一个行为等价物。它不需要性能相同也不需要实现相同的内部机制只需要满足白皮书记载的外部契约——同样的输入、同样的输出、同样的副作用。我在一个内部工具里给 AI 生成的解析模块做了这么个替换实验用一套完全手写的、逻辑简单的解析逻辑去替换它跑同一组回归样本对比结果。实验做完我并没有真的把这个手写版本上线但通过这个对比我确认了黑盒的核心契约是什么也确认了如果未来出问题我有能力绕开它。这个思路也可以反过来用。当你决定把一个模块交给 AI 生成时可以先自己定义好接口契约和验收测试再让 AI 去填实现。这样你手里拿到的就不是黑盒而是一个用契约拴住的实现。后面我会专门讲这个操作流程。4. 黑盒在团队交接时最危险无主代码的治理方法4.1 交接现场的黑盒事故黑盒的危害很少在创造者自己手里爆发它通常在团队交接那一下集中引爆。我亲眼见过一个案例一位同事用 AI 快速完成了某个数据清洗模块的初版代码合并后他就去休假了。两周后该模块所在链路上游的数据格式调整导致清洗结果全部偏差。接手的人打开那两百行代码注释全是 AI 生成的readConfig()式废话没有设计说明没有输入输出样例。更麻烦的是那位休假同事也没法提供任何背景——他自己提交完就忘得差不多了。这种局面我称之为无主代码。它比普通的技术债更可怕因为普通技术债至少有人还记得当初为什么这么做而无主代码连当初为什么都不存在。团队只能靠猜和试错来维护它效率极低。4.2 口述型注释把为什么钉在代码里面对这种情况我后来推行了一个很简单但有效的做法口述型注释。它和传统的注释不同只回答一个问题——这段代码为什么存在为什么不能换个写法。难度在于要把当时对话时才会讲出来的背景沉淀成文字。举例来说像这样的注释// 这里不能直接读最新配置因为配置刷新有1小时延迟读旧值会破坏幂等性。这就是口述型注释。相比之下AI 生成的注释往往是// 读取配置这种复读机式说明价值接近于零。我在项目里给团队立过一个规矩AI 生成的代码可以保留但合并前必须由人类补充至少三处口述型注释分别回答这个模块解决了什么问题这里为什么不走更常规的方案已知有哪些边界限制。不用多三处就够了。它逼着你至少在生成后为关键节点做一次主动思考同时也让未来接手的人不至于完全陷入真空。4.3 代码所有权必须落到具体人头上代码所有权不是一句空话。黑盒只有在有人认领的情况下才会被真正打开。我习惯在项目看板上给每个 AI 参与的模块显式标注代码责任人哪怕该责任人当前不理解模块的所有细节他也必须对持续理解这件事负责。这听上去像管理动作但在实践里很有用。责任人的存在会带来一个微妙的心理变化他开始觉得自己有义务拆掉黑盒而不是继续往里堆东西。有一些团队会担心代码所有权会拖慢节奏我的经验是恰恰相反。责任人会定期检查自己负责模块的行为白皮书是否过期会主动补测试会在代码评审时对自己的区域多花十分钟。这十分钟相当于为未来省下数小时的排障时间。团队评审时也要有针对 AI 产物的特殊关注项。普通评审看逻辑正确性黑盒评审要看这段代码的意图是否能被传记式地还原。我在 code review 环节会给评审者一个建议把自己当成三个月后第一次打开这份代码的人如果读完整份代码你能否给新同事讲清楚它的工作流程如果做不到那不是你水平的问题是代码本身的黑盒浓度过高了。5. 给 vibe coding 划边界五条铁律防止生产下一个黑盒5.1 铁律一分批生成以能整块回读为粒度上限不要一次性让 AI 生成一个完整的大功能。一次对话下来生成二百行以上几乎必然超出你的即时理解能力。我在实际操作中会把一个功能拆成若干小块每一块控制在五十到一百行之间每次生成后立刻回读确认自己理解再进入下一块。很多 AI 工具支持对话上下文持续累加但这种累加也意味着你会慢慢失去对早期内容的关注。分批生成是防止这个问题的第一道闸门。5.2 铁律二先定接口契约再让 AI 填实现这是前面提到过的方法论我对此的依赖度很高。一个模块开始编码之前先把接口契约写清楚输入参数是什么、输出是什么、在什么错误条件下抛什么异常、允许产生哪些副作用。这些内容可以用形如函数签名加注释的形式固定下来然后再交给 AI 生成内部实现。这么做的最大价值是无论 AI 生成的内部有多黑外部边界是你定的。你可以绕过对内部的完全理解通过测试来验证契约是否被满足。更妙的是如果未来要对 AI 实现进行替换只要契约不变替换成本极低。这也让黑盒从无法控制的失控代码变成带安全锁的实现细节。5.3 铁律三提交时强制附一段个人理解复述这是我最想推荐给所有人的一条纪律。每次提交包含 AI 代码的改动时在提交描述里用自然语言写一段总结大意是这段代码在做什么、它解决什么问题、我知道它的哪些限制。它不要求你逐行理解但要你用自己的话复述一遍核心行为。如果连这个复述都写不出来那就说明你不该提交。这个机制不是为了给别人看而是为了逼自己确认理解状态。我自己在实践里发现写这段复述的时间通常只需要两三分钟但它能极大提升后续排障速度。当你在一周后看到一条报错可以先读自己当时的复述快速重建上下文而不必重新打开整个黑盒。5.4 铁律四AI 生成代码也要走完整评审流程不少团队对 AI 产物存在审查豁免这是个危险的倾向。我的态度恰恰相反AI 生成的代码不仅不能免于评审反而需要额外的审查焦点。我加了一个黑盒评审环节专门回答三个问题这段代码的可测试性如何是否存在隐式状态写入如果出现故障日志能否帮我们快速定位这三个问题比逐行逻辑审查更实用。逐行审查很容易变成只在代码语法层面打转而这几个问题直接指向黑盒的本质风险。评审人员不需要理解每一行 AI 逻辑但需要确认它留下的可观测性和可测试性足够好。5.5 铁律五给反黑盒留出固定时间盒最后一条是关于节奏的。AI 提效会让人产生一种错觉产出越快剩余时间越多。实际上如果你不刻意安排时间去消化自己产出的东西黑盒累积的速度会快过你清理的速度。我采用的做法是每四个迭代周期安排一个反黑盒时间盒专门处理过去几周生成的 AI 代码补充白皮书、补测试、删掉无用分支、把长函数拆小。这个时间盒的产出并不显眼它不会带来新功能但它会持续降低整个项目的维护成本。我自己的体会是一个季度下来黑盒密度会明显下降团队对代码库的掌控感也会回来。这种掌控感带来的信心比再多新功能都值钱。根据我个人这几轮实操下来的体会vibe coding 不是原罪它只是一个速度放大器。如果你的流程足够清晰它能帮你把精力从打字挪到架构思考上如果你的流程放任黑盒累积它就会让技术债以指数级速度膨胀。我现在的习惯是每次收到 AI 生成的代码第一件事不是夸它跑得通而是问自己我是否愿意在三个月后为它负责。如果答案是犹豫那我会主动回到前面拆解五步里的某一步先把理解补上再继续。也建议你从今天这批代码开始给自己定一个最小目标每周处理一个黑盒模块写一页白皮书补一个回归测试。几个月后你回头看会发现这些动作带来的安心感远胜过所有短期提速。