last-20-percent

最后 20%

Agent 能可靠地交付解决方案的前 80%——数据导入、端点、架构、流水线——却悄悄跳过让它真正成为用户心头好的那 20%。当被要求构建企业知识 Wiki 时，Agent 会搭建爬虫、嵌入和大模型合成层，却从未问过 Wiki 页面应该读起来是什么样、应该有哪些页面，或者有人第一天该如何找到答案。结果能够编译、通过测试、演示起来也不错，却从一开始就注定失败。

这项技能旨在找出这 20%，像明确管道建设一样具体地为它制定规格，并将其完成。

为什么会跳过这 20%

问题是结构性的，因此应对措施也必须如此：

1. 任务从名词出发。 把“Wiki”拆解后，得到的是数据导入、存储、搜索和生成。使用 Wiki 的体验从未出现在这种拆解中——因此它不会成为任务，也就永远不会完成。
2. “完成”的定义取决于可检查的内容。 测试可以断言响应状态码为 200，却无法断言“这页在第一段就回答了问题”。没有完成标准的工作会悄无声息地从计划中消失。
3. 品味会让人觉得越界。 决定页面应该读起来是什么样，是一种产品判断。模型会有所保留：它们构建“灵活”的机制，把每个真正的决定都推给用户，而用户提出需求，恰恰是因为希望这些决定能由别人来做。
4. 这 20% 被安排在最后，而最后往往会被砍掉。 即使体验相关的工作被明确列出，它也会落在计划末尾——恰恰是上下文、预算和注意力都即将耗尽的时候。

下面的每个阶段都会针对其中一种问题。

首要原则

在你以最终用户的方式亲自体验解决方案的输出，并且它带来了惊喜时刻之前，绝不要说解决方案已经完成。 阅读自己的代码不算亲自体验输出。通过测试不算亲自体验输出。打开 Wiki，冷启动阅读三页。运行报告并阅读报告。加载仪表板，试着用它回答一个真实问题。

阶段 1：写下惊喜时刻

在拆解任何内容之前，先写一个具体场景：一个明确的人、一项真实任务、他们会看到什么，以及之后为什么会把这件事讲给同事听。

糟糕的写法（功能）：“用户可以搜索 Wiki。” 好的写法（场景）：“法务部的 Sarah 输入‘数据保留’，随后打开一个页面，第一段就回答了她真正的问题，并附上了源自该内容的政策文档链接。她不再在 Slack 上提问了。”

这个场景是后续所有工作的目标。如果你写不出来，那么这个缺口就是缺失的那 20%——停下来，先把它补上。提出两到三个候选场景并给出建议；绝不要把一张白纸交给用户填写。

阶段 2：拆解场景，而不只是名词

列出两份清单：

• 名词清单（80%）。 拆解交付物的名称后得到的内容。数据导入、身份验证、架构、API、部署。Agent 会自动生成这份清单；无需协助。
• 场景清单。 按步骤梳理惊喜时刻，写下要实现它必须满足的一切条件。Sarah 在哪里输入内容？她怎么知道该去那里？页面加载后是什么样子？为什么答案会出现在第一段？链接又是从哪里来的？数据导入完成前，她第一天会看到什么？

最后的 20% 就是场景清单减去名词清单。 剩下的内容并非杂乱无章——它们属于一些反复出现的类别：内容和语气、信息架构、首次使用和空状态、明确的默认选项、黄金路径、失败体验、命名和微文案。完整目录包含探查问题以及各领域的实例，详见 references/last-20-catalog.md——逐项对照场景清单，找出梳理过程中遗漏的内容。

阶段 3：以管道实现的精确度定义最后 20%

场景清单中的每一项都要有具体的完成标准，比如“端点返回 200”。模糊的质量目标会让这项工作功亏一篑；把每个目标都转化为可检查的标准：

• “页面应该易于阅读” → “每个页面开头都先用 2–4 句话直接回答问题，再展开任何细节；章节标题应是读者实际会问的问题；每项主张都链接到其来源文档。”
• “良好的空状态” → “搜索结果为零时，显示最接近的三个页面和一个可一键执行的‘请求此页面’操作——绝不能只显示‘没有结果’。”

黄金样例

当系统会生成产物——维基页面、报告、电子邮件、仪表板、生成的代码——先手工制作出尽可能好的样例，再构建生成器。 亲自撰写理想的维基页面，用真实语料库中真实主题的实际内容。这个黄金样例同时承担三种作用：规格说明（输出就应该是这样）、测试夹具（将生成的输出与之比较）和质量标准（生成器达不到这个水准，就还没完成）。

没有黄金样例就构建生成器，最终只会得到泛泛的填充内容，因为没有范例的“生成一个维基页面”意味着“生成所有维基页面的统计平均值”。黄金样例中也绝不要使用 lorem ipsum 或占位内容——虚假内容会掩盖结构是否真正有效。

阶段 4：前置处理，绝不留到最后

在构建模式下，拒绝把最后 20% 安排在最后。按以下顺序规划，确保体验层得以保留：

1. 先制作黄金样例——在构建生成它们的机制之前。
2. 体验决策（页面类型、默认设置、语气、导航）应贯穿整个构建过程，在构建相关管道时就做出决定，而不是集中留到“润色周”。
3. 在计划或跟踪表中，将场景清单作为醒目的收尾清单，并为每一项列出完成标准。把未勾选的收尾清单项视同未通过的测试：只要有一项未完成，构建状态就为红色，直到全部变绿。

阶段 5：走一遍流程

当构建工作声称已经完成时，要成为最终用户——不带任何内部知识，从零开始。亲自完整体验那个神奇时刻：去 Sarah 会去的地方，输入她会输入的内容，阅读她会阅读的内容，一路走到底。

根据黄金样例和收尾清单评判实际体验。然后记下体验与场景之间的每一处差距：读起来像填充内容的页面、让人感觉冷清的首次使用体验、让你自行决定而产品本该替你决定的默认设置。修复后再走一遍。这个循环最终只会停在以下两种状态之一：

• 体验实现了神奇时刻 → 明确说明这一点，并展示证据（实际阅读的页面、实际走过的流程），然后停止。
• 剩余差距需要人来做产品决策 → 将这些问题明确列为待决策事项，并为每项推荐一个选项，然后停止。

模式

• 计划模式——刚收到构建请求。在整理名词清单的同时或之前运行阶段 1–4，以完善计划；然后在宣布完成前运行阶段 5。
• 审计模式——解决方案已经存在（“这真的完成了吗？”“为什么感觉像个演示？”）。先从阶段 5 的实际体验开始收集证据，再补充魔法时刻和场景清单（阶段 1–2），然后明确差距并完成收尾（阶段 3–4），最后再走一遍流程。

边界

• 最后 20% 应深入打磨核心场景，绝不是拓展广度。 添加功能是另一种失败，只不过披着收尾润色的外衣。如果某个想法不能服务于神奇时刻，就把它放进“以后再说”清单。
• 提出明确主张。 说明你建议的默认设置、页面结构和语气，并给出理由。只有在决策确实不可逆或确实关乎业务战略时才提出问题——即便如此，也要附上推荐方案。
• 不要过度打磨管道。 这项技能的预算应花在体验层的剩余问题上，而不是为了让运作正常的基础设施内部看起来更漂亮就重写它。
• 解决方案可以通过验收。 如果实际体验实现了目标，就说“已经完成”，然后停止。为了显得全面而凭空制造差距，本身也是一种糟粕。