AGENT 时代，Markdown 已死，HTML 当立

Agent 时代，输出格式从"易编辑"转向"易消费"

Markdown 是为人写人读设计的；现在文档是Agent 写、人读。"易编辑"已是被牺牲的优势，"信息密度 + 易消费 + 易分享 + 可交互"成为新的核心需求。下图沿四个维度对比两个时代下"Agent ↔ Human"通道的形态变化：

FIG 1 · AGENT ↔ HUMAN 通道：MARKDOWN → HTML 四维转移

为什么 HTML：六个具体的"赢点"

原文从六个角度给出 HTML 的优势——前四个是能力维度（密度、清晰、分享、交互），第五个是生态维度（Claude Code 能吸收的上下文足够多），最后一个是体验维度（"joyful"，让人重新感到投入）。

01 · INFORMATION DENSITY

信息密度

表格、CSS、SVG 插图、script 交互、canvas 空间数据、image 等等。原文断言："几乎不存在 Claude 能读但 HTML 不能高效表达的数据。"作为对比，Markdown 里 ASCII 画图、unicode 估色都是"硬撑"的痕迹。

02 · VISUAL CLARITY

视觉清晰 · 易读

大型 spec / plan 在 Markdown 里超过 100 行就没人读，但同样体量的 HTML 可以用 tabs、章节锚点、配图、mobile responsive 让一个人也能舒服读完——更重要的是，团队成员愿意点开。

03 · EASE OF SHARING

易分享

浏览器不原生渲染 .md，分享要么走附件、要么转图、要么贴 GitHub。HTML 上传到 S3 / GitHub Pages 就是一个能直接点开的链接。原文："别人真的读你 spec 的概率提高一个数量级。"

04 · TWO-WAY INTERACTION

双向交互

不只是看——还能调参。slider、knob、表单、拖拽看板，调出满意的状态后一键"copy as prompt"塞回 Claude。原文中提到自己 prototype 动画时常做这种"用完即扔的专用编辑器"。

05 · DATA INGESTION

上下文吸收

Claude Code 能从代码库、git 历史、MCP（Slack / Linear）、浏览器扩展、本地文件等多源吸收上下文，再 synthesize 成单个 HTML。原文里他写这篇文章时，就是让 Claude Code 翻自己的 code folder 找出所有 HTML 文件，归类后输出可视化对照。

06 · IT'S JOYFUL

它令人愉悦

原文最后一个理由没有"硬指标"，但作者强调它真实存在：用 HTML 跟 Claude 共同打磨产物时，人会重新感到"参与感"——这在 Markdown plan 越写越长、越来越不忍读的时代里，是被让渡的体验。

五个具体场景 · 示例 prompt

原文给出五类已在生产中验证的用例。每张卡：场景图 + 中文意译 prompt（点开看英文原文）+ 适用场景标签。

USE CASE 01 Specs · Planning · Exploration

Spec / 规划 / 多方案探索

原文里 Thariq 已经不写单文件 markdown plan 了，取而代之是一组 HTML 文件互相引用——先让 Claude 探索多个方向、再钻一个、做 mockup、写实现计划，最后开新 session 把这些文件作为 context 喂给 implementation agent。

EXAMPLE PROMPT · 中文意译

"onboarding 屏幕方向没定。给我 6 个明显不同的方案——layout、tone、density 都要变，排版到单个 HTML 文件里做网格对比。每个标注它在牺牲什么。"

展开英文原版 prompt

I'm not sure what direction to take the onboarding screen. Generate 6 distinctly different approaches — vary layout, tone, and density — and lay them out as a single HTML file in a grid so I can compare them side by side. Label each with the tradeoff it's making.

多方向并行探索实现计划跨 session 上下文

USE CASE 02 Code Review · Understanding

代码审查 / 代码理解

把 PR diff、模块图、流程图、严重程度标注同时渲染在一个 HTML 里——比默认的 GitHub diff 视图更适合复杂逻辑（如 streaming / backpressure）。原文作者现在每个 PR 都附一个 HTML code explainer。

EXAMPLE PROMPT · 中文意译

"帮我 review 这个 PR，输出一个 HTML 文档描述它。我对 streaming/backpressure 部分不熟，重点解释那块。把真实 diff 渲染出来 + 在 margin 上加注释、按严重程度配色、加任何能帮助理解的元素。"

展开英文原版 prompt

Help me review this PR by creating an HTML artifact that describes it. I'm not very familiar with the streaming/backpressure logic so focus on that. Render the actual diff with inline margin annotations, color-code findings by severity and whatever else might be needed to convey the concept well.

创建 PR 审查 PR 代码主题理解

USE CASE 03 Design · Prototypes

设计与原型

HTML 即便不是最终交付介质，也是极好的"中间设计语言"——可以先在 HTML 里 sketch，再翻译到 React / Swift / SwiftUI。Thariq 强调要把 slider / knob 用起来：调到满意，再用"copy params"按钮把结果带回 prompt。

EXAMPLE PROMPT · 中文意译

"我想 prototype 一个 checkout button：点击时播放一段动画，然后快速变成紫色。做一个 HTML 文件，带几个 slider / option 让我试不同参数；调好后给我一个 copy 按钮把参数复制出来。"

展开英文原版 prompt

I want to prototype a new checkout button, when clicked it does a play animation and then turns purple quickly. Create a HTML file with several sliders and options for me to try different options on this animation, give me a copy button to copy the parameters that worked well.

设计系统物料组件微调组件库可视化动画原型

USE CASE 04 Reports · Research · Learning

报告 / 调研 / 学习

Claude Code 跨多数据源 synthesize 出研究报告是它的强项——代码、git history、Slack、网络资料汇总成一份高可读性 HTML。Thariq 自己写 prompt caching 系列文章前，先让 Claude 翻 git history 生成一份深度内部研究 HTML 给自己读。

EXAMPLE PROMPT · 中文意译

"我搞不清我们的 rate limiter 怎么工作。读相关代码，做一个单页 HTML 讲解：一张 token-bucket 流程图、3-4 段关键代码 + 注释、底部一个'gotchas'清单。针对只读一遍的人来优化。"

展开英文原版 prompt

I don't understand how our rate limiter actually works. Read the relevant code and produce a single HTML explainer page: a diagram of the token-bucket flow, the 3–4 key code snippets annotated, and a "gotchas" section at the bottom. Optimize it for someone reading it once.

特性总结概念解释周报 / 状态汇报故障复盘 SVG 技术示意图

USE CASE 05 Custom Editing Interfaces

一次性自定义编辑器

纯文本难以描述的操作（拖拽排序、颜色 / 缓动曲线 / 正则、structured 编辑），让 Claude 做一个"用完即扔"的专属编辑器——不是产品、不是复用工具，就一个 HTML 文件，结尾必须有 "copy as JSON" / "copy as prompt" 按钮把结果带回 Claude。

EXAMPLE PROMPT · 中文意译

"我要给 30 张 Linear ticket 重新排优先级。做一个 HTML：每张 ticket 一张可拖拽卡片，分 Now / Next / Later / Cut 四列。你先用最佳猜测预排，加一个 'copy as markdown' 按钮导出最终顺序，每列一句理由。"

展开英文原版 prompt

I need to reprioritize these 30 Linear tickets. Make me an HTML file with each ticket as a draggable card across Now / Next / Later / Cut columns. Pre-sort them by your best guess. Add a "copy as markdown" button that exports the final ordering with a one-line rationale per bucket.

排序 / 三分法结构化配置编辑 prompt 双侧 editor 数据集策展颜色 / 缓动 / 正则

六条答疑 · 原文 Q&A 摘录

原文末尾给出六条最常被问到的问题与作者本人的回答。这里是中文转述：

Q1HTML 不是更费 token 吗？

是。但 Opus 4.7 的 1M context 让这个开销在 context window 里几乎察觉不到；而且 HTML 带来的"实际被读到"和"表达力"溢价远超 token 成本——产物质量整体更高。

Q2那还用 Markdown 吗？

原作者承认自己已经几乎不用了，并自嘲是"HTML maximalist"。日常 spec / report / plan / review 全部 HTML 化。

Q3HTML 文件怎么看？

本地直接浏览器双击打开（也可以让 Claude 直接 open）；需要分享时上传到 S3 / GitHub Pages，给链接就行。

Q4生成 HTML 慢吗？

慢。原作者实测 2-4x 于 Markdown。但他认为产出价值抵得过这部分时间——更少 round trip + 更高被消费率。

Q5版本控制怎么办？

这是 HTML 最大的短板——diff 噪音大、review 起来比 Markdown 累得多。原文没给出解决方案，作者把它视为可接受的代价。

Q6怎么让它不丑、匹配公司风格？

用 frontend-design plugin 提升基础审美；想匹配公司风格，让 Claude 读你代码库后生成一个 design system HTML 文件，之后所有 HTML 都以这个为参考。