think-twice：让 Agent 写出读者能理解的说明

开发 Spock 时，我发现提示词里会出现一些只有开发环境才有的上下文。

Spock 是一个常驻群聊的 Agent。开发工作区里有代码、设计文档和历史讨论，运行时只能看到实际传入的提示词、工具说明与对话。开发 Agent 写下一句“按照某份决策文档处理”，自己读起来没有问题，Spock 却未必能看到那份文档。

于是我开始要求 Agent 根据接收者实际拥有的信息编写说明。后来又加入对读者背景、事实依据和解释层次的检查，把这些要求整理成了一份名为 think-twice 的 Skill。

我后来经常用它重新解释 Bug、整理交接文档，也分给过同事和朋友使用，反馈都还不错。它的作用逐渐从编写提示词，扩展到了各种需要独立阅读的说明。

从提示词里缺失的前提开始

假如一段运行时提示词写着“按内部授权规范操作”，这句话只是指出规范存在，并没有告诉接收者该做什么。接收者看不到规范时，还需要自己猜。

如果真正的要求是“某项操作必须通过授权工具确认”，提示词就应该写明触发条件、需要调用的工具，以及授权结果如何影响后续动作。维护者需要的决策来源可以另行保存，执行规则必须出现在运行时能够访问的地方。

这里的问题也会出现在普通回复中。Agent 已经看过几十个文件，很容易直接使用内部模块名；读者看到的只有一段结论，却要自行补齐它省略的背景。即使读者有仓库权限，也不意味着读者应该先通读实现才能理解这段话。

因此，think-twice 要求 Agent 在写之前先判断两件事：读者能取得哪些资料，以及读者已经知道什么。前者决定哪些前提需要写进正文，后者决定从什么层次开始解释。

先解释 Bug 是怎样发生的

有一次调试业务表单，Agent 找到了一个字段读写不一致的问题，给出了涉及字段声明、表单框架和读取路径的说明，还比较了两种修法。我看完仍然不清楚：用户已经填了值，为什么计算时却没有用上？

我让它用 think-twice 重新解释。这次它先说明了输入到结果之间发生的事：表单把值保存在一个嵌套对象里，计算代码却去最外层找这个字段。输入没有丢失，只是计算没有读到，最后按零处理。

到这里，修法才容易理解：让计算代码去实际保存数据的位置读取即可。已有数据本来就存在那里，因此不用搬动；但修复后的计算结果会变化，因为原来漏读的值参与了计算。

重述后，我接着确认的也是读取位置和旧数据的关系。前一份说明已经给出了代码层面的原因和方案，但我还缺少理解方案的前提。先说明输入如何得到错误结果，再展开实现，我才能判断这个修改是否合理。

适合调用的场景

有些输出在当前对话里看得懂，离开对话就缺少条件。交接文档、PR 说明、运行时提示词，以及需要发给其他人的问题解释，都适合在交付前用 think-twice 检查。读者需要执行操作时，除了理解结论，还要知道操作前提和完成后的预期结果。

源码交接是一个很典型的场景。我曾把一个小工具打包给别人，要求同时附上 handoff.md，说明它的用途和使用方式。开发目录里已经有配置和状态文件，接收者却是从空目录开始，只复制一条启动命令还不够。

这份文档需要写清哪些目录由程序创建、配置从哪里取得，以及哪些原始资料需要使用者提供。当时核对后补充的是：状态目录会按需创建，配置文件不会自动生成；如果显式指定一个不存在的配置文件，程序会报错。这些条件会直接影响接收者能否完成首次运行。

交接给另一个 coding agent 时，也要按它实际收到的信息编写任务说明。我会把修复目标、允许修改的范围、失败测试和验证方法放进独立文档，接手者就能从这份文档继续工作。需要补充多少背景，取决于接收者接下来要做什么。

一次性短指令则通常没有必要这样处理。接收者已经知道某条命令的用途，或者已经照做，再补一整段背景只会妨碍阅读。现用版本也明确跳过这种情况。

从检查要求到最终输出

think-twice 没有给每类文章准备模板。它要求 Agent 先判断读者为什么看不懂，再核对事实，最后重新组织输出。

判断解释层次尤其重要。前面的表单问题需要先解释填写的值为什么没有参与计算；源码交接则需要补齐首次运行的条件。两者都要补充背景，但读者需要作出的判断不同，说明的重点也不同。

接下来需要区分补充事实和核对结论。前者寻找说明中缺少的信息，后者确认已有判断是否成立。字段读写问题需要检查表单写入结构、计算读取位置和测试输入。只修改上一条回复的措辞，可能把错误的修法一同保留下来。

这些是 Skill 给 Agent 的处理要求。它是否落实了检查，还需要看实际读取的资料、执行的工具和最终输出。文字变得通顺，并不能证明其中的事实已经核实。因此 Skill 要求能够查证的结论回到代码或实际输出，无法确认的部分则写清楚缺少什么依据。

交付时再按文本用途组织：聊天回复先给结论；PR 说明触发问题的条件、改动后的行为和验证结果；交接文档写明继续工作的条件。篇幅由这些信息决定，Skill 不要求把每条回复都写成固定的小标题和清单。

安装和使用

think-twice 放在我的 Skills 仓库里，安装命令如下：

npx skills add https://git.im0o.top/agent-skills/skills

安装后，可以在支持 Skill 的 Agent 中调用 /think-twice。也可以同时说明自己缺少什么，例如希望查看修改前后的数据，或者交接对象是没有参与过讨论的 Agent。