evidence-docs

有证据支撑的文档

**只有附带核查方法的主张，才算文档。**本技能是标准，也是索引：十条准则，以及每条准则的定义、执行和奠基位置。

它是导航索引，而非第二份副本。下列每条规则都只有一个归属——这就是准则 3；若导航索引重述了规则本身，就会违反它所索引的规则。每条准则的完整说明、理由和执行方式都载于 documentation.md → The canons。

十条准则

1. 主张附带其地址——file:line、附有输出的命令、测试名称；经验教训则注明其提交。
   • 1a. 看起来像证据的标记，在解析确认之前并非证据。提交 SHA、行号、路径、标志、测试名称：每一个都可能看似可信，却并不存在；而人们恰恰会在不再核对它们时相信它们。提交引用要在提交实际存在之后填写，并用命令核实。
2. 数字要计算得出，绝不重新陈述。
   • **2a. 从 shell 得出的数字，在查看匹配项之前不算测量结果。**只要某个标记可能出现在其他内容中，就应在计数旁打印并分类匹配项；也绝不要管道连接退出状态会影响后续操作的命令——否则 shell 给出的就是分页器的状态。包含这三个数字的十八行与十八次节流事件是不同的主张。
3. 每条事实都只有一个归属——其他地方只链接，绝不重述。
4. 引用应从阅读文档的位置解析——而非从文档所在的位置解析。
5. 没人观察却变红的绿灯，不算证据。
   • **5a. 无法复现缺陷的过小模型，也不足以证明修复有效。**先复现，再修复：若测试框架在未修复的输入上也能通过，它就不是合格的测试框架。若模型小于研究对象，就要列出它遗漏的内容，并附上数字。
6. 检查只能证明其范围内的内容，不能证明更多。
7. 沉默不代表通过——要问机制在未进行检查时会打印什么。
8. 估算绝不宣称为测量结果——规则要说明其证据条件。
9. 已检查的内容旁要列出未检查的内容。
   • 9a. 测得的零与未测量的数量，打印结果不能相同——准则 9 要求标明缺失；9a 则要求未进行测量时不报数字。
10. 文档要随使其内容为真的变更一同提交——更正要追加，绝不覆盖原文。

这些准则是认识论层面的：它们界定了什么才算文档。操作层面——在特定触发条件下要做什么、如何检查以及何时结束——见 learned.md。当两者看起来在说同一件事时，准则讲的是为什么，规则讲的是怎么做。

接下来读什么

你将要……	阅读	原因
从零开始搭建项目文档	documentation.md → 清单	在着手工作前回答四个问题
记录一项决策，让它在作者离开后仍然有效	登记册与 ID + templates/decisions.md	仅追加的 ID、边缘标记、唯一的决策归档处
做出更改，同时避免文档失去对应内容	文档循环 + 传播矩阵	更改需要更新哪些文档，从元行开始
决定某条事实应放在哪里	单一事实来源	其中一处更新后，两个归档处就会出现矛盾
构建不会撒谎的检查	gates.md	三个维度、执行阶梯、逐步启用、探测
信任一个报告成功的机制	gates.md → 虚假成功	移除查看理由的那种失败
将检查接入 Agent 自己的工具	hooks.md	钩子契约，以及崩溃的防护机制为何会允许操作继续
审核项目已有的文档	setup.md	七轮检查，从成本最低的开始，输出为修复计划
将经验教训带到下一次运行	retrospective.md	先盖时间戳（冷启动触发器会读取它），再精简到最多十条；每条经验都要注明其提交
在宿主项目中植入门禁	templates/docgate.sh	它植入的是绿色状态：尚无输入的地方保持休眠
声称某个 Agent 表现良好	tdd.md → 当被测对象是 Agent 时 — 此处使用具名引用而非链接，因为此导航中的目录外链接在打包者单独分发此技能包时会失效	地址是跟踪 ID 和实际运行的断言（规范 1）；一个无人监督的评判者即使意见不合，也会给出无人监督的绿色结果，而不是转为红色（规范 5）
推动一项完整更改直至验收	task-pipeline 技能（需单独安装）	此技能定义标准；那个技能说明如何让更改进入代码仓库

适用范围

边界在于“它会被当作事实来读”。 决策记录、README、验收报告、运行手册、面向用户的变更日志、审计发现，或声称某事已得到验证的内容。

不适用此技能的内容： 草稿、边想边说的内容、聊天答复、提交消息、代码注释。要求别人为“让我检查一下”提供 file:line，是教会 Agent 绕过规则的最快方式，而规则真正能保护事物的地方恰恰在此。

拒绝措辞——“без доков” / “on my word”。 如果任务原本会经过此流程，这种说法就会生效：直接完成任务，并明确说出该说法没有依据，而不是把估计伪装成测量结果（规范 8）。

规范服务于谁

操作者的意图才是关键。证据让意图经得起现实检验 — 而不是拒绝执行的许可证。

以上一切都是为了让操作者得到他们真正想要的结果，并避免过程中悄然出错。它们不是用来决定他们可以说什么的。若某项技能把规范 8 理解为“我不能写未经核实的主张”，并因此拒绝执行，就颠倒了自身的目的：它保护了一条规则，却辜负了规则原本服务的人。

界限在此，而且两者并非一回事：

操作者可以	操作者不可以，且这构成拒绝理由
声明尚未成真的内容——例如介绍正在开发的产品的落地页、路线图、宣传材料	让某项测量结果声称并非事实的内容：通过的测试、基准测试、计数、引用
在被告知一次后，明知缺乏依据仍发布主张	将估算值呈现为测量结果（规范 8），这是唯一不受任何意图授权的事

**因此，面对未经证实的主张，顺序是：说一次，标注它，然后继续工作。**这不是协商，不是第二次警告，更不是伪装成提问的悄然拒绝。如果操作者确认他们知情，就带着标明其为前瞻性内容的标记发布该主张——这就是此处这项技能应做的一切，然后完成任务。

**接着完成更难的那一半。**遵循意图只是底线，不是服务。服务在于让意图更好——比操作者要求的更有结构、更可预测、更易维护和扩展，同时仍然是他们要求的内容。只会服从的 Agent，不过是一把更慢的键盘。

唯一的检验

在文档发布之前，找出那句会让你在有人问*"你怎么知道？"*时感到难堪的话，然后从三件事中选一件做：给那句话注明出处、删除它，或者将其标记为操作者选择发布的无依据主张，并发布它。第三种选择不是漏洞，而是前两种选择有意义的原因。没有可行之道的规则只会让人绕开它，最终没有任何内容会注明出处。

**编辑这些参考资料。**这里 references/ 和 templates/ 下的文件都是生成的副本，因此单技能安装后，所有链接都能正常解析，无需相邻的代码库检出。请编辑源文件所在位置，绝不要编辑副本——哪些文件是生成的、从何处生成，以及如何重新同步：GENERATED.md。

触发条件

描述是简短版。它在 1.98.0 之前包含的完整触发条件列表现已原样移至此处，仍会路由到这项技能：

"Use when writing or reviewing anything that will be read as true — a decision record, a README, an acceptance report, a runbook, a changelog entry, an audit finding, or any claim that something was verified. Applies the ten canons of evidence-backed documentation — what makes a claim documentation rather than an assertion — and routes to the doctrine that enforces each one. Also use when a project needs a documentation gate, a decision register, a propagation matrix, or a retrospective that outlives its author. Triggers - 'documentation gate', 'decision record', 'ADR', 'acceptance report', 'runbook', 'is this verified', 'доказательная документация', 'записать решение', 'запиши решение', 'отчёт о приёмке', 'раннбук', 'чем это подтверждено', 'доки в синхроне'. Not for: drafts, chat answers, commit messages or code comments — say 'без доков' to opt out."