verify-docs-findable

verify-docs-findable — 以全新视角冷读文档

这项实践要落实的核心洞见是：完整 ≠ 易于查找。 即使索引列出了所有文档（甚至通过了“每篇文档都已编入索引”的检查），读者仍可能要辗转 5 步，最后不得不查阅源代码才能回答一个基本问题。唯一可靠的测试方法，就是把问题交给一个从未看过这个仓库的人，观察他仅凭文档能找到多少信息。一个全新的低成本 Agent 就能胜任。

为什么用 HAIKU，为什么限定“仅查阅文档”

• Haiku（小型、低成本模型），全新上下文（没有会话上下文）。 关键是让一个未经引导的读者来冷读，而不是一个聪明的读者。拥有上下文的强大模型会搜索源代码、推理填补空白，从而_掩盖_文档的问题。让 Haiku 只查阅文档，就能暴露这些问题。
• “仅使用文档，从索引开始。” 核验者一旦需要打开源代码才能找到答案，文档就已经失职了——这就是我们要捕捉的信号。从索引出发所需的步骤数，就是衡量指标。

流程

1. 收集问题（3–8 个）

测试那些反复出现、至关重要且容易被误述的问题——这些问题确实会浪费时间。按以下顺序寻找问题来源：

• 用户（或你自己）在本次会话中刚刚感到困惑的内容——这是信号最强的来源。
• 文档声称会提供的“标准答案”（一个文档集通常旨在传达约 5–8 条事实；测试这些事实）。
• 如果没有可用的问题：向用户征集问题，或根据文档集的顶层主题推断。不要编造无关紧要的琐事——测试真正的贡献者需要了解的内容。

把每个问题写成读者真正会问的问题，而不是文档标题。

2. 为每个问题启动一个全新的 Haiku 核验者（并行运行）

使用 Agent 工具，设置 model: "haiku"、run_in_background: true，每个问题启动一个核验者。为每个核验者使用相同的严格模板（填入 <QUESTION>）：

你是一名刚刚首次打开 <repo path> 的工程师。仅使用仓库文档回答问题——从索引（<the index file(s)>）开始并跟随指引；优先查阅文档，而不是阅读源代码。 问题：<QUESTION> 报告：（a）你的答案；（b）找到答案的确切文件；（c）从索引出发经过了多少步（指引是否直接带你找到答案，还是需要你自己查找？）；（d）内容是否清晰明确，还是分散难懂？（e）文档没有说明时，你是否不得不阅读源代码？ 请如实报告——本测试旨在检查文档是否便于查找。

在一条消息中运行所有核验者，让它们并发执行。（Haiku + 并行 = 审计成本低。）

3. 为每个答案评分

信号	良好	缺口
正确吗？	与真实情况一致	错误／不完整 → 文档内容有误或缺失
从索引出发的步骤数	1–2 步	3 步以上 → 缺少明确的指引
是否走了弯路？	没有	首先找到了一篇内容看似合理、实际却不相关的文档 → 标题或范围说明存在误导
是否需要查阅源代码？	不需要	需要 → 文档实际上并未说明相关内容
是否存在矛盾？	—	引用了两篇说法不一致的文档 → 存在内容一致性问题（立即修复）

核验者还能顺带发现矛盾：冷读者引用的两篇文档说法不同，这是发现矛盾成本最低的方法。

4. 修复问题

• 3 步以上 / 无法继续 → 在索引入口处添加问题→文档指引（一个“标准答案：问题 → 唯一对应文档”区块）。明确指出答案所在文档，就能把 5 次跳转缩短为 1 次。
• 需要源代码 → 正文里没有这个事实；将其写入唯一的标准文档。
• 答案错误 → 文档内容过时或不正确；修正它（如果文档记录了某项决策，则追加内容而非删除原文）。
• 内容矛盾 → 协调各文档；保留历史决策，并标记为已被取代。
• 内容散落在 N 篇文档中 → 针对每个问题整合到唯一的一篇文档中；其他文档改为指向该文档。

5. 重新验证（测量，而非假设）

针对修复后的文档，重新检查最难的问题。确认步数确实减少（例如，从 5 步降到 2 步）。没有重新测量的修复，只是猜测。

输出

一份简短的可查找性评分表（问题 | 正确 | 步数 | 需要源代码 | 结论）以及一份按优先级排序的修复清单。报告每个已修复并重新验证的问题在修复前后的情况。

注意事项

• 这与“每篇文档是否都已编入索引”的完整性检查是两回事——它衡量的是更上一层：陌生人能否找到答案。每次重新组织文档后都应运行这项检查。
• 将问题集保存在代码库中（例如 docs-findability-questions.md），以便重复执行审计，并确保随着文档库不断扩充，标准答案依然可靠。
• 可按需缩小（1 个问题、1 个 Agent，用于抽查一项修复），也可扩大（完整的标准问题集）。