# 把 AI 写的代码交给客户前，先读这本设计书

> John Ousterhout 用 196 页只讲一条纪律：用小接口藏住复杂性，因为你走后客户还要与代码共处。

原文: https://fdetimes.net/zh/books-courses/philosophy-of-software-design-ai-handover/

2025 年 4 月，John Ousterhout 在 [The Pragmatic Engineer 播客](https://newsletter.pragmaticengineer.com/p/the-philosophy-of-software-design)上把 AI 编程工具比作“战术龙卷风”（tactical tornado）：写代码快，修 bug 快，制造新 bug 和技术债也一样快。

对前线部署工程师（FDE）来说，这句话戳中了痛处。你用 AI 几天就搭好一个集成，然后交给客户的工程团队；你转去下一个项目后，读代码、改代码的是他们。

在同一期节目里，Ousterhout 提出，AI 编程的热潮可能让软件设计比以往更重要。他那本 196 页的 [A Philosophy of Software Design](https://i-programmer.info/book-watch-archive/14822-a-philosophy-of-software-design-2nd-ed-yaknyam-press-.html)，是学习这类设计最精炼的读物。

## 196 页，只对付一个敌人

第二版由 Yaknyam Press 于 2021 年 7 月出版，ISBN 978-1732102217。全书的核心是如何把复杂系统分解为模块，例如类和方法。Ousterhout 在接受 Software Engineering Radio 采访时说得很直白：软件能做成什么，唯一的限制就是复杂性。

他的定义很实用：复杂性是一切让项目难以理解、难以修改的东西。FDE 可以马上用上这个定义，因为“难理解、难修改”正是客户工程师打开你留下的代码仓库时的感受。

## 最该记住的是深模块

Ousterhout 把接口多、功能少的模块称为浅模块。深模块正好相反，用简单的接口隐藏复杂的功能。浅模块会让系统更混乱，因为使用者要花力气学习接口，回报却很少。

举个假设的例子。你让 AI 写一个从客户 CRM 拉取联系人的连接器，生成的版本有六个公开函数：获取 token、刷新 token、构造请求头、重试请求、读取下一页、规范化记录。客户工程师想用它，就得弄懂这六个函数以及正确的调用顺序。

深模块版本只暴露一个函数，比如 `fetch_contacts(since)`，认证、重试和分页都收在里面。接手的人要学的东西从六件减到一件。CRM 改了分页方式时，只需改一处，外部谁都不必知道。

所以在客户现场，合并 AI 生成的代码前，先数一数公开函数，问一问哪些是客户真正需要调用的，其余的收进内部。

## 团队里的战术龙卷风是谁？

Ousterhout 笔下的战术龙卷风，是那种不惜代价推动当天进度、不管对系统造成多大破坏的人。[freshman.tech 上的一篇本书总结](https://freshman.tech/philosophy-of-software-design-summary)指出，战术式编程是大多数公司的默认做法，目标是尽快让功能跑起来。

战略式编程则相反，愿意花时间找出既能用又最好的设计。

FDE 的工作天然把人推向战术式：演示就在下周，客户在等，Agent 几秒钟就能写出代码。当龙卷风是 AI 时，你就是团队里唯一的战略型工程师。有个习惯很容易坚持：每轮用 AI 生成代码之后，留出一小段时间只整理设计，不加新功能。

**要点:** 机器写代码比人快时，人的职责是让设计保持足够简单，让别人也能改得动。

## 注释是写给接手的人看的

第三个观点篇幅不长，但很有价值：注释应记录无法从代码中推断出的东西。客户工程师需要知道的是背后的理由：连接器为什么跳过没有邮箱地址的记录，是遗留系统的哪条约束逼出了这种做法。

这些理由只存在于你的脑子里和你与客户的会议中。交接那天之前不写下来，它们就会跟着你一起离开。

## 按什么顺序读？

时间紧的话，先听 [Software Engineering Radio 第 520 期](https://www.se-radio.net/2022/07/episode-520-john-ousterhout-on-a-philosophy-of-software-design/)（2022 年 7 月 12 日）。

这一期里，Jeff Doolittle 与 Ousterhout 聊了复杂性、模块化、分层、抽象和信息隐藏。接着听 2025 年 4 月那期 Pragmatic Engineer，了解他如何看待 AI 编程，最后再读书，优先读深模块和注释的章节。

如果你接手过别人的代码，这本书会为那种痛苦准确命名，这正是要早读它的原因。如果你刚入行，别跳过那些看似显而易见的观点：截止日期一逼近，最先被忘掉的就是它们。

找工作时，把这些观点变成证据。在简历或 FDE 面试中，讲一次你在交接前精简模块接口、之后客户团队无需找你就能自行修改的经历。这样具体的故事，远比一句泛泛的“写整洁的代码”有说服力。

2022 年 Ousterhout 在 SE Radio 上谈战术龙卷风时，它还是人类程序员。如今它就运行在你的 IDE 里，交接是干净还是一团乱，取决于掌舵的人。

**本周动手试试:**

- 打开 AI 最近为你写的模块，数一数公开函数，把客户无需直接调用的收进内部
- 买书之前先听 SE Radio 第 520 期，弄清哪些章节需要精读
- 在客户的代码仓库里添加三条注释，记下你们在会议上敲定的决策背后的原因

## 信源

- [A Philosophy of Software Design, 2nd Ed (Yaknyam Press )](https://i-programmer.info/book-watch-archive/14822-a-philosophy-of-software-design-2nd-ed-yaknyam-press-.html)

- [John Ousterhout on A Philosophy of Software Design (Software Engineering Radio episode 520)](https://wiki.tcl-lang.org/page/%7BJohn+Ousterhout+on+A+Philosophy+of+Software+Design%7D+%7BSoftware+Engineering+Radio%7D+%7Bepisode+520%7D+%7B2022+07+12%7D)

- [Book Summary: A Philosophy of Software Design](https://freshman.tech/philosophy-of-software-design-summary)

- [The Philosophy of Software Design – with John Ousterhout](https://newsletter.pragmaticengineer.com/p/the-philosophy-of-software-design)

- [SE Radio 520: John Ousterhout on A Philosophy of Software Design](https://www.se-radio.net/2022/07/episode-520-john-ousterhout-on-a-philosophy-of-software-design/)
