better-documents

文档审阅

生成或审阅任何商务文档时，都应遵循沟通最佳实践——确保正确的信息以恰当的顺序传达给正确的受众。

此技能应用了 Anil Dash 的 制作更好的文档中的原则。

适用范围

此技能适用于商务文档：演示文稿、幻灯片、提案、报告、备忘录、简报、单页文档和电子邮件。不适用于 UI、网页组件或前端应用程序——这些请使用 frontend-design 技能。

这里的设计原则与前端设计有几个重要区别：

• 克制胜过表现力。 UI 适合大胆的审美表达和鲜明的视觉个性。商务文档则应尽量不干扰内容。大多数阅读董事会演示文稿或客户提案的人，并不是为了欣赏字体而来。
• 受众无法与文档互动。 网页界面鼓励探索。文档通常只会被读一遍，而且往往是快速浏览，也可能是在小屏幕上阅读或打印出来阅读。任何吸引注意力的设计选择，都会分散受众对信息的注意力。
• 作者和受众都可能不是设计师。 UI 的设计和使用通常都有设计背景作为辅助。商务文档由运营人员、分析师、高管和创始人制作，也由这些人阅读——复杂的设计师直觉上能够处理，对其他人来说却会变成干扰。

模式

模式	适用场景	要做的事
generate	“帮我写一份提案”“制作一套演示文稿”“起草一份备忘录”	编写文档时应用全部五项原则；无需另行提交报告
full-review	“审阅这份文档”“看看这套演示文稿”	对现有文档完成全部五轮检查和读者测试，并生成结构化报告
rewrite	“修正一下”“改进一下”	应用全部检查，测试修改后的结果，并返回修订版
targeted	“请求是否清楚”“检查格式”	只执行相关检查
quick	“快速看一下”“这样行吗”	只执行第 1 和第 2 轮检查，并指出最重要的 3 个问题

从头编写新文档时，默认使用 generate。收到现有文档且没有其他指示时，默认使用 full-review。

---

五轮检查

按顺序执行。每一轮都针对一种不同的失败模式。

在审阅和改写模式下，每完成一轮，都要简要复查本轮所做的修改是否影响了前面各轮的检查结果——例如，第 2 轮中的内容重排不应重新引入第 3 轮发现的格式问题。发现任何退化都应先修正，再继续下一轮。

第 1 轮——受众与目的

文档最常见的失败原因：它是为作者写的，而不是为读者写的。

检查以下内容：

• 缺少背景信息：文档是否默认受众掌握了他们可能并不了解的信息？指出未加解释的行话、背景故事或缩写。
• 请求埋得太深：是否需要提出请求、做出决定或采取行动？如果需要，是否在文档的前三分之一清楚说明，而不是留到最后？
• 以作者为中心的开篇：文档开篇是否着重介绍作者的焦虑、背景故事或资历，而不是双方共有的背景？指出这一问题，并建议调整内容顺序，从共同背景切入。
• 缺少截止时间或利害关系：如果需要做出决定或提供回复，是否说明了时间安排？是否从受众的角度解释了安排时间的原因，而不只是从作者的角度？

如果受众是董事会成员，请在审阅或生成文档前阅读 references/boardroom.md。其中介绍了董事会成员实际如何阅读、会议室中的权力运作方式，以及董事会文档的现实目标。

严重程度指南：

• CRITICAL — 核心请求或决策缺失，或只在文档末尾出现
• MAJOR — 受众不明确；不同读者可能会以不同方式理解文档
• MINOR — 背景信息存在缺口，可以用一句话补足

Pass 2 — 结构与顺序

顺序传递重要性信号。读者会认为排在最前面的内容最重要。 如果事实并非如此，他们可能还没读到关键部分，就已经感到困惑或不以为然。

检查以下方面：

• 按创作顺序排列：文档是否按照撰写时的顺序组织（背景 → 分析 → 结论），而不是按照读者需要的顺序（结论 → 支撑逻辑 → 行动号召）？
• 悬疑式结构：文档是否层层铺垫，直到最后才揭示重点，而不是一开始就说明？标记关键结论或请求出现在后半部分的文档。
• 未说明的排序依据：如果文档按时间顺序、类别或其他非重要性顺序排列，是否明确说明了这一点？如果没有，读者就会试图从顺序中寻找含义。
• 关键内容出现在错误位置：是否有关键内容只出现在演讲者备注、附录或脚注中？核心要点应放在正文中。

严重程度指南：

• CRITICAL — 文档结论或核心请求出现在后半部分
• MAJOR — 排序依据不明显且未作说明
• MINOR — 调整支撑要点的顺序可以让行文更流畅

---

Pass 3 — 克制使用格式

过度使用格式是思路不清晰最明显的表现。当所有内容都被强调时，就没有内容真正突出。本轮检查的对象包括叠加使用强调格式、装饰性下划线、过多颜色、粗重边框、无用的视觉元素，以及读者可能误以为具有特定含义的不一致格式。

完整检查清单请参阅 references/formatting-restraint.md。

严重程度指南：

• CRITICAL — 格式不一致会被读者视为具有语义含义的信号（例如，文档中字体随意变化）
• MAJOR — 过度使用强调格式，导致读者无法判断哪些内容真正重要
• MINOR — 轻微装饰徒增干扰，却没有传递任何含义

---

Pass 4 — 导航与信息密度

读者需要知道自己读到了哪里，以及还需要读多少内容。

检查以下方面：

• 缺少结构指引：对于超过一页或五张幻灯片的文档，是否提供了任何结构说明，例如简要大纲、章节标题或进度标记？如果没有，请标记。
• 缺少概述的数据：是否有图表、表格或数据展示没有标题或说明文字来概述其内容？读者不应毫无准备地解读数据。标记标题无法回答“这展示了什么？”的所有图表或表格。
• 无法回答的问题：文档中是否有实际上无法通过选择作答的开放式问题（作为标题或提示词）？标记可能引发哲学讨论而非推动决策的问题。 好：“我们选方案 A 还是方案 B？”不好：“我们如何改进？”
• 冗长且不分段的文字：是否有超过约 6 行的段落，可以在不损失含义的前提下改成项目符号，让内容更易于浏览？

严重程度指南：

• CRITICAL — 呈现数据时完全没有解读性说明
• MAJOR — 长文档缺少结构标记
• MINOR — 可以改写问题，让它们更易于回答

第 5 轮 — 命名与版本控制

标题承载着信息。大多数文档名称却把这些信息丢掉了。

检查以下内容：

• 通用或自动生成的标题：文档标题是否为“未命名”“草稿”“会议纪要”，或收件人的姓名？请标记，并建议使用包含主题、日期和背景／负责人的标题。
• 以收件人为先的命名：如果文档是给其他组织的某人看的，标题是否以对方而非作者或主题命名？对方会按你的名字而非他们自己的名字来搜索文档。
• 版本含糊不清：文件名或标题是否使用了 _v2、_final、_final_final，或不带日期的连续编号？请标记，并建议按日期进行版本控制。
• 以参会者命名的会议邀请：如果文档与会议有关，请标记标题为“与 [姓名] 开会”的邀请——这种标题没有告诉收件人谈话的主题。

严重性指南：

• 严重 — 面向外部分享的文档没有标题或标题过于通用
• 主要 — 有多个草稿的文档存在版本含糊不清的问题
• 次要 — 命名不够理想，可能导致日后难以检索

---

读者测试

在完整审查和改写模式中，完成五轮检查后，验证文档是否适合目标读者，而不只是适合知道作者原意的你。

1. 预测读者的问题。 写出读者实际阅读时可能会问的 3–5 个问题：我们要决定什么？如果我们拒绝会怎样？费用是多少？截止日期是什么时候？
2. 让没有背景的人试读。 如果有子 Agent 可用，就只提供文档内容和问题，不提供本次对话的背景信息，并派出一个子 Agent 试读。如果没有子 Agent 可用，则跳过此步骤，并在报告中注明未进行读者测试。
3. 报告未能回答的问题。 如果试读者无法仅凭文档回答某个问题，则将其列为第 1 轮检查（受众）发现。在报告中注明“（读者测试）”，并附上暴露问题的提问。

目的是发现作者的盲点：对作者而言理所当然的内容，在初次阅读时却未必能让读者理解。

---

专家评审团

对于高风险文档（董事会演示文稿、客户提案，以及任何面向外部受众的内容），可以酌情召集 3–5 位与文档类型相关的专家角色进行评审，例如持怀疑态度的董事会成员、用手机快速浏览的高管，或没有任何背景信息的首次读者。每位角色都要给文档打 1–10 分，并提出具体批评，而不只是打分。

优先修改得分最低的部分，然后重新评分，直到所有角色得分均达到 7 分以上，平均分达到 8 分以上。

分数	含义
9–10	可直接发布；没有值得改进之处
7–8	整体出色；只需微调
5–6	基本可用，但存在明显不足；需要再修改一轮
3–4	存在重大问题；需要大幅修改
1–2	根本行不通；需要重新考虑方案

适用场景： 高风险外部文档一律使用；内部文档可选；快速模式下跳过。

---

文风中的 AI 痕迹

大模型的默认文风有一些容易辨认的痕迹（对比式揭示、陈词滥调式开场、占位形容词等），会让专业文档读起来像机器生成的内容。在生成模式中，应避免这些痕迹。在审查模式中，应标记这些痕迹。

完整的痕迹列表、修正方法和不应标记的内容，请参阅 references/ai-tells.md。

---

输出格式

生成模式

生成文档时，将全部五项原则作为首要约束，而不是事后核对清单。具体来说：

• 在开头给出结论或提出请求，不要放在结尾
• 按受众关注的重要程度安排内容，而不是按内容的编写顺序
• 只使用必要的格式：每次只用一种强调样式，不加装饰性下划线，颜色不超过两种，以留白代替边框
• 文档超过一页或五张幻灯片时，加入结构性提示
• 标题应包含主题、日期和相关背景
• 写作时避免 AI 痕迹：直接陈述观点，不用反转式表达、陈词滥调的开场白或空洞的形容词（参见 references/ai-tells.md）

检查品牌背景文件。 在询问品牌限制之前，先查找项目根目录中的 .better-documents/brand.md 文件。如果存在，请阅读该文件，并使用其中的品牌颜色、字体和模板规则。如果用户提供的新品牌信息与文件内容不同，请更新该文件。

覆盖默认视觉风格。 不要套用 Claude 的默认文档美学；这种风格看起来像 AI 生成的，不适合大多数专业场景。生成任何带有视觉样式的文档前，先询问品牌或视觉限制；如果没有相关限制，则采用中性风格。完整规则和流程参见 references/visual-style.md。

生成模式无需提供审阅报告。原则已融入流程。

---

完整审阅模式和定向审阅模式

## Document Review: [Title or description]

### Summary
[2–3 sentences: what the document is trying to do, how well it's set up to succeed,
the one or two changes that would most improve it]

### Pass 1 — Audience and Purpose [N issues]
[Each issue: location → what the problem is → suggested fix → severity]
[Reader-test failures go here, labeled "(reader test)"]

### Pass 2 — Structure and Sequencing [N issues]
[Same format]

### Pass 3 — Formatting Restraint [N issues]
[Same format]

### Pass 4 — Wayfinding and Density [N issues]
[Same format]

### Pass 5 — Naming and Versioning [N issues]
[Same format]

### What's Working Well
[2–3 specific things the document does right — what is clear, what is
effective, what is worth keeping. Calibrates the findings. Do not pad it.]

### Top 3 Changes
[The three revisions that would most improve this document's effectiveness,
ranked by impact]

改写模式

完成全部五轮审阅和 AI 痕迹检查，然后对修订稿进行读者测试（如果有可用的子 Agent），再返回结果。返回修订后的文档，并在其后附上简短说明，解释每一轮改动的内容和原因。无需解释每处细微修改，只说明改变含义或顺序的结构性决策。

快速模式

仅返回第 1 轮和第 2 轮中发现的前 3 个问题，每个问题附上一行建议的修复方式。不提供完整报告。

---

约束

• 不要改变作者的语气。 在审阅和改写模式中，改进结构和清晰度，而不是文风。如果某句话清晰有效，就保留原样。
• 不要编造内容。 如果缺少信息（例如截止日期、决策选项或受众背景），请指出缺口，不要自行补充。
• 如果受众不明确，生成前先询问。 在生成模式中，如果请求没有说明文档的读者是谁，或文档需要推动什么决策，请先询问。无论结构多么完善，为错误受众撰写的文档都不合格。
• 具体明确。 每项发现都必须引用实际文本或位置。不要只说“建议澄清”，而应指出具体位置和修改方式。
• 尊重有意为之的选择。 如果文档明确采用叙事形式或悬疑式提案格式，应将结构惯例标记为风险，而不是违规。

---

根据 Anil Dash 撰写的 《制作更好的文档》 改编。