last-20-percent
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseThe Last 20%
最后20%
Agents reliably deliver the first 80% of a solution — the ingestion, the endpoints, the schema, the pipeline — and quietly skip the 20% that makes it something a person would love. Asked for an enterprise knowledge wiki, an agent builds the crawler, the embeddings, the LLM synthesis layer, and never once asks what a wiki page should read like, which pages should exist, or how someone finds an answer on day one. The result compiles, passes tests, demos fine, and is dead on arrival.
This skill exists to find that 20%, spec it as concretely as the plumbing, and finish it.
Agent总能可靠交付解决方案的前80%——数据采集、接口、架构、流程管线,但会悄悄跳过那能让用户真正喜爱的20%。当要求构建企业知识维基时,Agent会搭建爬虫、向量嵌入、LLM合成层,却从不会过问维基页面的实际呈现效果、应包含哪些页面,或是用户第一天该如何找到答案。最终产物能编译通过、测试合格、演示顺畅,但实际投入使用后却毫无生命力。
这项技能正是为了找出这20%的内容,将其与底层架构一样明确规范,并完成它。
Why the 20% gets skipped
为什么这20%会被忽略
The failure is structural, so the countermeasures must be too:
- Tasks come from the noun. Decomposing "wiki" yields ingestion, storage, search, generation. The experience of using the wiki never appears in that decomposition — so it never becomes a task, so it never gets done.
- "Done" is defined by what's checkable. A test can assert a 200 response. It cannot assert "this page answers the question in its first paragraph." Work without done-criteria silently drops off the plan.
- Taste feels like overreach. Deciding what a page should read like is a product judgment. Models hedge: they build "flexible" machinery and defer every real decision to a user who asked precisely because they wanted those decisions made.
- The 20% is scheduled last, and last gets cut. Even when the experiential work is named, it lands at the end of the plan — exactly where context, budget, and attention run out.
Each phase below counters one of these.
问题出在结构层面,因此应对措施也必须从结构入手:
- 任务源于名词拆解。将“维基”拆解会得到数据采集、存储、搜索、生成等任务,但使用维基的体验却从未出现在拆解结果中——因此它永远不会成为一项任务,自然也不会被完成。
- “完成”的定义基于可验证项。测试可以验证接口返回200状态码,但无法验证“该页面的第一段就能回答用户问题”。没有明确完成标准的工作会悄悄从计划中消失。
- 审美判断被视为越界。决定页面的呈现效果属于产品判断范畴。模型会采取回避策略:它们搭建“灵活”的机制,将所有实际决策推给用户——而用户寻求帮助恰恰是因为希望这些决策能被代劳。
- 20%的工作被安排在最后,而最后环节总会被砍掉。即便体验相关工作被明确提出,也会被放在计划的末尾——而此时上下文信息、预算和注意力都已耗尽。
以下每个阶段都对应解决上述一个问题。
The cardinal rule
核心准则
Never call a solution done until you have consumed its output the way the end user will — and it delivered the magic moment. Reading your own code is not consuming the output. Passing tests is not consuming the output. Open the wiki and read three pages cold. Run the report and read the report. Load the dashboard and try to answer a real question with it.
永远不要宣布解决方案完成,除非你以终端用户的方式使用过它的输出——并且它带来了预期的惊喜时刻。 阅读自己的代码不算使用输出,通过测试也不算使用输出。打开维基页面,直接阅读三个页面;运行报告并阅读报告内容;加载仪表盘,尝试用它回答一个真实问题。
Phase 1: Write the magic moment
阶段1:撰写惊喜时刻场景
Before decomposing anything, write one concrete scene: a named person, a real task, what they see, and why they'd tell a colleague about it afterward.
Bad (a feature): "Users can search the wiki."
Good (a scene): "Sarah from legal types 'data retention' and lands on a page whose first paragraph answers her actual question, with a link to the policy doc it came from. She stops asking in Slack."
The scene is the destination for everything that follows. If you cannot write it, that gap is the missing 20% — stop and close it first. Propose two or three candidate scenes with a recommendation; never hand the user a blank page to fill in.
在拆解任何内容之前,先撰写一个具体场景:指定一个真实人物、一项真实任务、他们看到的内容,以及事后他们会向同事推荐的原因。
反面示例(仅描述功能):“用户可以搜索维基内容。”
正面示例(场景描述):“法务部的Sarah输入‘数据留存’,进入的页面第一段就直接回答了她的实际问题,还附带了来源政策文档的链接。她从此不再在Slack里提问。”
这个场景是后续所有工作的目标。如果你无法写出这个场景,那么这个空白就是缺失的20%——先停下来填补这个空白。提出两到三个候选场景并给出推荐,永远不要让用户面对空白自行填写。
Phase 2: Decompose the scene, not just the noun
阶段2:拆解场景,而非仅拆解名词
Build two lists:
- The noun list (the 80%). What you get by decomposing the deliverable's name. Ingestion, auth, schema, API, deploy. Agents produce this list automatically; it needs no help.
- The scene list. Walk the magic moment step by step and write down everything that must be true for it to happen. What did Sarah type into, and how did she know to go there? What did the page look like when it loaded? Why was the answer in the first paragraph and where did the link come from? What would she have seen on day one, before ingestion finished?
The last 20% is the scene list minus the noun list. That residue is not random — it falls into recurring categories: content and voice, information architecture, first-run and empty states, opinionated defaults, the golden path, the failure experience, naming and microcopy. The full catalog, with probe questions and worked examples across domains, is in references/last-20-catalog.md — run the scene list against it to catch what the walk-through missed.
构建两个列表:
- 名词列表(前80%):通过拆解交付物名称得到的内容。比如数据采集、权限验证、架构、API、部署。Agent会自动生成这个列表,无需额外帮助。
- 场景列表:一步步梳理惊喜时刻的流程,写下场景实现所需的所有必要条件。Sarah在哪里输入内容?她怎么知道要去那里?页面加载时是什么样子?为什么答案在第一段,链接来自哪里?在数据采集完成前,她第一天会看到什么?
最后20%就是场景列表减去名词列表的部分。这部分内容并非随机,而是可以归为固定类别:内容与语气、信息架构、首次运行与空状态、预设默认值、黄金路径、错误体验、命名与微文案。完整的类别目录(包含探查问题和跨领域示例)可参考references/last-20-catalog.md——对照该目录检查场景列表,找出流程梳理中遗漏的内容。
Phase 3: Spec the 20% at plumbing fidelity
阶段3:以底层架构的精度规范20%的内容
Every scene-list item gets done-criteria as concrete as "endpoint returns 200". Vague quality goals are how this work dies; convert each one into something checkable:
- "Pages should be readable" → "Every page opens with a 2–4 sentence direct answer before any detail; section headings are the questions readers actually ask; every claim links to its source document."
- "Good empty state" → "A search with zero results shows the three closest pages and a one-click 'request this page' action — never a bare 'no results'."
场景列表中的每一项都要有像“接口返回200”一样具体的完成标准。模糊的质量目标是这类工作夭折的原因;将每个目标转化为可验证的内容:
- “页面应易于阅读” → “每个页面开头先用2-4句话直接给出答案,再展示细节;章节标题是读者实际会提出的问题;每个结论都附带来源文档的链接。”
- “优质空状态” → “搜索无结果时,显示三个最相关的页面,并提供一键‘请求创建该页面’的操作——绝不能只显示‘无结果’。”
Golden artifacts
黄金范例
When the system produces artifacts — wiki pages, reports, emails, dashboards, generated code — hand-craft the best possible instance before building the generator. Write the ideal wiki page yourself, with real content about a real topic from the actual corpus. That golden artifact becomes three things at once: the spec (this is what output looks like), the test fixture (compare generated output against it), and the quality bar (a generator that can't approach it isn't done).
A generator built without a golden artifact converges on generic filler, because "generate a wiki page" with no exemplar means "produce the statistical average of all wiki pages." And never use lorem ipsum or placeholder content in a golden artifact — fake content hides whether the structure actually works.
当系统需要生成产物(维基页面、报告、邮件、仪表盘、生成代码)时,在构建生成器之前,先手动打造一个最佳范例。亲自撰写理想的维基页面,使用来自真实语料库的真实主题内容。这个黄金范例同时具备三个作用:规范(输出应达到的效果)、测试基准(将生成的输出与它对比)、质量标准(无法接近它的生成器不算完成)。
如果没有黄金范例就构建生成器,最终只会得到通用的填充内容,因为“生成维基页面”在没有范例的情况下意味着“生成所有维基页面的统计平均值”。另外,黄金范例中绝不能使用Lorem Ipsum或占位符内容——虚假内容会掩盖结构是否真正可行。
Phase 4: Front-load, never append
阶段4:前置安排,绝不后置
In build mode, refuse to schedule the 20% last. Order the plan so the experiential layer survives:
- Golden artifacts first — before the machinery that produces them.
- Experience decisions (page types, defaults, voice, navigation) threaded through the build, decided at the moment the relevant plumbing is built, not batched for "polish week."
- Keep the scene list visible as a finish list in the plan or tracker, each item with its done-criteria. Treat an unchecked finish-list item exactly like a failing test: the build is red until it's green.
在构建阶段,拒绝将20%的工作安排在最后。调整计划顺序,确保体验层工作得以保留:
- 先打造黄金范例——在构建生成它的机制之前。
- 将体验决策(页面类型、默认值、语气、导航)融入构建过程,在构建相关底层架构时就做出决策,不要批量留到“优化周”处理。
- 将场景列表作为完成清单显示在计划或追踪工具中,每个条目都有明确的完成标准。将未勾选的完成清单条目视为失败测试:只要未完成,项目就处于未完成状态。
Phase 5: The walk
阶段5:模拟用户使用
When the build claims to be done, become the end user — cold, no insider knowledge. Perform the magic moment literally: go where Sarah would go, type what she'd type, read what she'd read, all the way through.
Judge what you find against the golden artifacts and the finish list. Then write down every gap between the walk and the scene: pages that read like filler, a dead-feeling first run, a default that made you decide something the product should have decided. Fix, and walk again. The loop ends in one of two states:
- The walk delivers the magic moment → say so, show the evidence (the actual pages read, the actual flow taken), and stop.
- The remaining gaps need a human product decision → list them explicitly as decisions with a recommended option each, and stop there.
当项目声称完成时,切换为终端用户视角——完全不具备内部知识。严格按照惊喜时刻场景操作:去到Sarah会去的地方,输入她会输入的内容,阅读她会阅读的内容,全程走完流程。
对照黄金范例和完成清单判断结果。然后写下模拟使用与场景之间的所有差距:内容像填充料的页面、毫无生气的首次运行状态、需要用户自行决定而产品本应预设的默认值。修复这些问题后,再次模拟使用。循环会在两种状态下结束:
- 模拟使用带来了惊喜时刻 → 明确说明这一点,展示证据(实际阅读的页面、实际走的流程),然后停止。
- 剩余差距需要人工产品决策 → 明确列出这些决策,并为每个决策提供推荐选项,然后停止。
Modes
使用模式
- Plan mode — a build request just arrived. Run Phases 1–4 to shape the plan before or alongside the noun-list work, then Phase 5 before declaring done.
- Audit mode — a solution already exists ("is this actually done?", "why does this feel like a demo?"). Start with the walk (Phase 5) to gather evidence, backfill the magic moment and scene list (Phases 1–2), then spec and finish the gaps (Phases 3–4) and walk again.
- 规划模式——刚收到构建请求。执行阶段1-4来制定计划(可与名词列表工作同步进行),然后在宣布完成前执行阶段5。
- 审计模式——解决方案已存在(比如用户问“这真的完成了吗?”“为什么感觉像演示版本?”)。从模拟使用(阶段5)开始收集证据,补全惊喜时刻和场景列表(阶段1-2),然后规范并填补差距(阶段3-4),再次模拟使用。
Boundaries
边界规则
- The last 20% is depth on the core scene, never breadth. Adding features is the opposite failure wearing a finishing-touches costume. If an idea doesn't serve the magic moment, it goes to a someday list.
- Bring a take. Propose defaults, page structures, and voice with reasons. Reserve questions for decisions that are genuinely irreversible or genuinely business-strategic — and even then, attach a recommendation.
- Don't gold-plate the plumbing. This skill spends its budget on the experiential residue, not on rewriting working infrastructure to be prettier inside.
- A solution is allowed to pass. If the walk delivers the moment, say "this is done" and stop. Manufacturing gaps to look thorough is its own kind of slop.
- 最后20%是核心场景的深度优化,而非广度扩展。添加功能是披着“收尾工作”外衣的另一种错误。如果某个想法对惊喜时刻没有帮助,就将其放入未来计划清单。
- 给出明确方案。提出默认值、页面结构和语气建议并说明理由。仅在决策真正不可逆转或涉及核心业务战略时才提问——即便如此,也要附上推荐选项。
- 不要过度优化底层架构。这项技能的资源应投入到体验层的缺失部分,而非重写原本可用的内部架构来使其更“美观”。
- 允许解决方案通过验收。如果模拟使用带来了预期的惊喜时刻,就说“已完成”并停止。为了显得全面而刻意制造问题是另一种敷衍。