为什么开发者一定要读官方文档

输出优先背后的隐性债务

我大学学的不是计算机科学。我拥有的是地球物理学的技术学士学位（B.Tech）。

我对软件的了解，都是通过阅读一点点建立起来的。文档、源代码、GitHub issues、最终不了了之的 RFC 讨论串、2014 年那些半对半错但能启发我思考的博客文章。没有参加过 bootcamp，也没有接受过系统化的课程训练。只有我、一个浏览器，以及那些真实的一手资料。

学习 Cloudflare Workers 时，我手边没有课程。只有 Workers 文档、Wrangler changelog，以及一个迫使我在凌晨一点排查的部署故障。关于 binding 配置的文档，我读了三遍，才弄明白为什么我的 KV namespace 无法解析。我还一路追查了一个始于 2022 年的 GitHub issue 讨论串，才理解 Wrangler 的某个行为——而这个行为根本没有出现在官方文档里。

我所知道的一切，就是这样学来的。不是来自摘要，而是耐心面对原始材料，直到某个瞬间豁然开朗。

而我正在看着这个过程逐渐消失。

我们称之为生产力

我反复看到的模式，不再是“我读了文档，但没看懂这一节”，而是“给我实现 X 的代码”。不再是“我顺着源代码追踪，发现了这种行为”，而是“这个函数是做什么的”。

现在，理解已经成了可选项。拿到结果就行。

我们改变的不只是寻找答案的方式，也改变了自己对目标的定义。过去的目标是理解，现在的目标是输出。而我们把这种转变称为效率。

你可以在完全不理解什么是 half-open 状态、也不知道它为什么存在的情况下，生成一套可以工作的 circuit breaker 实现。它在测试环境里运行正常。六周后，它在高负载下的某个特定边缘场景中失败，而你却无从下手，因为你从未建立起相应的心智模型。你得到了结论，却没有经历构建结论的过程。你知道“是什么”，却不知道“为什么”。

真正重要的，只有“为什么”。

阅读文档，会让你通过接触真实的一手材料建立心智模型——API 设计试图权衡的取舍、藏在一条差点被你跳过的脚注里的边缘场景，以及“是什么”背后的“为什么”。阅读复杂 RFC 时产生的困惑，正是学习发生的地方。理解是在这种阻力中建立起来的。

构建 Bookmark Brain 时——这是一个基于我自己 55,000 多条 X 书签打造的 RAG 系统——我必须真正理解 Cloudflare Vectorize 的底层工作原理，而不只是它表层的 API。包括 embedding dimensions、index behavior、query distance metrics，以及它们对 retrieval quality 意味着什么。我读了 HNSW 论文，也读了贴近源代码的相关文档。我在困惑中停留了足够长的时间，直到困惑转化为理解。

如今，这份理解已经成为生产系统的关键支撑。如果凌晨两点出了问题，我有一套心智模型可以依靠。

如果我只是不断输入 prompt，拼出一个能运行的 demo，那我最终拥有的也只会是一个 demo，而不是一个我能够分析和推理的系统。

代码库中的分化已经显现

谁还在阅读、谁已经不再阅读——正在形成的分界线就在这里。不是高级开发者与初级开发者之间的差异，也不是有经验者与初学者之间的差异。

这种分化会体现在 code review 中。读过 ORM 文档的开发者，三十秒内就能看出为什么某条查询会引发 N+1 问题。生成这段代码的开发者却看不出来，因为他从未建立起那套让你一眼识别问题的心智模型。

它也会体现在架构设计中。真正读过 Kafka 文档的开发者，确实理解 consumer group 的行为、partition assignment 和 offset management。当系统需要扩展时，这名开发者有知识可以依靠。而通过摘要学习 Kafka 的人，虽然掌握了相关词汇，底层却没有任何结构作为支撑。

这种分化在 debugging 时体现得最为残酷。Debugging 几乎完全取决于你的心智模型。没有心智模型，你就只是在不停修改，然后祈祷问题消失。

AI 无法掌控整个架构。它看不到贯穿整个代码库的全局图景。我亲眼见过一套由 AI 生成的 caching layer：交付时干干净净，通过了所有测试，却在三周后拖垮了生产环境。原因是，无论代码本身，还是合并代码的人，都没有理解当两个请求竞相让同一个 key 失效时会发生什么。这个问题必须由 human in the loop 来把握，而这需要心智模型。心智模型来自阅读，而不是不断输入 prompt。

我们在不知不觉中交换了什么

我见过开发者交付自己无法推理的 auth systems、自己解释不清的 caching layers，以及在失效前一直运行正常的 queue implementations。可一旦它们真的失效，开发者除了重新打开一个聊天窗口，便无计可施。

这不是工具的问题，而是阅读的问题。

同一种工具，交到两名开发者手里。一名开发者用它来理解——追问代码为什么有效、存在哪些取舍、在高负载下什么地方会出问题。另一名开发者用它来逃避理解——拿走输出、直接上线，然后继续下一项工作。六个月后，当系统需要变更时，两者会得到截然不同的结果。

分界线就在这里。关键不在于你是否使用 AI，而在于你是在用它帮助自己理解，还是用它逃避理解。

在我观察到的那些能够持续积累、不断成长的开发者中，进步最快的并不是行动速度最快的人，而是那些仍然坚持阅读的人。他们读真实的 changelog，读真实的 query planning 文档，在事情说不通时直接阅读真实的源代码。他们正在建立一种可以持续复利的心智模型，而这是输入 prompt 无法复制的。

那些停止阅读的人也在积累某种东西：对 API 表层的了解，以及产出结果的固定模式，只是底下缺乏结构性的理解。在系统需要改变之前，这个问题不会显现出来。

尤其对于自学成才的开发者

文档让自学成为了一条可行的道路。你可以阅读开源代码，可以查看 Stack Overflow 上那些带着时间戳、分歧和编辑记录的讨论串，从中看到人们的理解是如何演进的；还可以阅读工程师写下的博客文章，了解他们不仅做了什么，也了解为什么这么做。

这套课程依然存在。我现在仍然在使用它。只是不知道后来者中，还有多少人也在这样做。

我通过阅读那些令我困惑的内容，一直读到不再困惑，才构建出了今天的一切。这不是什么天赋，而是一种习惯。我每天都在看着开发者为了获得“自己正在前进得更快”的感觉而放弃这种习惯，却没有意识到，他们拿来交换的恰恰是那项真正的能力。

凌晨一点，你带着挫败感阅读文档，把同一节读了三遍，由此建立起来的心智模型，并不是对生产力征收的税。恰恰是它，让你在系统发生故障时变得不可替代。

跳过这个过程，也就跳过了思考。而在生产环境出现问题、你发现自己无从下手之前，你根本不会意识到自己曾经跳过了它。

AI 帮助我研究、组织并编辑了这篇文章。其中的论点、示例和观点都属于我。它们当中的任何错误，也同样属于我。

部分评论可能只对已登录的访客可见。登录后可查看全部评论。

如需采取进一步措施，你可以考虑屏蔽此人和/或举报滥用行为。