我遇到过一种很容易让人误判的系统问题：说明书看起来写得很完整，代码也确实具备对应能力，可真正使用时，别人还是会问“这个入口到底在哪里”。继续往下查，才发现问题不在某一行文字，而在于系统同时存在几种“真相”：运行时的权威解析器、面向人的说明书、命令索引，以及由这些内容生成出来的文档。它们各自没有完全写错，却没有始终指向同一套能力。
这次审查的起点很具体。有人觉得草稿库的位置没有讲清楚，我顺着这个疑问去核对，发现代码里早已有一套权威路径解析逻辑，而且实际运行可以找到正确的草稿库。也就是说，能力并不缺，缺的是门面没有把这条正门讲明白。用户看到的内容和系统真实能做的事情之间，出现了一层距离。
这件事让我重新意识到，文档问题最危险的地方，不是某个句子不够漂亮，而是它可能让人误以为系统没有能力。
入口为什么会先于能力失真
如果只看某个说明文件，问题像是“补一句默认路径”这么简单。但实际情况并不是这样。说明书只是人最先看到的门面，真正决定路径的可能是运行时解析器，帮助使用者查命令的又是另一份索引，最后展示给人的生成文档还可能保存着旧数字。
这几层内容的职责不同。运行时真源负责在当前环境中判断资源在哪里；门面文档负责告诉人应该从哪个概念进入；命令索引负责让人按命令检索；生成器负责把代码中的登记信息变成可阅读的材料。只要其中一层把自己的职责越界，或者复制了另一层本应动态读取的内容，漂移就会开始。
当时我没有直接改说明书，是因为先要回答一个更基础的问题：代码里的权威判断是否真的可靠？如果解析器本身不对，补文档只是把错误说得更清楚；如果解析器是对的，才说明当前缺口主要在入口表达。先确认运行时真源，再讨论门面怎么写，是处理文档漂移的第一道分界线。
表面是路径，实际是多套能力账本
继续审查后，问题从路径扩展到了能力登记。门面里按语义整理的是一套能力族，命令索引里按前缀或操作方式分的是另一套检索桶，生成文档顶部还出现过一个写死的能力数量。它们都能独立工作，却不能自然地回答同一个问题：这个命令最终通向哪项公开能力？
这也是为什么“参数很多”会让人感觉系统混乱。一个能力可能在门面上有一个名字，在底层命令里又有一组不同命名的入口，另外还有一些用于诊断、审计、生命周期保护的内部命令。若把命令总数直接当成能力总数，或者把检索分组当成产品能力族，数字和概念就会一起漂移。
这里最容易误判的是，看到某个数字不对，就只把数字改成当前值。数字确实应该修，但如果数字来自手工抄写，过一段时间仍会再次过期；更深的问题是，读者无法判断这几个数字分别在统计什么。
如果不处理这种区分，后面会出现更隐蔽的后果：维护者会以为自己已经补齐了一个能力，使用者却仍然找不到正门；测试可能只验证命令有没有被列出，却没有验证每项公开能力是否能从索引抵达；生成文档看起来更新了，实际映射关系却仍然是旧的。
我先把三种真相分开
我选择把系统拆成“运行时真源、门面文档、派生索引”三层，是因为这比试图让所有文件互相复制更稳。运行时真源只负责它最擅长的事：给出当前环境下的真实路径、能力登记和入口判断。门面文档不重新发明这些结论，而是解释用户该从哪个概念开始。索引和帮助页则被视为生成物，应该由源数据生成，而不是由人手工维护完整副本。
这样拆分以后，每一层都有自己的失败方式。解析器可能误判环境，门面可能没有暴露关键概念，生成器可能读错数据，索引可能漏命令或把内部命令误写成公开能力。问题不再混成一句“文档过期”，而可以追到具体边界。
审查时我也坚持先只读对账。先核对权威解析结果，再盘点能力登记、命令登记、生成文档和已有测试；确认漂移发生在哪一层后，才决定是否修改长文件。这个顺序很重要，因为长文件往往已经有冻结区或只准变小的棘轮约束，凭印象重构不仅可能扩大改动，还可能破坏原本已经守住的边界。
文档治理的核心不是让所有文件长得一样，而是让每个文件明确说明自己从哪里得到结论。
契约测试要锁住映射，不只锁住数字
后续整改没有停在补一句说明或改一个硬编码数字上。命令索引增加了能力映射，让每条命令都明确指向某项公开能力，或者明确标成内部命令并说明类别。这里的“内部”不是逃避判断，而是承认有些命令服务于诊断、审计或流程护栏，并不应该伪装成用户能力。
同时，映射契约检查了几个方向。第一，命令登记表中的每条命令都必须有映射；第二，映射到公开能力的名称必须真实存在；第三，公开能力不能整体消失在索引之外；第四，生成文档里的能力总数必须来自源数据，而不是另写一个常量。这样一来，测试验证的不是某个文件“看起来有内容”，而是三层之间的关系仍然闭合。
这一步也处理了一个常见边缘情况：命令索引的家族和门面的能力族并不需要强行改成同一套命名。它们服务的目标不同，前者适合检索，后者适合理解。真正需要建立的是交叉引用，而不是为了视觉整齐去重命名所有家族。契约测试锁住的应该是可达关系和语义边界，而不是表面上的同名。
如果只改索引文本，下一次生成时仍可能被覆盖；如果只改生成器，没有测试守住双向完整，新增能力仍可能没有任何可发现入口；如果只补测试，却让数字继续手写，维护者还会被旧信息误导。所以整改必须同时覆盖源数据、生成逻辑和验证关系，但每一处都只改它承担的职责。
最容易走的错误捷径
最容易误判的错误捷径，是把用户看到的说明书当成运行时真相。它很符合直觉：说明书写了什么，系统就应该有什么。可在有自动探测、生成索引和多层入口的系统里，说明书可能只是滞后的投影。直接改它当然能立刻改善阅读体验，却不能保证下一次运行、重生成或扩展能力时仍然正确。
另一个捷径是只追求一个漂亮的总数。命令数、能力数、家族数分别回答不同问题，把它们压成一个“系统有多少功能”，会让读者失去上下文。数字越精确，误导反而可能越强，因为人会把精确当成可信。
我也没有为了消除差异而强行统一所有命名。表面统一会带来更大的迁移风险，尤其当已有测试依赖检索分组、命令格式或冻结文件时。这里更保守的选择是保留已有分组，用映射列和契约测试把关系讲清楚。它不一定最整齐，但能减少无关改动，也更容易知道以后哪里该更新。
这件事让我重新意识到，一个流程成熟的标志，不是它能把文档生成出来，而是它能在下一次变化时准确告诉维护者哪一层先失配。
一套可以复用的对账流程
以后遇到“文档说没有，代码却像有”的问题，我会先做只读对账。第一步，找到运行时真正作出判断的源头，实跑或读取它的输出，确认能力是否真实存在。第二步，分别记录门面、命令索引、生成文档和测试各自声称了什么，不把它们混成一张表。第三步，标出每个数字的统计口径，判断它是在数命令、能力、家族，还是某类内部操作。
第四步，检查入口关系，而不是只检查文本有没有出现。每个公开能力是否能从门面或索引抵达？每个命令是否知道自己是公开能力还是内部工具？生成文档是否直接来自源数据？第五步，先确定最小修复边界，再动手修改；遇到冻结文件、棘轮约束或长文件治理时，优先保留原有护栏。
最后，把已经确认的关系写成契约测试。测试至少要覆盖登记完整、映射有效、公开能力可达、生成数字闭合这几个不变量。这样做的价值，不是让系统永远不变，而是让变化发生时尽早暴露漂移。可复用的方法不是记住某个路径，而是把“真源—门面—生成物”的关系变成可检查的契约。
真正难的不是把一份说明书写得更详细，而是承认说明书只是系统的一层。只要我们愿意把不同层的职责分开，入口漂移就不再只是使用者的困惑，也会变成维护者能够定位、测试能够拦截的具体问题。
下次我会怎么做
下次再看到一个“文档可能没写清”的反馈，我会先问：运行时真源是什么？门面文档从哪里得到结论？索引是手工维护还是生成出来的？这几个问题能让我避免一上来就改长文件，也避免把用户的困惑简单归咎于表达不够好。
如果确认是入口层缺失，我会补上概念、路径和交叉引用；如果确认是生成物漂移，我会回到生成器和源数据；如果确认是能力映射不完整，我会增加契约，而不是再补一行说明。每次只修真正失配的边界，并保留一次可重复的验证结果。
我更愿意把这看成一种工作习惯，而不是一个技巧。系统的真实能力会继续变化，文档也一定会变化。我们能做的不是保证它们永远同步，而是让不同步时尽快被看见，让下一位维护者不用依赖某个人记得“这里其实还有一条隐藏正门”。