为什么小产品也需要架构总览文档

小产品最容易产生的错觉，是“反正我都知道”

很多小产品不写架构总览，并不是因为它们不需要，而是因为作者默认觉得：人少、系统小、变更都在自己脑子里，所以暂时没必要专门写一张图或一份文档解释整体结构。

这个判断在最早期并不完全错。问题在于，小产品的变化速度通常比想象中快得多。你今天只多加一个内容层，明天再补一个 payment boundary，后天又把 auth、workspace、公开站、部署链路拆开一点。单看每次变化都不大，但几周之后，系统已经不再是“一个人完全靠记忆就能随时复述”的状态。

这时候如果还没有一份总览文档，最先出问题的不是新人 onboarding，而是你自己会开始丢上下文。你记得每个点做过什么，但不再总能快速讲清楚：它们彼此怎么连，哪一层是公开站，哪一层是工作区，哪些是部署边界，哪些是发布门禁，哪些是产品主线，哪些只是临时实验。

我现在越来越把架构总览理解成“恢复上下文工具”，而不是“正式设计文档”。它最重要的价值，不是证明系统多复杂，而是让你在隔了一段时间之后，还能快速重新进入正确问题空间。

比如当我要继续处理 MakePlans 时，如果没有总览图，我就得重新翻 route、翻组件、翻 docs、翻测试，才能重新拼出当前系统的边界。这个过程既慢，也很容易漏。总览文档存在之后，很多事情就会变得清楚：

对小产品来说，这种“恢复速度”远比形式上的架构优雅更有价值。

大团队缺总览，问题通常是沟通成本；一个人做产品缺总览，问题通常是判断成本。因为你会在产品、工程、表达、发布、内容之间反复切换，一旦系统关系没有被写出来，每次切换回来都要重新建立一次脑内地图。

这个代价在独立开发里尤其高。因为你本来时间就紧，如果每次回到项目都先花一段时间想“现在系统到底是什么形态”，那很多真正应该花在决策和推进上的精力，就会被上下文恢复吞掉。

所以我后来不再把架构总览看成“等项目更大了再说”的文档，而是把它看成一个很早就值得补的基础设施。它不需要长，不需要装得像 enterprise 设计说明，也不需要一开始就覆盖所有细节。它只需要足够清楚，让你知道系统大致由什么构成，以及这些构成现在如何协同。

总览最怕的写法，不是太简单，而是太贪心。很多人一写架构文档就想把所有模块、所有依赖、所有流向一次性画全，结果最后变成一张信息密度很高但恢复效率很低的图。你打开它，知道作者很认真，但你还是不知道系统现在最关键的边界在哪。

我更偏向五类信息：

第一，系统分层。比如公共站、工作区运行层、服务边界层、配置部署层、测试与发布层。

第二，关键文件路径。不是所有文件，而是能帮助你重新进入项目的主干路径。

第三，主要依赖关系。谁依赖谁、谁生成谁、谁验证谁。

第四，当前有效文档。哪些是还在生效的，哪些已经只是历史参考。

第五，恢复阅读顺序。一个人下次回来时，应该先看哪三份东西，才能重新理解当前状态。

这几项足够清楚，总览就已经有用了。再往上继续堆信息，通常收益并没有想象中高。

以前我把架构总览更看成工程整理动作。现在我更愿意把它看成发布能力的一部分。因为一旦系统复杂到连你自己都很难快速复述它，很多发布判断就会失真：你不知道某个改动会不会牵到 auth；你不确定某个 smoke checklist 对应哪层；你忘了某条部署链路其实和公开站的内容系统有关。

总览文档本质上是在降低这种“模糊发布”的概率。它不能代替测试，也不能代替 build，但它能让你更快知道该在哪里补测试、该在哪层做 smoke、该读哪份 runbook。对于一个逐步变复杂的小产品来说，这已经是很现实的工程收益了。

第一，小产品不写架构总览，节省的只是当下几小时，增加的往往是之后每次恢复上下文的成本。

第二，总览文档首先服务作者自己，其次才服务协作者。对独立开发者来说，这一点尤其关键。

第三，好的总览图不是细节全集，而是一张能解释系统关系和恢复顺序的地图。

所以我现在不再觉得“小产品还不配写架构总览”。恰恰相反，越是只有一个人推进、变化又频繁的小产品，越需要这样一张地图，来防止系统在你自己脑子里先变得不可读。