Readable Output

输出工程：让 AI 输出长内容时按清单想一遍

综合写作理论（Zinsser《On Writing Well》/ Heath《Made to Stick》/ Rosenfeld《Information Architecture》）+ 学习科学（Sweller CLT / Brown《Make It Stick》/ Wiggins backward design）+ 大厂文档实践（Stripe / GitLab / Linear / Anthropic / Google SRE）三方交叉验证。

---

元原则（贴在最顶层，每次开始前默念）

1. 如果你自己读完没有获得新认知，读者也不会有。 写作是 thinking on paper，不是模板填空。 2. 终点是"读者下次能用"，不是"读者这次能懂"。 Backward design：先想读者读完手里多了什么"可复用的工具"（一张对照表 / 一个判断框架 / 一条决策路径 / 一个口诀），再倒推写什么。 3. 不列菜单——给推荐 + 一句话理由。 AI 喜欢"列出 5 个选项让你选"，但好文档敢于 opinionated。

---

触发条件

触发（需要给人读的中长 HTML 内容）：

• "做个复盘 / 总结 / 汇总 / 整理"
• "做个教程 / 学习指南 / 上手文档"
• "把 X 讲清楚 / 整理成可读的 HTML"
• "做份报告 / 说明文档"
• 任何要求产出 > 500 字的结构化阅读内容

不触发（短输出 / 操作型 / 非 HTML 需求）：

• 写代码 / 修 bug / 改文件
• 一两句话回答
• 代码 diff / 短列表
• 用户明确说"用 markdown 答" / "聊天里直接说"
• PRD（用 prd-doc-writer）/ 文章写作（用 writing-assistant）/ 起名（用 product-naming）

重要：本 skill 产出只有 HTML 一种格式。如果用户要 markdown，不用本 skill。

---

运作模式

触发
  ↓
阶段 1：强制用 AskUserQuestion 一次性问 4 个关键问题
  ↓
用户选完
  ↓
阶段 2-6 在 AI 心里走（不对用户念稿）
  ↓
产出 HTML，顶部加「本次配置」确认条，浏览器自动打开

例外（跳过阶段 1 的提问）：

• 用户在 prompt 里已经明确所有 4 个参数（如"给 PM 看的 5K 字复盘，故事化风格"）
• 用户明确说 "快速做" / "随便给我一份" / "别问"

---

阶段 1（强制）：用 AskUserQuestion 一次性问 4 个

必须用 AskUserQuestion 工具发起一次询问，包含下面 4 个问题。问题文案和选项可微调但维度不能换。

问题 1：给谁看？（受众）

问题 2：读完拿什么？（终点）

问题 3：要详到什么程度？

设计原因：字数是后验感受、且常常承诺不到（素材撑不到时硬卡字数会注水）。所以字数不进用户视图，只承诺用户能感知的两件事——「包含什么」和「阅读时间」。

字数怎么定（AI 内部参考，不告诉用户、不在配置条里写字数承诺）：

• 阅读速度按 PM/产品类内容 300 中文字/分钟 反推。
• 速读卡 → 内部目标 ~800 字 | 标准版 → ~1.5K-2.5K 字 | 教学版 → ~5K-8K 字
• 真正决定停笔的是"包含什么"清单是否每项都讲到位（standard 的"核心点 / 故事 / 反例 / 出口"四件事都齐全；teaching 多 4 项延展），而不是"字数到了"。

阶段 1.5（强制）：素材体量自检 + 主动反劝

问题 4 答完后、进入阶段 2 之前，AI 必须做一次自检。触发反劝的场景只有一个：

• 单文档型素材（单个 README / 单个 PRD / 单篇文章）且原文 < 3K 字 + 用户选了「教学版」

触发后，AI 必须中断流程，向用户主动反劝：

⚠️ 提示一下：你选的是教学版（20-30 分钟阅读），但素材是单 [README/PRD/文章] 仅 X 字。强行扩到教学版深度，约 60% 内容会是 AI 推演（背景延伸 / 对照 / 框架），不是素材原文。建议二选一：

① 改成「标准版」（5-8 分钟），刚好覆盖素材现有深度

② 补充 2-3 份同类素材（多 PRD / 同领域多篇文章 / 项目全部文档），让教学版有真正的舞台

>

要继续教学版吗？（继续 / 改标准版 / 我去补素材）

• 用户改档：按新档位走阶段 2-6
• 用户去补素材：等用户补完再继续
• 用户坚持继续教学版：才产出，且必须加「素材体量警告」横幅 + 每段推演加「推演」标签（详见输出规则）

多源素材 / 非教学版 → 不触发反劝，直接进阶段 2。

问题 4：风格 + 侧重（合并）

每个选项是「视觉调性 + 内容侧重」绑定的：

用户选完后，把 4 个参数写入 HTML 顶部「本次配置」段（见下方"输出文件规则"）。

---

阶段 2-6（AI 自己心里走，不对用户念）

阶段 2 · 定终点（backward design）

基于阶段 1 用户选的"读完拿什么"，进一步具体化：读完手里多了什么"可复用的东西"？

• 一张对照表（A vs B 怎么选）
• 一个判断框架（什么情况该做 X）
• 一条决策路径（遇到 Y → 先 a → 再 b）
• 一个口诀（短句易记）
• 一份 checklist

反模式：终点只定到"读者理解"。

阶段 3 · 抓核心点（≤ 3 个）

工作记忆铁律（Sweller 认知负荷理论）：新读者一次只能处理 3-4 个新组块。默认 3 个，最多 5 个，超过必须合并或降级到附录。

核心点之间关系必须显式想清楚：

• 【并列】3 个独立要点，可任意顺序读
• 【依赖链 Why → What → How】必须按顺序

砍半测试：列出所有候选点后问"只能保留一半留哪几个"——剩下的就是真骨干。

阶段 4 · 选主结构（一个，不要叠）

警告：这一阶段最容易"自己在示范认知超载"——给推荐 + 一句话理由，不列菜单。

主结构 1 个（按内容性质选）：

主视觉 1 套（不要叠）：表 / 对比卡 / ASCII 图 / Callout，选一种主导。

视觉细节（颜色、字体）按阶段 1 用户选的"风格"决定。

阶段 5 · 写：TL;DR + 论点句 + 反例 + 出口

5.1 开篇 TL;DR / 钩子（前置，不能埋）：Stripe / Google SRE 实践——前 2-3 句 = 全文摘要。钩子三选一：反常识 / 痛点 / 数字冲击。

5.2 每段一个论点句开头：先说结论再展开。

5.3 每个正面论点配一个反例 / What not to do：Anthropic Docs 实践，反例对照比正面示例更有效。

5.4 结尾给"出口"：可复用产物 + 下一步行动 + 边界声明（什么时候不适用）。

5.5 数据带出处，不复制已有内容：链接引用（GitLab single source of truth）。

5.6 复盘类内容：blameless 原则：对事不对人。

5.7 检索提示：开头一句总结 + 每节末尾回顾 + 可复用口诀。

阶段 6 · 自检 5 问

写完前必过：

1. 不懂这事的人能看懂吗？ 2. 读完一周后能复述核心吗？ 3. 最长那段砍一半还说得通吗？ 4. 每段是否都在一屏内？（Linear One-Screen Test） 5. 是按"详略档完成度"产的，不是为了凑字数硬加的吗？（如果为了卡字数加了背景延伸/虚构案例/重复同类场景，砍掉）

---

反模式总清单

---

快速决策树

触发
  ↓
[阶段 1] AskUserQuestion 4 问（除非已明确）
  ↓
[阶段 1.5] 素材体量自检 → 单文档 + 教学版 → 主动反劝改档
  ↓
[阶段 2] 定终点 = 可复用的什么？
  ↓
[阶段 3] 3 个核心点 + 砍半测试
  ↓
[阶段 4] 主结构 + 主视觉（不叠）
  ↓
[阶段 5] TL;DR + 论点句 + 反例 + 出口
  ↓
[阶段 6] 自检 4 问 → 砍 / 拆 / 调
  ↓
HTML 输出（顶部加确认条）+ 浏览器打开

---

输出文件规则

HTML 顶部必加「本次配置 + 追加提示」条

每份产出的 HTML 在 Hero 区下方、正文上方，必须加这样一段双行条：

<div class="config-bar">
  <div class="config-line">
    📋 本次配置 · 受众：[问题 1 答案] · 终点：[问题 2 答案]
    · 详略：[问题 3 答案]（约 [阅读时间]） · 风格：[问题 4 答案]
  </div>
  <div class="hint-line">
    💬 觉得短？告诉我「展开 [章节名]」/「加 [背景/案例/可复用框架]」
       觉得长？「砍到要点」/「合并 X 章和 Y 章」
  </div>
</div>

为什么加追加提示：长度是后验感受，事前再准也会有"差一点"。把"差一点"显式化成可点的指令，用户不用重跑就能迭代。这是这份 skill 故意不卡死字数的配套机制。

为什么配置条只写阅读时间不写字数：阅读时间是用户能感知的承诺、字数是 AI 内部目标。素材撑不到字数时硬卡会注水，撑过头时硬砍会丢内容。把字数从用户视图删掉，避免"标 5K-8K 给 3K"这种期望错位（这种错位等价于旧版"卡不住"）。

文件路径

默认写入项目 docs/ 下：

docs/[内容主题]-[YYYYMMDD].html

如果项目没有 docs/，写入用户指定路径或当前目录。

写完自动打开

写完 HTML 文件后，运行 open <path> 在浏览器打开供 review。

---

维护规则

这份清单综合三方视角（写作 / 认知科学 / 大厂实践）交叉验证而来。如果有新来源（某本经典写作书、某家公司最佳实践）值得加入，按"是不是 3 方都认可"为标准筛选。

反原则：不要往清单里加"可能有用但不是必须"的检查项。AI 走清单本身有成本，每加一项都要确认能阻止某种具体反模式。