写完三卷 AI 编程书后我发现:99% 的＂bug＂其实是...

AI编程三卷书 v1.0 发布后的第一篇深度文 · 关于「源码核实」是什么意思

写在前面

市面上的 AI 编程教程，绝大多数都是抄出来的。

抄什么？抄官方 README、抄 changelog、抄别人的博客、抄 ChatGPT 给的总结。

我做这本书的时候，本来也想抄。因为快——一周内能抄出 10 万字。但抄到第三章我停下来了。

原因很现实：几乎每抄一段，我都发现跟实际工具行为对不上。

文档说 A，工具实际做 B，社区博客说 C，ChatGPT 总结说 D。四份说法没有一份能跟我自己跑出来的结果对上。

那一刻我决定换路线：从抄文档改为读源码。这本书的整体节奏从此变慢了 5 倍，但价值翻了不止 5 倍。

下面这一篇，把我整本书最核心的"源码核实方法论"完整讲一遍——配一个真实的案例。读完你会知道为什么 AI 编程不能再靠"换个 prompt 再试一次"了。

一、为什么必须读源码

我先给你看一组反差。

我整理三卷书第二卷《工作流》的过程中，每一个我以为是「bug」的 AI 工具行为，最后都被源码追踪证明：

不是 bug，是行为变了，文档没更新。

具体来说，31 个深度陷阱里：

17 个
是工具升级后行为静默改了，文档慢了 1-3 个月才追上
9 个
是社区流传的"hack"——其实根本不存在那个配置项
5 个
是用户自己理解错了 prompt / context / agent 之间的关系
0 个
真的是工具 bug

0。

这个比例让我重新思考"AI 编程"这个领域的认知结构：

你以为	真相
AI 工具不稳定，老出 bug	工具其实很稳，是文档慢了
换个 prompt 就好了	行为已经改了，prompt 换 100 次都没用
这个工具差 / 那个工具好	你只是没看到它们各自的真实行为模型
ChatGPT 帮我总结一下吧	ChatGPT 训练截止时这个工具行为还是上一代

唯一靠谱的真相来源——源码。

源码不会骗你。文档可能落后，issue 可能误判，博客可能道听途说，git log 不会。

二、5 步源码诊断法

写完 31 个陷阱后，我把每次的排查过程提炼成一个可复用的诊断套路。这是这本书第二卷的核心框架。

任何时候 AI 工具行为反常，按这 5 步走：

第 1 步 · 症状采集

不要写"它失败了"。记录确切的、可复现的现象：

完整命令（含所有参数 / 标志）
触发条件（什么时候开始出错的）
错误输出全文（不要省略，省略的部分往往最关键）
重试 N 次的结果（每次都一样？还是随机？）

这一步看起来无聊，但80% 的人在这里就跳过——直接进入"猜测 + 重试"循环。这就是为什么大多数 AI 编程问题排查不了。

第 2 步 · 文档对照

打开工具官方文档，逐字对照你看到的行为：

官方说"会自动 X"——你的实测是不是真的自动 X？
官方说"不会做 Y"——你看到的是不是 Y？
文档版本号跟你装的版本号一致吗？（这一点 90% 的人会忽略）

文档跟现象对不上 → 进入第 3 步。

第 3 步 · 误判收集

去 GitHub Issues / Reddit / V2EX / Twitter 搜你看到的现象。

收集 4-5 种流行的解释——重点是找出它们互相矛盾的地方：

有人说原因是 A，有人说是 B
有人说要改配置 X，有人说改配置 Y
有人 swear 这个 hack 管用，有人说完全不管用

矛盾点 = 真相不在表面。这一步明确告诉你：社区也没搞清楚，必须自己读源码。

第 4 步 · 源码追踪

这是最慢、也最值钱的一步。

打开工具的 GitHub repo，按这个顺序找：

entry point
— 你的命令最终调到哪个文件 / 函数
dispatch 路径
— 这个函数往下又调用谁
关键决策点
— 在哪一行做了"是否 X"的判断
环境依赖
— 这个决策依赖哪些环境变量 / 配置 / 状态

通常 1-3 小时能追完。关键不是追多深，是追到「决策点」——找到那个 if (condition) { do_A() } else { do_B() }，你就赢了。

第 5 步 · git log 时间线

找到决策点后，看这一行 / 这个函数的 git blame：

什么时候改的
？
改之前是什么逻辑？
commit message 怎么说？

这一步通常解释为什么文档没更新——改动是个内部 PR，commit message 一句"refactor sandbox handling"，根本没意识到这是个 breaking change。

5 步走完，真相通常跟所有社区讨论都不一样，但可以解释所有现象。

三、一个真实案例（节选自卷二第 5 章）

让我用一个具体陷阱演示这套方法。

症状：用 Codex CLI --full-auto 跑长任务，90% 的命令一气呵成，10% 卡在中间等确认。社区把这个叫"Codex CLI 的 --full-auto 是 bug"。

5 步走完之后我发现：

不是 bug。--full-auto 的语义在 2025 年某个版本悄悄变了——从"任何情况都不问"改成"在 sandbox 内不问，sandbox 外照样问"。文档版本号跟代码版本号脱节了 2 个月。

最干净的修复不是"再试一次"，也不是"换个 prompt"，是显式开启 sandbox mode。这是社区流行的 4 种"修法"里没有人提到的那一种——因为前面那些人都没读源码。

完整 6 轮源码追踪过程（哪个文件 / 哪个函数 / 哪段 commit / 怎么交叉印证）在三卷书第二卷《工作流》第 5 章，约 4000 字。这里只展示方法论。

这种案例，整本书第二卷里有 31 个。每一个都按上面 5 步走完。

四、《AI 编程实战三卷书》v1.0 已发布

如果上面这套方法论对你有启发，欢迎完整读三卷书：

📖 在线阅读

https://book.aibuzhiyu.com/ —— CDN 加速 mdbook 完整在线版

📥 PDF 下载 + GitHub

github.com/jnMetaCode/ai-coding-trilogy —— 三卷分卷 PDF，CC BY-NC-SA 4.0 协议

🌐 完整内容矩阵

aibuzhiyu.com —— 10 工具 / 28 章 / 31 陷阱 / 215 专家角色 / 6 开源仓 (10k+ ⭐)

三卷分别给谁

卷	适合谁	看完能做什么
卷一 · 入门	AI 编程零基础 / 只用过 Tab 补全	4 款主流工具任选其一独立完成日常任务
卷二 · 工作流	已经会用 1-2 款工具，想把效率往上拔	多工具组合 / 31 个陷阱排雷 / 端到端实战剧本
卷三 · 架构	团队 lead / 平台工程师 / CTO	CI 接入 / 安全策略 / MCP 生态选型

写在最后

我做这本书不是为了卖。

永久免费——CC BY-NC-SA 4.0 允许个人 / 公司内部学习 / 团队培训 / 课堂使用，禁止贩卖。

如果它真的帮到你，麻烦在以下任一地方留个痕：

⭐ GitHub 给 ai-coding-trilogy 一个 star（让算法多推给其他人）
💬 朋友圈或群里转发这篇——尤其是身边那种**"AI 工具试了一圈感觉都怪怪的"的朋友**
📨 关注公众号 「AI 不止语」 回复 群 进读者群

工具会过时，方法论不会。

读源码，做核实，永久免费——给真心想用 AI 把活儿干好的人。

📖 在线读 : book.aibuzhiyu.com 🌐 官网 : aibuzhiyu.com ⭐ GitHub : ai-coding-trilogy