先写文档再写代码：一次文档驱动开发的实践

作者要为设计系统里的一个 Web Component 做大改，改到一半发现自己没法按惯常的方式开工——他很推崇 TDD（测试驱动开发，先写测试再写实现），但当时的状态就是写不出测试。

于是他换了个顺序：**先把新组件的文档写出来，再写测试，最后写实现。**

这个决定他自己都说是"ADHD 驱动的"，纯属找个能启动的入口，结果意外好用。

文档逼你想清楚哪些事

写文档的过程，实际上是在把模糊的想法逐条落实。他在写的过程中被迫回答了几个平时容易拖到编码阶段才临时决定的问题：

这些问题的答案一旦写成句子，就不再是可以含糊过去的东西。文档里写"支持自定义图标位置"，你就得决定它是通过属性、插槽还是 CSS 变量实现——而这些决定会直接变成接口设计。

从文档出发，测试变得好写了：文档里每个使用场景，基本对应一个测试用例。测试写好，实现的边界也就清楚了，写代码时不用再反复回头改接口。

这也是 TDD 常常被低估的一部分价值——真正的收益不是覆盖率，而是**逼你在动手前把需求想明白**。文档只是换了一个更自然的载体：测试用断言描述行为，文档用句子描述行为，后者门槛更低，也更容易和产品、设计对齐。

原文很短，只记录了一次个人实践，没有给出可复用的流程或数据支撑。把它当成一个轻量的方法论提示更合适：当你卡在"不知道从哪下手"时，先写一段给使用者看的文档，往往比硬憋测试更快破局。

作者也明确说，文档驱动开发不是他的发明，他只是在状态不对时偶然用上了，并且打算以后继续这么干。

需要提醒的是，这套做法在接口边界清晰、偏前端的组件开发里最顺手；如果需求本身还在剧烈变动，先写文档可能只是把返工提前了一遍。