核心思想
当模型越来越擅长产出长方案、specs 和报告时，Markdown 的表达力开始捉襟见肘。HTML 在信息密度、视觉清晰度、易分享性、双向交互 四个维度全面胜出，特别适合 specs/code review/设计/报告/一次性编辑器五大场景。代价是生成时间 2-4 倍，以及 HTML diff 噪声大、难以做版本对比。
Markdown 已经成为 agent 与我们沟通时的主流文件格式。它简单、便携、具备一定的富文本能力，而且方便你自己编辑。Claude 甚至已经擅长用 ASCII 图表（ASCII diagram）在 markdown 文件里画图，这一点让我相当意外。
但随着 agent 越来越强大，我开始觉得 markdown 是一种有局限的格式。超过一百行的 markdown 文件，我就读不下去了。我想要更丰富的可视化、颜色和图表，并且希望能轻松分享。
而且我越来越不会亲自编辑这些文件，更多是把它们当作 specs（规格说明）、参考文件、头脑风暴（brainstorm）的产出等等。即便我要做修改，通常也是让 Claude 来改，这就抹掉了 markdown 最大的好处之一。
我开始更喜欢用 HTML 而不是 Markdown 作为输出格式，并且越来越多地看到 Claude Code 团队的其他成员也在这么做。这篇文章就讲讲为什么。
（如果你想直接看一些例子，可以从这里看一堆：https://thariqs.github.io/html-effectiveness，但记得回来读完背后的原因。）
为什么是 HTML？
信息密度
相比 markdown，HTML 能传达远为丰富的信息。它当然能搞定基本的文档结构，比如标题和格式，但它还能表达各种各样的其它信息：
- 用 table 标签呈现表格数据
- 用 CSS 表达设计数据
- 用 SVG 画插画
- 用 script 标签内嵌代码片段
- 用 HTML 元素 + JavaScript + CSS 构造交互
- 用 SVG 和 HTML 表达工作流
- 用绝对定位和 canvas 表达空间数据
- 用 image 标签嵌入图片
我甚至敢说：几乎不存在 Claude 能读懂、却没办法用 HTML 高效表达的信息集合。这让 HTML 成为模型向你传达深度信息、以及你回头审阅它的极高效方式。
我发现，如果不能这么做，模型就会在 markdown 里搞出一些低效的事情，比如 ASCII 图表，或者我个人最爱的——用 unicode 字符来”估算”颜色，下面这张 Claude Code 的截图就是个例子。
Claude Code 在 markdown 里尝试展示颜色
视觉清晰度与阅读体验
随着 Claude 能做越来越复杂的工作，它写出来的 specs 和方案也越来越长。实际操作中我发现自己往往不会读完一个超过 100 行的 markdown 文件，更别说让公司里其他人读了。
但 HTML 文档读起来轻松得多，Claude 可以把结构在视觉上组织成最适合浏览的样子——tab、插图、链接等等。它甚至可以做成响应式的，让你根据自己的设备形态（form factor）以不同方式阅读。
易于分享
Markdown 文件相当难分享，因为大多数浏览器并不能很好地原生渲染它。你常常得把它作为附件塞进邮件或消息里。
而 HTML，只要你把文件传上去（比如传到 S3），就能轻松分享一个链接。同事可以在他想要的任何地方打开它、引用它。
如果你的 specs、报告或 PR 说明是 HTML 格式，被别人真正读完的概率会高得多得多。
双向交互（Two-way Interaction）
HTML 让你可以与文档交互。比如，你可以让它加上滑块或旋钮来调整设计，或者让你切换算法里的不同选项看看会发生什么。你也可以让它把这些改动复制成可以粘回 Claude Code 的 prompt。关于这种双向交互的更多例子，可以看我那篇关于 playgrounds 的文章：https://x.com/trq212/status/2017024445244924382
数据摄取
为什么用 Claude Code 来生成 HTML 文件，而不是用 ClaudeAI 或 Claude Design？最大原因之一是 Claude Code 能摄取的上下文。比如写这篇文章时，我让 Claude Code 翻遍我的代码文件夹，找出我生成过的所有 HTML 文件，分组并归类，然后做一个 HTML 文件来展示每一类的图示。本文里的那些示意图就是这么来的。
除了文件系统，Claude Code 还可以通过你的 MCP（如 Slack、Linear 等）、你的浏览器（Claude in Chrome）、你的 git 历史等等找到额外的上下文。
这很有趣
用 Claude 做 HTML 文档单纯就是更好玩，让我对创作过程更投入、更有参与感——光这一点就足够了。
如何上手
我有点担心，会有人读完这篇文章就把它做成一个 /html skill 之类的东西。这么做或许有点价值，但我想强调：你并不需要做太多事情就能让 Claude 这么干。你只需要让它”做一个 HTML 文件”或者”做一个 HTML artifact（工件）”。
诀窍在于你要清楚自己希望这个 artifact 做什么、你打算怎么用它。你也许过段时间会做一个 skill，但现阶段我建议先从零起手 prompt，先在不同场景里把感觉摸顺。
使用场景
为了让这件事更具体，我做了很多不同用途的 HTML 文件。所有这些你都可以在这里看到：https://thariqs.github.io/html-effectiveness/，下面是大致概览。
规格说明、规划与探索
HTML 是一块丰富的画布，方便 Claude 深入钻研一个问题。当我开始处理一个问题时，我不再期望产出一个简单的 markdown 方案，而是预期会做出一整张相互关联的 HTML 文件之网。比如，我可能先让 Claude Code 头脑风暴并给出几种不同方案的探索。然后让它在某个方向上展开更多，也许做点 mockup 或代码片段。最后，当我有感觉了，再让它写一份实现方案。等我对方案满意了，我会开一个新会话，把所有这些文件都丢进去让它实现。
到了验证阶段，我也会让验证 agent 把这些文件都读一遍，这样它就能拿到关于”需要做什么”的更广上下文。
Prompt 示例：
- 我不确定 onboarding（引导）页面该往哪个方向做。生成 6 个截然不同的方案——在布局、调性、信息密度上都做出区别——把它们排成一个网格放在一个 HTML 文件里，方便我并排比较。给每个都标上它做出的取舍。
- 在一个 HTML 文件里写一份详尽的实现方案，记得做几张 mockup、画出数据流，并把我可能想看的关键代码片段贴上。让它易读、好消化。
适用场景：
- 探索代码层面的不同实现方式
- 探索多种视觉设计
代码评审与代码理解
代码在 Markdown 文件里很难读。但用 HTML 我们可以渲染 diff、批注、流程图、模块图等等。可以用它来理解 agent 写的代码、做 code review，或者向某个 reviewer 解释你的 PR。我发现这通常比 GitHub 默认的 diff 视图好用，所以我现在每次提 PR 都会附一份 HTML 代码讲解。
Prompt 示例：
帮我评审这个 PR，做一个 HTML artifact 来描述它。我对其中的 streaming/backpressure（流处理/背压）逻辑不太熟，所以重点说这块。把真实的 diff 渲染出来并在行内边距加批注，按严重等级用颜色编码各项发现，以及任何能帮助把概念讲清楚的元素。
适用场景：
- 写一个 PR
- 评审一个 PR
- 理解代码中的某个主题
设计与原型
Claude Design 就是基于 HTML 的，因为 HTML 在表达设计上极具表现力——哪怕你最终交付的形态不是 HTML 也无所谓。Claude 可以先用 HTML 勾勒出设计，再用你选择的语言（React、Swift 等等）写出来。
你也可以原型化各种交互，比如动画、动作等等。可以让 Claude 做滑块、旋钮等控件，方便你调出你想要的精确效果。
Prompt 示例：
我想原型化一个新的结账按钮：点击时先做一个 play 动画，然后快速变紫色。做一个 HTML 文件，给我若干滑块和选项让我尝试这个动画的不同参数，再给我一个复制按钮，方便我把效果好的参数复制走。
用途：
- 创建设计系统的工件
- 调整组件
- 可视化组件库
- 原型化让人愉悦的动画
报告、研究与学习
Claude Code 极其擅长把多个数据源的信息综合起来，转换成一份易读的报告。你可以让 Claude 搜索你的 Slack、代码库、git 历史、互联网等等，用来给你自己、给领导、给团队生成可读性极高的报告。
你可以把它组装成一份长 HTML 文档、一个交互式讲解页，甚至是幻灯片/演示稿。让 Claude 用 SVG 画图来辅助可视化。比如我那几篇关于 prompt caching 的文章，我让 Claude 在读完 git 历史后，把我们对 prompt caching 的所有改动整理成一份深度研究的 HTML 文件供我阅读。
Prompt 示例： 我没搞懂我们的限流器（rate limiter）实际是怎么运转的。读相关代码，产出一个单页 HTML 讲解：一张令牌桶（token-bucket）流程图、3-4 个核心代码片段并加上批注，外加底部一个”坑点”区。按只读一遍的人来优化它。
用途：
- 总结某个特性如何运作
- 给我讲清楚一个概念
- 给老板的周报
- 给领导的事故复盘
- SVG 插图、流程图、技术示意图等
自定义编辑界面
有时候你单靠一个文本框很难描述清楚自己想要的东西。这种情况下我会让 Claude 给我搭一个一次性的（throwaway）编辑器，专门针对我手头处理的那个东西。它不是一个产品，也不是一个可复用工具，就是一个 HTML 文件，专门为这一份数据而生。
诀窍永远是以一个导出按钮收尾：“copy as JSON” 或 “copy as prompt” 这样的按钮，把我在 UI 里做的任何动作变回一段我可以粘进 Claude Code 的内容。
Prompt 示例：
- 我需要给这 30 个 Linear ticket 重新排优先级。给我做一个 HTML 文件，每个 ticket 是一张可拖拽的卡片，跨 Now / Next / Later / Cut 四列摆放。先按你最佳猜测预排好。加一个 “copy as markdown” 按钮，把最终顺序导出，并且每一档附一行简要理由。
- 这是我们的特性开关（feature flag）配置。给它做一个表单形式的编辑器，按业务区域给开关分组、显示开关之间的依赖关系；如果我打开一个开关而它的前置条件还没开，就警告我。再加一个 “copy diff” 按钮，只把改过的 key 给我。
- 我在调一个 system prompt。做一个左右并排的编辑器：左边是可编辑的 prompt，把变量槽位高亮出来；右边是三组示例输入，会实时把模板填好的样子渲染出来。再加一个字符/token 计数器和一个复制按钮。
用途：
- 给任何东西重新排序、分诊、分桶（ticket、测试用例、反馈等）
- 编辑结构化配置（特性开关、环境变量、带约束的 JSON/YAML）
- 调 prompt、模板或文案，并实时预览
- 整理数据集、批准/拒绝行、给样本打标签、导出选中的部分
- 给文档、转写或 diff 加批注，并把批注导出
- 选择那些用文字很难表达的值：颜色、缓动曲线、裁剪区域、cron 时间表、正则表达式
常见问题
我跟很多人聊过我已经切换到 HTML 这件事，发现有几个反复出现的问题。
HTML 不是 token 效率更低吗？ 虽然 markdown 通常用更少的 token，但我发现 HTML 带来的额外表现力，加上”我真的会去读它”的概率高得多，整体来说我得到的产出更好。在 Opus 4.7 的 1MM 上下文窗口（context window）下，多用的那些 token 在上下文窗口里其实感受不太到。
那你现在还什么时候用 markdown？ 老实说我几乎已经完全不用 markdown 了，但我大概在 HTML 极端主义者那一端走得很远。
怎么查看 HTML 文件？ 我一般就在本地用浏览器打开（你也可以让 Claude 帮你打开），或者上传到 S3 拿一个可分享链接。
生成 HTML 不是比 markdown 慢吗？ 确实更慢！HTML 可以比 Markdown 慢 2-4 倍，但我觉得效果值得这个代价。
版本控制怎么办？ 老实说这是 HTML 最大的劣势之一——HTML 的 diff 比 Markdown 嘈杂得多，也更难评审。
怎么让 Claude 符合我的审美 / 不要做得很丑？ 前端设计插件（frontend design plugin）能帮 Claude 产出好看的 HTML 文件。但要匹配你公司自己的风格，可以让 Claude 顺着你的代码库做出一份单文件的设计系统 HTML。然后把这个设计系统文件作为参考，喂给其他 HTML 文件去用。
保持在环中
上面说了这么多，其实我用 HTML 真正的原因是：我感觉自己跟 Claude 之间的”环”连接得更紧了。我曾一度担心，自己已经不再认真读方案了，恐怕只能放任 Claude 自己做选择。
但现在我可以高兴地说，恰恰相反——使用 HTML 时我比以往任何时候都更感觉自己在环中（in the loop）。希望你也一样。