Markdown 已经成了 agent 与我们沟通时最常用的文件格式。它简单、便携，具备一些富文本能力，也很容易编辑。Claude 甚至已经非常擅长在 Markdown 文件里用 ASCII 画图了。
但随着 agent 变得越来越强，我开始觉得 Markdown 反而成了一种受限的格式。超过一百行的 Markdown 文件，我读起来会很吃力。我想要更丰富的可视化、颜色和图表，也希望它们能被轻松分享。
而且我自己也越来越少亲自编辑这些文件了。更多时候，它们是规格说明、参考文件、头脑风暴输出等。即使我真的要改，通常也是让 Claude 来改，这就削弱了 Markdown 最大的优势之一。
我开始更偏好让输出使用 HTML，而不是 Markdown。现在我也越来越常看到 Claude Code 团队里的其他人这样做。原因如下。
（如果你想先看一些例子，可以在这里看到很多：https://thariqs.github.io/html-effectiveness。不过记得回来继续读读为什么。）
为什么是 HTML？
信息密度
相比 Markdown，HTML 能传达丰富得多的信息。它当然能表达标题、格式等简单文档结构，但也能表示各种其他信息，例如：
- 用表格表达表格数据
- 用 CSS 表达设计数据
- 用 SVG 表达插图
- 用 script 标签表达代码片段
- 用 HTML 元素配合 JavaScript + CSS 表达交互
- 用 SVG 和 HTML 表达工作流
- 用绝对定位和 canvas 表达空间数据
- 用 image 标签表达图片
我甚至会说，几乎不存在某种 Claude 能读懂、却无法用 HTML 相当高效表达的信息集合。这让 HTML 成为模型向你传达深层信息、也让你审阅这些信息的一种高效方式。
我发现，如果不能这样做，模型就可能在 Markdown 里采用一些效率更低的方式，比如 ASCII 图。或者我最喜欢的：像这张 Claude Code 截图里那样，用 Unicode 字符来估算颜色。
视觉清晰度与阅读便利性
随着 Claude 能完成越来越复杂的工作，它也会写出越来越大的规格说明和计划。实践中我发现，超过 100 行的 Markdown 文件，我往往不会真正读完；而且我当然也没法让组织里的其他人去读它。
但 HTML 文档要容易读得多。Claude 可以用视觉方式组织结构，让它非常适合通过标签页、插图、链接等方式浏览。它甚至可以做成移动端响应式，这样你在不同设备形态下可以用不同方式阅读。
易于分享
Markdown 文件其实很难分享，因为大多数浏览器无法很好地原生渲染它们。你通常必须把它们作为附件加到邮件或消息里。
而使用 HTML，只要你上传这个文件（比如上传到 S3），就可以轻松分享链接。同事可以在任何地方打开，也很容易引用。
如果你的规格说明、报告或 PR 说明是 HTML，别人真正读它的概率会高得多。
双向交互
HTML 可以让你与文档交互。比如你可能希望它加入滑块或旋钮，用来调整设计；或者允许你调节算法里的不同选项，看看会发生什么。你还可以让它提供一个功能，把这些修改复制成 prompt，再粘回 Claude Code。
想看这种双向交互的例子，可以读读我关于 playground 的帖子：https://x.com/trq212/status/2017024445244924382
数据摄取
为什么要用 Claude Code 来生成 HTML 文件，而不是用 ClaudeAI 或 Claude Design？最大的原因之一，是 Claude Code 能摄取的上下文非常多。
例如，在写这篇文章时，我让 Claude Code 读取我的代码文件夹，找出我生成过的所有 HTML 文件，把它们分组归类，然后生成一个 HTML 文件，用图表表示每一种类型。你在这篇文章里看到的图，正是这一过程的直接结果。
除了文件系统，Claude Code 还可以通过 MCP（比如 Slack、Linear 等）、你的网页浏览器（通过 Chrome 里的 Claude）、你的 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 或代码片段。最后，当我觉得方向不错时，我会让它写一份实现计划。等我对计划满意后，我会创建一个新 session，把这些文件全部传进去，让它实现。
验证时，我也会让验证 agent 读入这些文件。这样它会对需要完成的事情拥有更广泛的上下文。
示例 prompt：
- 我不确定 onboarding 页面该走哪个方向。生成 6 种明显不同的方案——在布局、语气和信息密度上都要有差异——并把它们放在一个 HTML 文件的网格里，这样我可以并排比较。给每个方案标注它所做的取舍。
- 创建一份详尽的 HTML 实现计划，一定要加入一些 mockup，展示数据流，并添加我可能想要审阅的重要代码片段。让它容易阅读和消化。
使用场景：
- 探索某段代码的其他实现方式
- 探索多种视觉设计
代码审查与理解
代码放在 Markdown 文件里可能很难读。但有了 HTML，我们可以渲染 diff、注释、流程图、模块等。可以用它来理解 agent 写出的代码、做代码审查，或者向审查你代码的人解释一个 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：
我想原型化一个新的结账按钮。点击时它会播放一个动画，然后快速变成紫色。创建一个 HTML 文件，里面放几个滑块和选项，让我尝试这段动画的不同参数，并提供一个复制按钮，用来复制效果不错的参数。
适用于：
- 创建设计系统 artifact
- 调整组件
- 可视化组件库
- 原型化令人愉悦的动画
报告、研究与学习
Claude Code 非常擅长综合多个数据源的信息，并把它们转换成易读的报告。你可以让 Claude 搜索你的 Slack、代码库、git 历史、互联网等，然后用它为你自己、领导层、团队等生成极其易读的报告。
你可以把它组织成长篇 HTML 文档、交互式讲解，甚至幻灯片/deck。可以让 Claude 使用 SVG 绘制图表，帮助可视化。
例如，在我写 prompt caching 相关文章时，我让 Claude 读取 git 历史后，为我准备了一份关于 prompt caching 所有变更的深入 HTML 研究文件。
示例 prompt：
我不理解我们的 rate limiter 到底是怎么工作的。读取相关代码，然后生成一个单页 HTML 讲解：包含 token-bucket 流程图、3 到 4 段带注释的关键代码片段，以及底部的“注意事项”部分。优化目标是让人只读一遍就能理解。
适用于：
- 总结某个功能如何工作
- 向我解释一个概念
- 给老板写周报
- 给领导层写事故报告
- SVG 插图、流程图、技术图表等
自定义编辑界面
有时，只靠文本框很难描述你想要什么。这种情况下，我会让 Claude 为我正在处理的那件具体事情搭一个一次性编辑器。它不是产品，也不是可复用工具，而是一个专门服务于这一份数据的单个 HTML 文件。
诀窍是最后一定要有导出功能：一个“copy as JSON”或“copy as prompt”按钮，把我在 UI 里做的操作转回可以粘贴到 Claude Code 里的内容。
示例 prompt：
- 我需要重新排序这 30 个 Linear ticket。做一个 HTML 文件，把每个 ticket 做成可拖拽卡片，放到 Now / Next / Later / Cut 几列里。先按你的最佳判断预排序。加入一个“copy as markdown”按钮，导出最终排序，并为每个 bucket 给出一句理由。
- 这是我们的 feature flag 配置。为它构建一个基于表单的编辑器，按领域对 flag 分组，展示它们之间的依赖关系，并在我启用某个前置条件关闭的 flag 时警告我。加入一个“copy diff”按钮，只输出被修改的 key。
- 我正在调这个 system prompt。做一个并排编辑器：左侧是可编辑 prompt，并高亮变量槽；右侧放三个示例输入，实时重新渲染填充后的模板。加入字符/token 计数器和复制按钮。
适用于：
- 重新排序、分诊或分桶任何东西（ticket、测试用例、反馈）
- 编辑结构化配置（feature flag、环境变量、有约束的 JSON/YAML）
- 调整 prompt、模板或文案，并提供实时预览
- 筛选数据集、批准/拒绝行、标注样本、导出选中结果
- 标注文档、转录稿或 diff，并导出标注
- 选择那些很难用文字表达的值：颜色、缓动曲线、裁剪区域、cron 时间表、正则表达式。
常见问题
我已经向很多人讲过我如何切换到 HTML，也看到过一些反复出现的问题。
这不是更浪费 token 吗？
虽然 Markdown 通常使用更少 token，但我发现 HTML 额外的表达能力，以及它显著提高我实际阅读输出的概率，意味着整体上我能得到更好的结果。对于 Opus 4.7 的 100 万上下文窗口来说，增加的 token 使用量在上下文窗口里并不明显。
你现在什么时候还用 Markdown？
老实说，我几乎已经完全不再用 Markdown 处理大多数事情了，不过我可能算是 HTML 极端主义者那一边。
我要怎么看 HTML 文件？
我通常直接在本地浏览器打开它（你也可以让 Claude 帮你打开），或者如果想分享链接，就上传到 S3。
这不会比生成 Markdown 更慢吗？
确实会更慢！HTML 可能比 Markdown 慢 2 到 4 倍，但我发现结果值得。
版本控制怎么办？
老实说，这是 HTML 最大的缺点之一。相比 Markdown，HTML diff 噪声很大，也更难审查。
我要怎么让 Claude 符合我的品味 / 不要做得很丑？
frontend design 插件能帮助 Claude 做出好看的 HTML 文件。但如果你想匹配自己公司的风格，可以让 Claude 读取你的代码库，创建一个单独的设计系统 HTML 文件。之后你就可以把这个设计系统文件作为其他 HTML 文件的参考。
保持在循环中
上面所有这些，其实是在说：我使用 HTML 的真正原因，是它让我觉得自己与 Claude 的协作更在循环中。我曾开始担心，因为我已经不再深入阅读计划，所以只能放手让 Claude 自己做选择。
但我很高兴地说，使用 HTML 之后，我反而比以往任何时候都更感觉自己在循环中。希望你也一样。