不留黑箱的交接讲解

不留黑箱的交接讲解：Agent 自主完成一段较长的工作（理解需求材料、写代码、改数据、部署、验证）之后，把需求背景、落地方案、验证结果和未决事项讲给使用人，让他能先自己吃透、再去和客户、同事、专家沟通。产出一份讲解文档（自己读，也能投屏、转给别人），有需要外部确认或拍板的事项时再加一份确认单（给对方逐条回复），单文件 HTML 或在线文档；结论写明出处，源文件配截图，条目多时用标杆例子讲。当有人说“我得先理解你做了什么”“给我讲讲背景”“对照原材料讲一下”“做个需求导读”“我要拿去和客户/同事沟通”“这些我都没看过”“做个 html 方便我理解”“写份汇报材料，我要投屏讲”“附上源文件截图”，或 Agent 刚独立做完一大段工作需要交接时使用。

不留黑箱

Know your own shit —— AI 做完的活，你得能讲给别人听。

Agent 一个人把活干完了，使用人却没看过材料、没跟过过程。他接下来要去和客户、同事、专家 沟通，必须先听懂：需求从哪来、改了什么、为什么这么改、改了以后会怎样、还剩什么没定。

本 skill 规定怎么讲：每个事项都按同一个顺序讲，用真实数据举例，原文和解读并排放，每个结论 写明出处。它不管活怎么干，只管活干完以后怎么讲清楚。

参考文件：

文件	何时读
references/rhythm.md	动笔前读：单个事项的讲解顺序、条目很多时怎么挑例子、沟通口径、反例
references/evidence.md	要写出处、截源文件或系统页面时：出处写法、截图方法、图注规则
references/page-template.html	写 HTML 时：版式、颜色令牌、组件（原文/解读并排、讲解卡、状态标签、截图与图注）；末尾有确认单骨架
references/example-briefing.html	想看成品长什么样时：一个虚构项目的完整讲解文档

1. 什么时候用，什么时候不用

用：

• 使用人明确说自己没看过材料、要先理解，或者要拿去和别人沟通、当面讲。
• Agent 独立完成了跨多份材料、多个改动的工作，使用人只看到了结果。
• 改动会影响外部的人（客户的数据、专家的方法、同事的模块），需要有人去解释。

不用：

• 小改动、一问一答能说清的，直接在对话里讲。
• 使用人一直全程参与，只需要一个结论。
• 使用人只要一份正式交付的对外文档（报告、发布说明），自己不需要先吃透、也不拿去当面讲，那用对应的写作规范。

拿不准时，先在对话里用三五句话讲结论，问使用人要不要展开成文档。

2. 动笔前准备

逐项确认，缺的就补，补不到的写进文档的「未决与待商量」：

项	要确认什么
读者	讲解文档除了使用人，还会转给或投屏给谁（客户、同事、专家）；确认单给谁拍板
原材料	使用人给过的每一份材料：文件名、谁写的、是什么性质（标准、意见、需求、笔记）
事项清单	这一轮做了哪几件事，每件事对应哪份材料
证据	每个结论背后的实际数据：改前改后的值、比对结果、测试结果。要从真实数据里取，不能凭印象写
出处	每个结论落在哪份源文件的哪一页、哪一行、哪一格；要配图的源文件和系统页面先截好（见 references/evidence.md）
验证	做了哪些验证、在哪个版本上、什么时候做的、结果如何、哪些没验证（比如本机缺环境）
未决	哪些需要外部的人拍板、哪些是自己后续要做的
保密	哪些信息不能出现在会被转发的文档里（见第 6 节）

3. 文档组合

最多两份文档，按读者分（确认单只在有需要外部确认或拍板的事项时做）：

文档	读者	作用
讲解文档	使用人，以及他要转给或投屏给的同事、专家、客户	把整件事讲清楚：使用人先吃透，再直接拿去讲
确认单	需要拍板的外部专家或决策人	逐条答复

默认用单文件 HTML（浏览器直接打开，不依赖外部资源，见第 5 节）；使用人的团队在在线文档里协作时， 直接写进在线文档。

讲解文档只写一份。 使用人自己读的和拿去给别人看的是同一份，所以它从一开始就按「会被别人看到」 来写：只放内容（见第 5 节「文档里只放内容」）。只给使用人一个人的东西（沟通口径、讲解提示）在对话里 交付（见第 8 节）；文档会到外部的人手里时，内部细节也放进对话（见第 4、6 节）。

讲解文档的章节顺序固定，没有的内容就省掉那一节：

1. 结论：三五句。做完了什么、影响多大、需要谁做什么。
2. 一页速览：每个事项一行（来源原话、结果、状态）；条目很多时再加按处理状态的条数表。
3. 先理解背景：被改的东西本身是什么、怎么运转。事项卡里的「它是什么」已经讲清的可以省。
4. 源文件一览：每份材料是什么、谁写的、对应哪个事项；材料之间是什么关系。
5. 每个事项：先一个结论框，再按第 4 节的顺序讲；原文和解读并排。事项可以按材料组织，一份材料一节。
6. 上线与验证：在哪个版本、什么时候、验证了什么、结果如何。
7. 需要外部确认的事项：确认单有几条、请谁回复、怎么回复（在线文档：在条目后填写或评论；单文件 HTML 不能批注， 请对方按编号在邮件或消息里回复，如「待定 1：……」；要对方直接在文件上填的，确认单改用在线文档或表格）； 在线文档附确认单链接，单文件 HTML 写确认单的文件名和位置（列进附录文件清单）。
8. 补充说明：容易被问到的点，写成中性的事实。
9. 未决与待商量：每条写明需要谁。
10. 附录：放不进事项卡的源文件截图、名词解释、文件清单（源文件、跟踪表的位置）。

确认单单独成文，因为读者要逐条回复。开头一段写清：致谁、依据哪几份材料、请回复哪几部分、怎么回复、 希望什么时候前回复。正文分三部分，顺序固定，某部分没有条目就省掉：「已处理」（已改好的，以及不用改、排进下一版的，每条写怎么处理的、没改的写为什么，供知悉，不用回复，不编号）、「疑问」（疑似 问题，每条写出处、现状、建议）、「待定」（需要拍板的，每条写出处和一个明确的问题，并写回复前暂按什么做）。 要回复的条目按部分各自编号，写成「疑问 1」「待定 1」；回复和讲解文档、跟踪表引用时都带前缀。版式见 references/page-template.html 末尾的确认单骨架。没有需要外部确认的事项，就不做确认单。

条目很多时（几十上百条意见），不逐条讲：一页速览给按处理状态的条数表，对应事项里每个状态挑 一到四个标杆例子，挑法、例子一览表和例卡格式见 references/rhythm.md；全量放跟踪表， 文档里写明它在哪（在线文档给链接，HTML 列进附录文件清单）。

4. 核心：每个事项按同一个顺序讲

这是本 skill 最重要的一条。使用人觉得「好懂」，主要靠这个顺序，所有事项都按它写：

1. 它是什么：先用一两句白话解释被改的东西本身。读者不知道「暗访」「培训完成率」是什么，后面的改动他看不懂。
2. 原文 / 改前：材料原话怎么写的，或者改之前是什么样。原文照录，不要转述。
3. 改成了什么：用改前改后对照表，配真实数字的例子。一条规则配一两个最典型的例子，不要列全量。
4. 一个算给你看的例子：挑一个具体对象，把改前改后各算一遍，让读者看到差在哪里。
5. 边界：哪些没动、为什么没动；哪些是例外。
6. 怎么落地的：规模（改了多少处）和核对结果；方法和碰到的坑看读者（见下面「会到外部的人手里时」）。
7. 影响：对结果、对外部的人有什么影响；什么不受影响。
8. 和其他事项的关系：它和哪份材料、哪个待确认事项、哪个后续工作有关。

不是每一步都必须有，但顺序不要乱。详细写法、措辞和反例见 references/rhythm.md。

几条容易卡住的规则：

• 结论放在卡片前面：每个事项先用一个结论框说一句话（改了什么、影响多大、状态），下面才是八步讲解卡。
• 原文不重复：页面上方已经有原文并排的，讲解卡里第 2 步只写「改前是什么状态」，不再照录原文。
• 可以用假设的例子：真实数据里找不到能说明问题的对象时，可以假设一个输入，但分界值、公式、 权重这些规则本身必须是真的，并在例子旁标「假设」。能找到真实对象（样例数据、实际记录）时优先用真的。
• 再算一个不变的例子：讲「什么不受影响」时，最好算一个改前改后结果相同的例子，比一句话有说服力。
• 规模数字写清口径：「改了多少处」可能有两种数法（业务上的条目数、系统里的副本数），两个都写并注明。
• 会到外部的人手里时：第 6 步只写对方用得上的部分（业务条目数和核对结果，用业务说法）；副本数、改法、 系统结构、改的过程中出过又已补上的错、提交号，在对话里讲给使用人（见第 8 节）。
• 使用人自己拍过板的事：写成「按 X 月 X 日定的口径」，讲清内容；是谁定的在对话里提醒使用人。
• 讲解中发现的新问题：写在对应讲解卡末尾的提示框里，同时列进「未决与待商量」，标明「新发现，未核实」。

5. 写法规则

• 结论先行：每节第一段就是结论，依据放后面。读者只看第一段也该知道发生了什么。
• 白话：术语第一次出现就解释；不用内部代号、提交号、函数名当主语，需要时放括号或附录（会到外部时省掉）。
• 真实数据：例子里的数字从实际数据里取，写之前先查一遍。查不到就写「未核实」，不要编。
• 出处写到格：每个结论写明源文件、页、行或单元格，原话逐字照录。写法见 references/evidence.md。
• 原文和解读并排：左边是材料原话，右边是理解和处理结果。读者能自己判断你理解得对不对。 关键源文件配截图，截图和图注的规则见 references/evidence.md。
• 结论只说到证据覆盖的范围：「说到分数的 40 条逐条重算，36 条一致，另 4 条都是系统舍入早了一步（已改）」比「全部没问题」可信。 别的条目里只要有一处中间值对不上，结论就不能扩到全部。
• 界面和系统行为对照实物再写：写「页面不显示 X」「系统会 Y」之前，看一次代码和实际页面 （反例见 references/rhythm.md）。
• 测试结果写清版本和时间：和「最终版本」放在一起的测试结果，读者会以为是在最终版本上跑的； 不是的话写明在哪个版本、什么时候跑的，此后又改了什么。
• 同一个记号只表示一样东西：同一页里只写「3」，读者分不清是例子一览的例 3 还是确认单的待定 3； 写明「例 3」「待定 3」。
• 各处说法一致：同一事实、同一数字、同一说法在讲解文档、确认单、跟踪表里一致。改一处说法时， 把每份文档里同样的话都找出来一起改，包括跟踪表的备注列。
• 状态一眼可见：用「已完成 / 待确认 / 未做」这类标签，不要让读者从段落里找状态。
• 诚实：没验证的写没验证，影响到读者的问题照写，被推翻的结论要更正。上线前就发现并改好、没影响到 读者的失误，文档会到外部的人手里时在对话里讲。
• 长度：讲透为止，但不要把材料整段搬过来。表格只放有代表性的行，全量放附录或另给文件。
• 载体要求：HTML 用单文件，颜色走 CSS 变量并做深浅两套主题，窄屏能看，不引外部脚本；截图用 data: URI 内嵌进 <img>，不写 src="shot1.png" 这类相对路径（转发或换台机器投屏就丢图，见 references/evidence.md）。版式和组件照 references/page-template.html。写进在线文档时用平台自带的组件对应： 结论框用高亮块，原文/解读并排用两栏，状态标签用表格底色，截图用图片块并写图注。

文档里只放内容。 讲解文档会被投屏、转发，确认单会发给外部的人：

• 不写「用途：本人使用」「信息截至」这类元信息，不写讲解顺序、时间安排、措辞建议、沟通口径、 「现场可能被问到」，也不写「今天改了哪几处」这类改动记录。这些在对话里交给使用人。
• 可能被问到的问题改写成中性的「补充说明」：只陈述事实，不用问句，不用质问的口气。
• 结论要经得起被涉及的人当面看：不写读起来像在说对方错的句子，待对方确认的事写成「疑似」「请您确认」 （正反例见 references/rhythm.md「反例」）。
• 交付前把文档通读一遍，找「本人」「讲解顺序」「先讲」「时间安排」「措辞」「沟通口径」「现场」「今天」这类字眼。

6. 保密与脱敏

讲解文档会被转发。动笔前先想清楚它会到谁手里：

• 任何文档都不写密码、令牌、密钥、服务器地址、个人联系方式。
• 会到外部的人手里时（客户、专家），只写对方需要知道的：不写内部系统结构、其他客户的信息、 实现细节、内部人员的评价。内部细节在对话里讲给使用人。
• 引用材料原文时，只摘和事项有关的几行。
• 截图同样要查：系统截图里可能带地址栏、账号、其他客户的名字；放进文档前逐张看一遍。
• 在线文档按团队默认权限创建，不擅自打开「有链接即可查看/编辑」；要开放时让使用人自己设。
• 文档要放进共享仓库或作为示例复用时，整体脱敏：项目名、客户名、人名、行业术语、编号体系、 真实数值、单元格位置、原文里有特点的笔误、地址、提交号全部替换成虚构的，替换后通读一遍，再按名单检索 一遍有没有漏网的。只把真实记录换个名词不算脱敏。

7. 交付前独立核对

文档发出去之前，按下面四个角度各找一个复核者从头查，复核者之间互不知情（宿主能开子 Agent 就每个 角度开一个）。查出的问题再找另一个人试着推翻，推不翻才改。四个角度：

• 事实：每句话对源文件、对系统、对数据查一遍（原话、行号、单元格、公式、数值、状态、编号）。
• 截图：逐张打开图片，看图注说的和图里能看到的是否一致；文档里截了另一份文档的，那份文档 改过之后要重截。
• 一致：讲解文档、确认单、跟踪表和线上版本互相比对：条数、编号、同一件事的说法。
• 读者：文档里有没有元语句、讲解提示；结论在被涉及的人面前读起来是否得体。

开不了子 Agent 时，自己按这四个角度各从头过一遍，每个问题先试着自己推翻再改；在交付说明（见第 8 节） 里写明「未做独立复核」，不要声称已独立核对。

每改一轮，就对改过的地方再查一轮，直到没有新问题。文档放在共享位置时：覆盖前先看有没有新评论、 版本号有没有变（别人可能正在改）；发布后回读线上版本，确认和源稿逐字一致、图片一张不少。

8. 交付以后

在对话里交给使用人：

• 文档链接，以及几句话的交付说明：先看哪一节、哪几件事值得先提（风险、例外、遗漏），哪些检查没做 （如「未做独立复核」「未实测」）。
• 沟通口径：每类读者一段可以直接说出口的话，三到五句：先说结论，再说对他有什么影响，最后说 需要他做什么。写法和例子见 references/rhythm.md。
• 讲解提示：讲的顺序、哪些说法当着谁的面要注意、容易被问到的问题和答法。
• 内部细节（文档会到外部的人手里时）：第 6 步的改法、系统结构和副本数、改的过程中出过又补上的错、提交号。
• 哪些事是使用人自己拍的板：文档里只写「按 X 月 X 日定的口径」，是谁定的在这里提醒（见第 4 节）。
• 使用人说「这个没看懂」，就单独把那一项按第 4 节的顺序在对话里讲一遍；他认可了，再把这段讲解 补回文档对应位置。使用人说「这个节奏好」，后面的事项都照这个节奏补齐。

9. 自查清单

交付前逐条过一遍：

• 讲解文档按第 3 节的章节顺序；每节第一段就是结论
• 每个事项都按第 4 节的顺序讲，没有跳过「它是什么」
• 每个例子的数字都从真实数据里查过；假设的例子标了「假设」，规则数值都是真的
• 原文是照录的，不是转述；每个结论写了出处（文件、页、行或格）
• 关键源文件有截图，每张按 references/evidence.md「截图清单」过了一遍（图注和图一致、后加标注/拼接/略去写明、看不见的格有说明、改稿后重截、投屏看得清）
• 条目很多时，给了按状态的条数和每类的标杆例子
• 结论的范围没有超出证据；界面和系统的说法对照过代码和实际页面；测试结果写明了版本和时间
• 状态标签和正文一致；讲解文档、确认单、跟踪表的数字和说法一致；同一记号只表示一样东西
• 确认单（有的话）开头写明致谁、依据哪几份材料、请回复哪几部分、怎么回复、何时前回复；分成「已处理」「疑问」「待定」 三部分（没有条目的省掉）；要回复的按「疑问 N」「待定 N」编号，和讲解文档、跟踪表一致；每条有出处，「疑问」每条写了 现状和建议，「待定」每条一个明确的问题，并写了回复前暂按什么做；没有需要外部确认的事项就没做确认单
• 未决与待商量写明了需要谁；讲解中新发现的问题已列进去并标「新发现，未核实」
• 文档里没有元语句、讲解提示、沟通口径和改动记录；结论在被涉及的人面前读得过去；这些提示已在对话里交给使用人
• 不该出现的内部信息没有出现，截图也查过；在线文档没有擅自打开链接分享
• 做过独立核对（开不了子 Agent 的，按四个角度自查过，并在交付说明里写明「未做独立复核」），改动后又 复核过；放在共享位置的，线上版本和源稿一致
• HTML：文件能单独打开（截图已内嵌），深色主题下看得清，手机宽度下页面不横向滚动（宽表只在表格框内滚动）， 浏览器放大到 150% 投屏时版式不乱、出处看得清。宿主有预览或截图工具就实际看一次；没有就在交付说明里写明 「未实测」，不要声称已检查