写文档这件事，终于轮到自己受益了

Specification-Driven Development，规格驱动开发。这个概念活过，死过，现在又回来了。

死因很明确：写规格说明的时间够把代码写两遍。你花两小时写的文档，受益者是三个月后接手的同事，或者半年后已经忘光上下文的你自己——但那时候文档早就和代码对不上了。成本当场付清，收益遥遥无期。交付一紧，文档第一个被砍，谁都不心疼。

这笔账算不过来，所以 SDD 死了。死了十几年。

然后 LLM 来了。

文档多了一个读者

你的类型注解、docstring、README，现在同时是 AI 编程助手的上下文。一个 query(q: str) -> Any 给 AI 的信息约等于零，而 search_products(query: ProductQuery) -> SearchResult[Product] 直接让它推断出入参结构、返回值怎么解包、异常怎么处理。同一个 AI，同一个任务，就因为类型签名的精度不同，生成的代码质量天差地别。

重点不是"AI 能读懂文档"——废话。重点是这件事反过来了：写文档的人自己就是即时受益者。

以前写文档是给别人攒功德，现在是给自己提效。账算过来了，SDD 就活了。

两个读者，一套标准

文档现在有两个读者。需求大部分重合，但差异很微妙。

一个函数叫 process_data，人类同事扫两眼上下文大概能猜出干什么。AI 按字面意思理解，生成出来的代码可能技术上没毛病，语义上完全跑偏。人靠记忆串联模块间的依赖，AI 需要你显式写出来。"我们这边不用 ORM，全是裸 SQL"——这种话不会出现在任何文档里，但你写进 CLAUDE.md，AI 就再也不会给你生成 SQLAlchemy 的代码。

两个读者一起阅卷，「好文档」的及格线被抬高了。以前那种"人能看懂就行"的精度，现在撑不住场面。

CLAUDE.md：把脑子里的东西写下来

我自己在用 Claude Code，项目根目录放了个 CLAUDE.md，写着文件结构约定、命名规范、写作风格。这些东西在传统团队里叫什么？隐性知识。活在老人脑子里，新人来了靠口传心授，走一个人丢一份。

CLAUDE.md 是被 AI 协作逼出来的，但它顺手把那些只存在老人脑子里的东西变成了白纸黑字——面向 AI 写的东西，人也能直接读。

更有意思的是：你在里面写「不使用 emoji」，AI 生成内容时就真的不用。这条规则通过 AI 的执行从描述变成了约束。文档不再只是记录，它在定义行为。这就是 spec 该有的样子。

SDD 十几年前就有人提，没火。不是理念有问题，是那笔账算不过来。现在 LLM 把收益结构掰过来了，账算通了，路就通了。

技术史上这种事太多了。不是做不到，是不划算。划算了，自然就文艺复兴。