文档驱动开发的复兴
文档的历史性失败
文档是软件工程中最没人管的东西，根本原因是写文档的成本眼前就得付，好处却要很久以后才能感受到。写的人付出时间，读的人获得效率，而这两拨人往往不是同一群。这种激励不对称的结果可想而知：在交付压力下，文档总是第一个被牺牲的环节。
LLM 改变了这个博弈结构。文档不再只是给未来的人类读者准备的——它同时是 AI 编程助手的上下文输入。写文档的人现在能立刻受益——好文档直接提升 AI 辅助质量，收益当场兑现。以前写文档是为别人，现在写文档直接利好自己。
双重读者：文档的新身份
一份好的技术文档历来需要满足人类读者的需求：概念解释清晰、结构层次分明、示例恰到好处。在 LLM 时代，文档多了第二个读者——AI。两个读者的需求大部分重合，但有几处不同。
重合的需求。 结构化程度高、概念定义精确、上下文自包含——这些特征对人和 AI 同样重要。一份人读不懂的文档，AI 同样无法从中提取有效信息。
AI 特有的需求。 类型注解对人来说是辅助信息，对 AI 来说是高优先级的约束信号。命名不够精确时，人可以靠上下文猜出意思，对 AI 来说直接影响生成质量。跨文件的引用关系对人来说可以靠记忆串联，对 AI 来说需要显式声明。
双重身份意味着：为 LLM 时代写的文档，本质上就是把好文档的标准抬高了。那些"人能看懂但不够精确"的文档在过去是可以接受的，在 LLM 时代则成为 AI 辅助质量的瓶颈。
文档质量决定 AI 辅助质量
这是一个可以直接观测的因果链。
类型注解是最高密度的文档。 def query(q: str) -> Any 告诉 AI 的信息接近于零——输入是某种字符串，输出是任何东西。def search_products(query: ProductQuery) -> SearchResult[Product] 告诉 AI 的信息量则是结构性的：输入有明确的 schema，输出有明确的泛型结构。AI 拿后者生成的调用代码、错误处理、测试用例，和拿前者生成的，质量完全不可同日而语。
第四章讨论的类型系统作为契约，在这里有一个额外的维度：类型既是运行时的契约，更是 AI 理解代码意图的最有效信号。LLM 时代，类型注解的回报远比以前大——不光人能读懂，AI 也能读懂你的意图。
文档字符串是语义层的上下文。 类型注解告诉 AI 结构是什么，文档字符串告诉 AI 意图是什么。一个函数的类型签名可能在结构上完全正确，但如果没有文档字符串解释业务含义，AI 在生成调用这个函数的代码时就缺少了关键的语义信息。
项目级文档是全局约束。 单个文件的注释和类型注解提供局部上下文，项目级的 README、架构文档、编码规范提供全局上下文。AI 有了全局上下文，生成的代码，会自动遵循项目的惯例和设计模式；没有全局上下文时，AI 只能依赖通用的编程常识，生成的代码可能在技术上正确但在风格上格格不入。
CLAUDE.md：一种新的规格说明形态
CLAUDE.md 这类项目级指引文件代表了一种新的文档形态——面向 AI 的系统规格说明，区别于传统的 README（面向人类的项目介绍）和 API 文档（面向开发者的接口说明）。
本项目的 CLAUDE.md 是一个典型案例。它包含的信息类型：
- 项目的定位和边界（AI 需要知道这是什么项目才能做出合理的决策）
- 写作风格和技术倾向（AI 需要知道应该生成什么风格的内容）
- 文件命名和结构约定（AI 需要知道生成的文件应该放在哪里、怎么命名）
- 质量标准（AI 需要知道什么样的输出是可接受的）
这些信息在传统的软件项目中通常是隐性知识——存在于团队成员的头脑中，通过口口相传和代码审查来传递。CLAUDE.md 迫使这些隐性知识显性化，这才是它的价值。这个显性化过程的受益者不仅是 AI，也包括新加入团队的人类成员——把这些默会的规矩写出来，对任何新加入的成员（无论是人还是 AI）都有用。
由此产生一个有趣的反馈回路：为了让 AI 更好地理解项目，团队投入精力编写 CLAUDE.md；编写过程迫使团队梳理和明确化那些原本模糊的约定；明确化的约定提升了人类成员之间的协作效率。AI 是催化剂，但最终受益的是整个开发过程。
文档与 AI 输出的反馈循环
文档质量和 AI 辅助质量会互相强化，既可能形成正循环，也可能形成负循环。
正向循环： 好的文档产生好的 AI 输出，好的 AI 输出节省的时间可以投入到文档维护中，更好的文档进一步提升 AI 输出质量。这个循环一旦启动，文档从成本中心变成投资回报可量化的资产。
负向循环： 差的文档产生差的 AI 输出，差的 AI 输出迫使开发者手动修复，手动修复消耗的时间挤占了文档维护的时间，文档进一步劣化。这个循环同样会自我强化。
两个循环的走向取决于一开始的投入。早期需要有意识地多投入，一旦转起来就能自我维持。
未解决的问题
文档驱动开发能复兴，前提是：文档的维护成本在 LLM 时代会下降。这话对了一半——AI 可以辅助生成文档的初始版本、检测文档与代码的不一致、自动更新变更日志。但文档中最有价值的部分——设计决策的理由、权衡的背景、"为什么不这样做"的记录——仍然只能由人来撰写。
另一个局限是文档的保鲜问题。文档和代码的同步维护是一个经典的工程挑战，LLM 并没有真正解决它。AI 可以检测到文档和代码的偏差，但无法判断应该修改文档还是修改代码——这个判断仍然需要人。文档驱动开发对团队纪律的要求变了：不是"要不要写文档"，而是"怎么让文档和代码保持同步"。