写完之后怎么验证：用文档测试在编码前找漏洞

你写了一份自认为清晰完整的规约。怎么知道它真的够好？

直觉做法是交给 Agent 执行，看产出是否符合预期。但这个反馈循环太长：Agent 写完代码、你 review 代码、发现偏差、追溯到规约的模糊之处、修改规约、重新执行。一个模糊点的修正可能需要一个小时。如果规约有五个模糊点，一天就过去了。

文档测试¹提供了一个更短的反馈循环。它的核心思路是：在写代码之前，用 AI 对规约本身进行"思想实验"。

具体做法是用用户故事作为测试用例，让 AI 逐步走查规约。对于每一条用户故事，从触发动作开始，检验规约中是否能找到完整的执行路径：需要调用的接口是否有定义？参数和返回值是否完整？异常情况是否有覆盖？状态转换是否一致？

例如，对于一个支付模块的规约，你可以要求 AI 走查这样一个用户故事："用户提交支付请求，支付网关返回超时，用户在等待期间再次提交了相同的支付请求。" 如果规约中没有定义幂等性处理策略，文档测试会在这里卡住，暴露出这个缺口。

这个过程的成本只有 token 消耗。一次完整的文档测试通常在几分钟内完成。相比之下，让 Agent 写完代码再发现规约有问题，修正成本高出一个数量级。

文档测试有明确的局限。AI 在走查过程中可能产生幻觉：它可能声称某条路径能走通，但实际上规约中并没有提供足够的信息。因此，文档测试的结果需要人类审核。它的价值在于大幅降低发现问题的成本，而非完全替代人类判断。

文档测试发现的每一个问题都需要回写到规约中。如果文档测试暴露了一个边界条件的缺失，修正方式是在规约的 acceptance_criteria 中增加对应的条目，而非口头记住"下次要注意这个"。规约是唯一的事实来源，所有的知识和决策都必须沉淀到规约中。

¹. 文档测试概念由胥克谦（AgentsZone 社区）提出。 ↩