---
name: readable-output
description: 产出给人读的 HTML 长文——把已有的素材、经历、资料想清楚再写出来。每次触发先用 AskUserQuestion 一次性问清「给谁看 / 读完拿什么 / 多长 / 风格 + 侧重」4 个关键参数，再按 6 阶段框架输出。**产出只有 HTML 一种格式**——用户要 markdown 或要在聊天里直接说，就不该用本 skill。当用户说"做个复盘""汇总一下""总结这堆""整理成 HTML""做个教程/学习指南""把 X 讲清楚"等需要超过 500 字的结构化阅读内容时触发。不适用于：项目的计划报告/框架计划/版本路线（用 issue-pool，它自带 md2html）、PRD/需求文档/测试用例（用 prd-test-writer）、整页界面方案（用 page-solution-design）、起名（用 product-naming）、写代码/修 bug/改文件、一两句话就能答完的问题。
metadata:
  status: active
  status_updated_at: "2026-10-06"
---

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

## 工具适配

文中的 `AskUserQuestion` 使用当前平台的结构化询问工具；没有该工具时，用一条消息问清同样的四个维度。用户已明确的参数直接继承；工具名不同不阻断写作。


> 综合写作理论（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-test-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：给谁看？（受众）

| 选项 | 说明 |
|---|---|
| PM / 产品经理 | 偏故事、对标、决策、可复用框架 |
| 工程师 / 技术新人 | 含代码片段、技术决策、动手指南 |
| 高管 / 决策者 | TL;DR + 数据 + 投/不投建议 |
| 自己 / 备忘 | 时间线 + 笔记式、备查 |
| 外部用户 / 客户 | 教程式、概念建梯 |

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

| 选项 | 说明 |
|---|---|
| 决策依据 | 看完能 go/no/hold |
| 操作步骤 | 看完能动手 |
| 概念理解 | 看完知道是什么 |
| 故事共鸣 | 看完有感触 |
| 备忘归档 | 看完之后能查 |

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

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

| 选项 | 包含什么 | 阅读时间 |
|---|---|---|
| 速读卡 | TL;DR + 1 个核心框架 / 1 张主图，能转发 | 3 分钟 |
| 标准版（默认推荐） | 核心点 + 故事 + 反例 + 出口 | 5-8 分钟 |
| 教学版 | + 背景延伸 + 多视角对照 + 可复用框架 + 边界声明 | 20-30 分钟 |
| AI 自选 | 按"受众耐受时间 × 素材独立信息点数"反推 | — |

**字数怎么定**（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：风格 + 侧重（合并）

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

| 选项 | 视觉 | 内容侧重 |
|---|---|---|
| 工程严肃 | 清新蓝（Stripe/Linear 风） | 教训方法论为主 |
| 故事化阅读 | 暖色书卷（米白 + 深棕） | 故事完整性为主 |
| 决策简洁 | 极简黑白（Apple 文档风） | 数据冲击为主 |
| 技术深度 | 暗色科技（GitHub Dark） | 含代码细节 |
| AI 自选 | — | 按受众默认推荐 |

**用户选完后**，把 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 个**（按内容性质选）：

| 内容性质 | 推荐结构 |
|---|---|
| 一段过程 / 多步骤决策 | 时间线 |
| 多个主题平行 | 分类章节 |
| 解决某个具体问题 | 问题导向 Q&A |
| 教学 / 概念建梯 | 由浅入深教学梯度 |
| 多版本对比 | before/after |
| 故事性强 | 危机-转折-启示 |

**主视觉 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 直接开写 | 1 | 自我感动 / 走偏 |
| 一次问超过 4 个问题 | 1 | 用户认知负担过重 |
| 用户已给的参数还重复问 | 1 | 啰嗦 / 显得不智能 |
| 终点定在"读者理解" | 2 | 信息汇总而非可迁移工具 |
| 5 个核心点并列 | 3 | 工作记忆超载 |
| 不分并列 vs 依赖链 | 3 | 结构混乱 |
| 列菜单不给推荐 | 4 | AI 让用户选 5 种结构 |
| 主视觉叠加（表+卡+图全用） | 4 | 视觉超载 |
| HTML 顶部没加「本次配置 + 追加提示」条 | 4 | 用户不知道按什么基准产的、也不知道可以追加 |
| 为了卡字数硬加方法论延展 / 虚构案例 / 重复场景 | 3-5 | 注水，自检第 5 问就是为这条而设 |
| 单文档素材选「教学版」未触发主动反劝 | 1.5 | 必然注水 + 用户预期错位（实测 README 类素材撑过 5K 就开始虚构） |
| 配置条 / 表格里写"参考字数"暴露给用户 | 3 / 文件规则 | 用户预期被字数锚定，撑不到时体感是"骗我" |
| TL;DR 埋在中间 | 5 | 读者前 30 秒走人 |
| 没有反例对照 | 5 | 正面示例容易被误用 |
| 数据无出处 | 5 | 容易编造 |
| 文档里抄已有内容 | 5 | 信息漂移 |
| 复盘里指责具体人 | 5 | 违反 blameless |
| 写完不自检直接交付 | 6 | 长 / 啰嗦 / 难读 |

---

## 快速决策树

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

---

## 输出文件规则

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

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

```html
<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 走清单本身有成本，每加一项都要确认能阻止某种具体反模式。