# 调试与归因层：当 AI 出错之后——冰山在水线下的部分

> **AI Harness Engineering 系列 · 第十篇** · 王海涛（公众号：Jia言Yi行 · GitHub：derekwang85 · 腾讯云 TVP / 架构师名人堂）

海明威在《午后之死》里提出过一个写作者的原则，后来被称作"冰山原则"：他说，"冰山运动之雄伟壮观，是因为它只有八分之一在水面上。"水面上的八分之一，是写出来的部分；水面下的七分之八，是从来不写、但读者能感受到的部分。

这一篇借用海明威的冰山，不是因为要讲写作，而是因为**调试一个（AI Native 代码）的事故，和读海明威的短篇是一模一样的心智活动**——水面上的东西，永远不是全部。

![00-intro.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/b0f2cadfd58556fbf2ed5eea1d70c219.jpg)

## 出错的时候，你看到的是八分之一

当一个 AI 干的活出了错，人类第一眼看到的永远是那个"现象"。

可能是提示词得到的反馈是废话，可能是生成的文件编译不过，可能是数字对不上，可能是接口超时。人打开日志，看到红色，看到报错，看到一行戳在脸上的 message，然后本能地问出那句最危险的话：**"这是哪里错了？"**

注意，这个问题本身就是陷阱。

因为它默认了"错"是个可以用鼠标点中的具体位置——一个函数、一行代码、一个字段。按照这个思考惯性，会顺着日志往下点，直到点到一个看起来可疑的地方，宣布"找到了"。可绝大多数时候，你能顺藤摸瓜的只是水面上的那八分之一。真正的根因，沉在水下。

## 三层冰山：现象、结构、设计

![01-three-layers.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/8fc22c891143ed8b52869bd31614ce08.jpg)

我们后来把"水面下"分成清晰的三层，每一层都对应一种解释"为什么错"的深度：

第一层是**现象层（L1）**。你直接看到的那个报错本身。它描述"发生了什么"，但它几乎从不解释"为什么"。"接口超时了"是 L1。"这个文件编译失败"是 L1。它们是冰山的尖。

第二层是**结构层（L2）**。在现象的后面，代码结构本身有没有问题。"接口超时"的 L2 可能是"这个服务没有设置超时配置，默认值小得离谱"。现象告诉你结果，结构告诉你布局有什么毛病。

第三层是**设计层（L3）**。再往深处，是整个方案的设计有没有问题。"服务没设超时"的设计问题，可能是"当初压根没把'另一个服务会慢'设计进方案里"——它不是一个字段的事，是一个假设的事。

这三层不是学术分类，它是一条硬性的排查门禁。我们把它写进了门禁里：**每个失败必须完成三层冰山分析，才能进入修复。** 而且有一条写死的规定，直戳人心——

**禁止把"数据问题"当成根因。**

“数据问题“，这四个字是无数调试事故的藏身之所。你会看到很多团队，追了三天，最后得出结论"哦，是数据不对"。这个结论看起来无懈可击，其实它只是把 L1 的"现象"换了个说法，重新报了一遍。数据为什么不对？是上游喂错了，还是校验漏了，还是格式约定不一致？每一个"数据问题"的背后，都藏着一层结构问题和一层设计问题。允许"数据问题"当根因，等于允许自己永远停在冰山水面上的那一层。

不过，"愿意往下钻"只是第一课。真正的凶险，往往发生在你以为"根因已经找到、可以动手了"的那一秒——因为大多数涉及 AI Coding的编码问题，因为缺乏人手搓过程中的“故事性”，往往很难产生横向关联，所以，真正的不好用，不是在于没找到根因，而是把信息和耐心耗光在了"改对了这一处，却惊动了别处"。

## 改 A 之前，先想 BCDE

![02-ripple.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/aa6716ee75bc08e41a030d31c6df633d.jpg)

找到根因还不够，因为工程往往具有非孤立事件的关联关系，事故之所以是"事故"，常常不是因为一处错，而是因为**改了一处，引爆了别处**。

这是我们踩得最深的坑之一。早期我们修 bug，经常是"头疼医头，脚疼医脚"。改了字段，包了解出来了，回测也过了。结果过了几天，另一个毫不相关的模块开始报错。查了半天，发现是上次那个"修好了"的改动，悄悄影响了一个没人想到的角落。

于是有了一个听上去像废话、做起来却反人性的规矩：**改 A 之前，先想 BCDE。**

我们把它做成了一套叫"涟漪分析"的机制。要改任何一个地方，先自动扫描它的影响面——直接依赖、间接依赖、被谁引用、谁引用它。然后按"涟漪"的远近分级级联回归：

- 改得很浅、影响只在一个文件内的，做最内层回归；
- 影响波及到相关模块的，次一层回归；
- 往上传导到整条链路的，再往外一层；
- 一旦改动动了约定、契约、接口，直接触发**全量回归**。

这套 R0 到 R4 的四级级联，目的只有一个：让"我改的这个 A"，在还没上线之前，先把可能被波及的 B、C、D、E 全部想一遍、测一遍。改一行，牵着十行，那不是效率低，那是对的。

## 一个修对了一半的 bug：Round 3

![03-half-fixed.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/846fada699aae685a6847ce115b21d3d.jpg)

说一个真实的、让我印象极深的例子。有个 bug，追了三轮。

第一轮：Agent 看到报错，判断是字段解包不对，改了，回测没完全过。

第二轮：Agent 仔细看，发现字段和解包其实都对了，是**另一个微服务的接口超时**——它已经碰到结构层了，但还没到底。

第三轮：真正的问题浮现——超时的根因，是那个远程调用**压根没配超时参数**，默认值太小，慢一点就崩。到了这一步，光靠自动修复已经处理不了了，因为它牵扯到一个"要不要给依赖方加配置"的跨服务决策。于是触发了 HITL——人工介入，人类来拍板：加超时配置。

这个经历，我想分享的，不是 Agent 聪明，而是**它差一点就在第一轮宣布"修好了"**。如果没有三层冰山逼它往下钻，如果没有涟漪回归逼它把影响面看清，它会在假根因上停下来，然后留下一颗定时炸弹。而绝大多数团队，恰恰停在了第一轮。

所以哪怕对AI Agent来说，调试编码问题也绝对是个技术活，这门手艺，练的不是"多快找到一个错误"，而是"愿不愿意把水下的那七分之八也看完"。**停在表面的诊断只是止痛，钻到根因的修复才是根治——你可以骗过同事，甚至骗过自己，但事故从不讲人情。**所以，要立规矩，要建制度。

![04-traceability.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/ea51d7285d2e630a6aab32896dd069dc.jpg)

## 历史解决方案的检索

这套"三层冰山 + 涟漪回归 + 归因沉淀"的完整循环，在 derekinside 里有一个最朴素、也最有说服力的落点：**历史解决方案的检索**。

回想一下第 9 篇我们在讲记忆——记忆不是拿来'看起来丰富'的，记忆是为了让归因不再从零开始。当一个新的 issue 进来，Worker 第一时间不是埋头分析，而是先去 derekinside 检索：**以前有没有处理过同类问题？** 如果有，直接取出当年的 solution，看当年怎么定性的、怎么修的、留了什么备注。

这让"归因"从一次次重复劳动，变成了越用越快的递进。同类 bug 第一次处理要一小时，第二次十分钟，第三次可能看一眼就能定位。记忆的最终价值，不是让你记得更多，是让你**归因得更快、更准**。

## 矫枉不一定过正

![05-anti-pattern.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/4553793abc6c15ca197be965145759a7.jpg)

"三层冰山"和"涟漪回归"的名字太好听了，好听到容易让人滥用。

不是每个 bug 都值得做完整的三层冰山分析。一个拼写错误、一个固定文案写错、一个显而易见的笔误，你要它"分析设计层根因"，那不是严谨，那是折腾。过度归因的系统，会像过度招投标的公司一样，被自己的流程拖到动弹不得。

判断题只有一条：**这个现象，停在这一层，会不会卷土重来？** 如果改了 L1 就永不再犯，那它就是 L1 该解的问题；如果改了 L1 下个月换个姿势又来了，那它才配得上往下钻一层。冰山的价值，是提醒你别只看表面，不是逼你对每一个涟漪都做潜入深海。

## 第一天就能用的清单

![06-checklist.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/3bcb35ec375b8b5fea381733310e9d0a.jpg)

1. 把"这是哪里错了"改成"这是哪一层错了"。先问自己是现象、结构，还是设计。
2. 禁止用"数据问题"当根因。数据不对，就去追数据为什么不对。
3. 改任何东西之前，先问一句"改了 A，会不会影响 BCDE"。影响面不清，不动手。
4. 给关键改动配涟漪回归：改得越深，回归范围越大，动了约定就全量回归。
5. 让每次归因可追溯：commit 带推理链，Issue 三权分立，别让结论孤零零地躺着。

## 下一篇预告

归因归到了，修也修对了，可系统还是不会自动变好。真正让一个 AI 体系"越跑越强"的，不是会修 bug，而是会**把修过的 bug 沉淀成下一次不再犯的能力**。下一篇，我们讲系列里最硬核的一篇：**测试与自成长层**——一次性验证跑 10 秒，是怎么变成 6 个套件 50 条场景的自动护城河的。

---

AI Harness Engineering 系列 · 第十篇 · 王海涛（公众号：Jia言Yi行 · GitHub：derekwang85 · 腾讯云 TVP / 架构师名人堂）

驾驭 AI · AI Harness Engineering ·冰山假设

海明威在《午后之死》里提出过一个写作者的原则，后来被称作"冰山原则"：他说，"冰山运动之雄伟壮观，是因为它只有八分之一在水面上。"水面上的八分之一，是写出来的部分；水面下的七分之八，是从来不写、但读者能感受到的部分。借用海明威的冰山，是因为调试一个（AI Native 代码）的事故，和读海明威的短篇是一模一样的心智活动——水面上的东西，永远不是全部。

 CTO

人工智能

职业发展

架构设计

三层冰山+涟漪回归+归因沉淀，AI错误调试从现象钻到设计根因，禁止数据问题搪塞，改A先想BCDE，历史方案加速定位，记忆沉淀让修复更快更准。

GitHub

Agent

2026上云采购 | AI焕新·智启新局

coding

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

驾驭 AI · AI Harness Engineering ·冰山假设-腾讯云开发者社区-腾讯云

驾驭 AI · AI Harness Engineering ·冰山假设

驾驭 AI · AI Harness Engineering ·冰山假设

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐