给AI读的测试文档按五列重写,附可复制模板

01 文档是给人看的，模型读的是另一套

PRD 里一句「按老规则处理」，群聊里一句「这个字段先别校验」，Wiki 里躺着一份三年前的接口说明。组里的人读得懂，因为大家记得当时的上下文：老规则指哪一条、先别校验到哪天为止、那份接口说明其实早被后一版覆盖了。

把这些原样交给生成用例的模型，它拿不到这些上下文，只能自己补。补出来的东西看着规整，落到用例里就是一条不存在的业务约束。

问题不在模型爱编，在文档从来没打算被机器读。人能靠默契补足的省略，机器只能当成空位填上一个猜测。

02 三处差距，都是写文档时留下的

把常见的技术文档摊开看，让模型出错的地方高度集中。

• 没有生效版本。 同一个字段，需求文档写一处、接口文档写一处、群聊里又改过一次。人知道按最新的来，检索时三份文本权重差不多，谁被捞出来全看运气。
• 缺否定式约束。 文档习惯写「支持什么」，很少写「什么情况下不许」。模型只看得到前半句，于是把例外当成了默认行为。
• 来源不可追。 一句结论没有出处，生成结果对不上时没法判定是模型幻觉还是文档本身过时，只能整段重来。

点评：这三处不是「文档写得不够详细」。恰恰相反，很多文档已经很厚了，厚在描述和背景，薄在可被校验的那几个字段。补篇幅没用，得改结构。

03 一条规则，五列写全

不用换系统，也不用先上一个平台。把每条规则改成一个固定五列的条目，人读着清楚，检索时也只命中一块确定的文本。

一份可以直接复制的条目模板：

条目编号：BR-014 字段：优惠券叠加上限 取值：单笔订单最多允许叠加 2 张 约束：跨境订单不参与叠加；已退款订单不可再次使用 来源：《交易域需求说明》v3.2 第 4.6 节 生效版本：v3.2 起生效，灰度期仅对白名单商户开放 复核：按团队既有规范填写复核人与日期

条目不用长，但约束那一列必须出现「不」字。一条只写正向能力的规则，等于给幻觉留了一块空地。

组织方式也简单，四类分开放，别混在一个大文档里：

测试知识/ ├── 业务规则/     # 一条规则一个条目，五列写全 ├── 接口契约/     # 字段名、必填、错误码、幂等约定 ├── 环境差异/     # 灰度开关、数据批次、生效范围 └── 废弃区/       # 不删，留一行失效说明与替代条目编号

04 三种内容，改法各不一样

同样五列，落到不同材料上，重点完全不同。

业务规则：最难的是把口头约定收进来。「老客户免押」「大促期间不走风控」这类话，写进约束列时要补上适用范围和失效条件，否则检索出来会被当成全局规则。改前是一段叙述，改后是一条带生效版本和例外的条目。

接口契约：重点在取值和错误码。文档里常写「失败返回错误」，但没列具体错误码与触发条件。生成断言时模型只能编一个。把错误码、必填项、幂等约定逐条写进取值列，断言才有依据。

环境差异：这一类最容易过期，也最容易被漏掉。灰度开关、数据批次、白名单范围，都要挂生效版本。同一条规则在预发和生产的表现不同，就该拆成两条，别在一条里写「视环境而定」。

点评：三类的共同动作只有一个——把「看情况」这三个字拆成可枚举的条件。拆不动，说明这条规则本身还没被讨论清楚，先回去问清楚再写，别让模型替团队做决定。

05 让它不过期，靠两条规矩

条目写完只是起点。三个月后还能不能信，取决于改动发生时有没有人回写。

• 谁改谁回写。 需求变更、接口改版、灰度扩量，改动的同时更新对应条目，并把生效版本往后推一版。评审清单里加一行「本次改动涉及哪些知识条目」，比事后补库有效得多。
• 废弃留墓碑，不直接删。 旧条目挪进废弃区，保留一行失效说明和替代条目编号。直接删掉，历史用例与历史报告就再也查不回当时的口径了。

再加一道准入：新条目进库前，人工核对来源与生效版本两列是否填了实名，别让空值混进去。Agent 与测试 Skills 检索得越快，越需要在入口留一处能被人按停的地方。

点评：这两条都不涉及工具，全是约定。工具能把检索做快，判断哪条规则还作数，始终得由人签字。

06 写在最后

把文档改成五列，不会让模型突然变聪明，也不会少写一行用例。它做的是另一件事：让「模型为什么给出这条断言」变成一个可以顺着来源查回去的问题。

查得回去，幻觉才是可修的 bug；查不回去，就只能整段重来，然后下次照样重来。

知识库的价值从来不是存了多少篇，是在需要它的那一刻，能稳定取出那条还作数的规则。这一条对人也成立：一个刚接手项目的新人，靠着五列条目，不用再花两周去补那些群聊里的上下文。