重新组织文档结构：分层逻辑与判断

上一篇提到，AI 编码时功能间契约往往因为缺乏跨会话的载体而全局失守。要回答“契约载体该怎么组织”，得先回到一个更加基本、却常被忽略的原点：项目管理为什么需要文档？如果我们不能回答为什么就无法回答如何做。

传统观念里，文档的价值通常被归结为三点：促成各参与方共识（避免会议记忆漂移）、指导后续开发（提供需求和接口依据，定技术方案）、作为未来决策的依据（连作者自己三个月后都会忘记选型理由）。这三条决定了文档的基准属性：它必须覆盖“谁需要知道什么”，而不能仅局限于“谁负责写什么”。

但传统的横向按岗位职能分层，恰恰是按“谁负责写什么”来组织的。

横向分层的失效与重复之痛

传统体系里，需求归产品、架构归架构师、接口归研发、黑白盒用例归测试、决定权归莫名其妙的领导。这隐含了一个前提：流程里应该存在一个拥有完整上下文的Mr.Key，能在不同文档间建立联系。但当 AI 介入后，岗位的执行边界开始溶解，AI 不在流程的某一环，而在每一环。

横向分层在应对这种变化时，暴露出一个致命的结构性缺陷：同一件事的上下文被分散，导致重复即不一致。

举个我们的真实案例。接口加密策略对所有模块生效。在传统横向体系下，每个模块的接口文档里都抄了一遍加密方式和密钥获取逻辑。“加解密”作为接口行为，声明在各模块里没问题；但“密钥管理”是全局策略，本该只有一个权威出处。当安全策略调整时，三个模块的负责人各自更新了自己的文档，结果改出了三个截然不同、甚至把公私钥部署位置写反的版本。随后，AI 在生成新模块代码时，忠实地读取了其中一份错误文档，直接导致产出物与全局安全策略冲突。

这不是人的疏忽，是组织维度的错位：“密钥管理”这条全局契约，在横向分层里找不到属于自己的唯一物理位置。当几份互相矛盾的文档摆在面前，连资深工程师都得靠猜，AI 更是无从判断哪份才是权威。

纵向模块化与渐进披露

要让人和 AI 都能精确无误地读取契约，必须放弃按“文档类型（需求/设计/测试）”横向切分的主轴，改为按层级纵向模块化组织。

1. 项目级（顶层共享）： 集中收拢全局契约。项目背景、技术栈选型、用户画像分析。像密钥管理这样的全局安全约束、以及模块间的对接标准，全都在这里且只有一份。改一次，约束全局。

2. 模块级（边界管辖）： 明确模块“做什么”和“不做什么”。对外提供哪些能力、依赖外部哪些能力、核心领域模型（DDD）如何设计，都在这一层定，它不提供具体实现但它是具体实现的原则。

3. 功能级（行为规格）： 聚焦单一功能的具体逻辑。这个功能怎么触发、如何处理异常、对应的测试和验收场景是什么。

为什么选择纵向模块化而不是横向分层？ 因为横向分层会让一个功能的上下文散落在相距甚远的几个仓库或文件夹里，AI 根本无法加载一个最小且完整的上下文；而纵向组织，意味着关于一个功能的所有知识（设计、决策、测试）都在一个切片里，同时它能向上精确追溯并继承模块级和项目级的约束，对AI是更加友好的。

比如，我们消息总线模块决定引入 Gossip 协议作为集群数据同步机制。在我们设计的纵向结构里，这个决策的脉络极其清晰：功能层的 Gossip 协议 $\rightarrow$ 模块层的去中心化架构 $\rightarrow$ 项目层的抗单点失效诉求。决策是自上而下推导的，追溯时就能自下而上还原。AI 在处理类似需求时如果能读到顶层诉求，就不会越界去生成一个违背原则的中心化方案。

约束必须是可执行的铁律

纵向分层解决了契约“放在哪”和“管到哪”的问题，但契约有了确定的位置，并不等于它能够被忠实执行。

人工代码评审存在物理上限。一百条约束，评审者能记住八十条已是极限；当 AI 一下午能砸出二十个功能的代码时，人工评审的防线注定会溃不成军。

因此，这套体系最核心的判断是：每一条必须遵守的硬约束，都必须能被机械追溯到具体的测试上，决不能靠人工评审兜底。

如果一条约束（例如“平台层禁用某特性”）无法转化为流水线里的自动校验或测试断言，那它就只是一句毫无价值的废话。分层逻辑解决了契约的可定位性，而测试追溯解决了契约的可执行性，两者缺一不可。

当然，这套体系也有其诚实的边界：它只管束“被写下来的约定”。至于哪些约定算硬约束、该被放在哪一层，这仍然需要工程师凭借经验去判断和定义。工具能兜底执行，但兜底不了技术判断。

本篇主要描述了文档重组的维度判断与分层逻辑。至于这套理念在工程上到底如何落地大家可以自由探索。下一篇，我们将聊聊这套纸面上的方法论，在从 v0 迭代的过程中，我是如何设计专属工具以及遇到过哪些问题的。