Metadata

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

不留黑箱

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 节）。

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

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

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

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

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

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

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

不是每一步都必须有，但顺序不要乱。详细写法、措辞和反例见 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. 自查清单

交付前逐条过一遍：

不留黑箱的交接讲解

安装技能