Markdown 已成为 Agent 与我们沟通的主导文件格式。它简单、可移植，具备一些富文本能力，而且易于编辑。Claude 甚至已经非常擅长在 markdown 文件中使用 ASCII 来绘制图表。
但随着 Agent 变得越来越强大，我越来越觉得 markdown 已经成为一种限制性格式。我发现超过一百行的 markdown 文件就很难读下去了。我想要更丰富的可视化、颜色和图表，并且希望能轻松地分享它们。
我也越来越多地不再亲自编辑这些文件，而是将它们用作规格说明、参考文件、头脑风暴的输出等。当我确实需要编辑时，通常也是让 Claude 来编辑，这实际上削弱了 markdown 最大的优势之一。
我开始更倾向于使用 HTML 而不是 Markdown 作为输出格式，并且发现 Claude Code 团队的其他人也越来越多地这样做，以下是原因。
（如果你想先看一些示例，可以在这里找到很多：thariqs.github.io/html-effect... ，但请务必回来看完为什么要这样做）
为什么选择 HTML？
信息密度
与 markdown 相比，HTML 能传达丰富得多的信息。它当然可以处理简单的文档结构（如标题和格式），但还能表示各种其他类型的信息：
- 使用表格展示表格数据
- 使用 CSS 展示设计数据
- 使用 SVG 绘制插图
- 使用 script 标签展示代码片段
- 使用 HTML 元素结合 JavaScript + CSS 实现交互
- 使用 SVG 和 HTML 展示工作流
- 使用绝对定位和画布展示空间数据
- 使用 image 标签展示图片
我甚至敢说，Claude 能读取的几乎所有信息，你都可以用 HTML 相当高效地表示。这使它成为模型与你进行深度信息沟通的高效方式。
我发现，在无法做到这一点的情况下，模型可能会在 markdown 中做一些低效的事情，比如 ASCII 图表，或者我最喜欢的------用 unicode 字符来估算颜色，就像下面这张 Claude Code 的截图。
视觉清晰度与可读性
随着 Claude 能够完成越来越复杂的工作，它也在编写越来越大的规格说明和计划。在实际使用中，我发现自己通常不会真正阅读超过 100 行的 markdown 文件，而且我确实无法让我组织中的其他人去读它。
但 HTML 文档更容易阅读，Claude 可以在视觉上优化结构，使其便于通过标签页、插图、链接等方式导航。它甚至可以做到移动端响应式，让你可以根据不同的设备形态以不同方式阅读。
易于分享
Markdown 文件很难分享，因为大多数浏览器不能原生良好地渲染它们。你通常不得不将它们作为附件添加到电子邮件或消息中。
而使用 HTML，只要上传文件（例如上传到 S3），你就可以轻松分享链接。你的同事可以在任何地方打开它并方便地引用。
如果你的规格说明、报告或 PR 说明是 HTML 格式的，有人真正去读它的概率要高得多。
双向交互
HTML 允许你与文档进行交互。例如，你可能想让它添加滑块或旋钮来调整设计，或者让你调整算法中的不同选项来查看结果。你还可以让它将修改后的内容复制到提示中，然后粘贴回 Claude Code。
阅读我关于 playground 的帖子，可以了解更多这种双向交互的示例：x.com/trq212/stat...
数据摄取
为什么使用 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 做到这一点。你只需要让它"make a HTML file"或"make a HTML artifact"。
关键在于知道你想要这个 artifact 做什么以及你打算如何使用它。随着时间推移你可能会制作一个 skill，但目前我建议直接从零开始提示，来掌握在不同场景下的使用方法。
使用场景
为了更具体地说明，我针对不同的使用场景制作了许多不同的 HTML 文件。你可以在这里查看所有内容：
规格、规划与探索
HTML 是一个丰富的画布，让 Claude 可以深入探索问题。当我开始处理一个问题时，我不再只做一个简单的 markdown 计划，而是预期会制作一系列 HTML 文件。例如，我可能先让 Claude Code 头脑风暴，创建不同选项的探索方案。然后让它在某个方向上进一步展开，可能制作原型图或代码片段。最后，当我感觉不错时，我会让它写一个实施计划。当我对计划满意时，我会创建一个新的会话，将所有这些文件传入让它实施。
在验证阶段，我也会让验证 Agent 读取这些文件，它会对需要做什么有更广泛的上下文。
示例提示：
- 我不确定引导页应该走哪个方向。生成 6 种明显不同的方案------在布局、语气和密度上都要不同------并将它们排列在一个 HTML 文件中，以便我可以并排比较。给每个方案标注它所做的权衡。
- 在 HTML 文件中创建一个详尽的实施计划，一定要做一些原型图，展示数据流，并添加我可能想审查的重要代码片段。让它易于阅读和消化。
适用场景：
- 探索代码实现的其他方式
- 探索多种视觉设计
代码审查与理解
代码在 Markdown 文件中可能很难阅读。但使用 HTML，我们可以渲染 diff、注释、流程图、模块等。用它来理解 Agent 编写的代码、进行代码审查，或向审查你代码的人解释 PR。我发现这通常比默认的 Github diff 视图效果更好，现在我在每个 PR 上都附上一个 HTML 代码说明文件。
示例提示：
帮我审查这个 PR，创建一个描述它的 HTML artifact。我对 streaming/backpressure 逻辑不太熟悉，所以重点关注那部分。渲染实际的 diff 并加上行内边距注释，按严重程度对发现进行颜色编码，以及其他可能有助于传达概念的内容。
适用场景：
- 创建 PR
- 审查 PR
- 理解代码中的某个主题
设计与原型
Claude Design 基于 HTML，因为 HTML 在设计方面具有极强的表现力，即使你的最终目标平台不是 HTML。Claude 可以先用 HTML 勾勒出设计，然后用你选择的语言编写，无论是 React、Swift 等。
你还可以原型化交互，比如动画、操作等。考虑让 Claude 制作滑块、旋钮等，来精确调整你想要的效果。
示例提示：
我想原型化一个新的结账按钮，点击后播放一个动画然后快速变成紫色。创建一个 HTML 文件，提供多个滑块和选项让我尝试这个动画的不同设置，给我一个复制按钮来复制效果好的参数。
适用于：
- 创建设计系统 artifact
- 调整组件
- 可视化组件库
- 原型化有趣的动画
报告、研究与学习
Claude Code 非常擅长跨多个数据源综合信息，并将其转化为可读性强的报告。你可以提示 Claude 搜索你的 Slack、代码库、git 历史、互联网等，用它为你自己、领导层、团队等生成极具可读性的报告。
你可以将其组装成长 HTML 文档、交互式说明甚至幻灯片/演示文稿的形式。让 Claude 使用 SVG 来绘制图表以辅助可视化。
例如，在我关于 prompt caching 的帖子中，我让 Claude 在阅读 git 历史后，准备了一份关于我们所有 prompt caching 变更的深度研究 HTML 文件。
示例提示：
我不理解我们的限流器实际上是如何工作的。阅读相关代码并生成一个 HTML 说明页面：一张 token-bucket 流程图，3-4 个带注释的关键代码片段，以及底部的"注意事项"部分。针对只读一次的人进行优化。
适用于：
- 总结某个功能的工作原理
- 向我解释一个概念
- 向老板提交每周状态报告
- 向领导提交事故报告
- SVG 插图、流程图、技术图表等
自定义编辑界面
有时候很难纯粹在文本框中描述你想要什么。在这种情况下，我会让 Claude 为我正在处理的具体内容构建一个一次性的编辑器。不是一个产品，或一个可复用的工具，而是一个单一的 HTML 文件，专门为这一份数据量身定制。
关键技巧总是以导出结束：一个"复制为 JSON"或"复制为 prompt"按钮，将你在 UI 中所做的操作转换回可以粘贴到 Claude Code 中的内容。
示例提示：
- 我需要重新排列这 30 个 Linear 工单。给我做一个 HTML 文件，把每个工单做成可拖动的卡片，放在 Now / Next / Later / Cut 列中。按你的最佳判断预排序。添加一个"复制为 markdown"按钮，导出最终排序并附上每个分桶的一句话理由。
- 这是我们的 feature flag 配置。构建一个基于表单的编辑器，按区域对 flag 分组，显示它们之间的依赖关系，如果启用了前置条件未开启的 flag 就警告我。添加一个"复制 diff"按钮，只给出变更的键。
- 我在调优这个系统 prompt。做一个并排编辑器：左边是可编辑的 prompt，高亮变量插槽，右边是三个样本输入，实时渲染填充后的模板。添加字符/Token 计数器和复制按钮。
适用于：
- 对任何东西（工单、测试用例、反馈）进行重新排序、分类或分桶
- 编辑结构化配置（feature flag、环境变量、带约束的 JSON/YAML）
- 调优 prompt、模板或文案并实时预览
- 策划数据集、批准/拒绝行、标记示例、导出选择
- 标注文档、转录或 diff 并导出标注
- 选择用文本难以表达的值：颜色、缓动曲线、裁剪区域、cron 时间表、正则表达式
常见问题
我一直在向很多人介绍我转向 HTML 的经历，也看到了一些反复出现的问题。
不是更耗费 token 吗？
虽然 markdown 通常使用更少的 token，但我发现 HTML 增加的表现力以及我真正去阅读它的可能性大大提高，使得整体输出质量更好。在 Opus 4.7 的 1M 上下文窗口中，增加的 token 使用量在上下文窗口中并不明显。
你现在什么时候还用 markdown？
说实话，我已经几乎在所有场景下都停止使用 markdown 了，但我可能处于 HTML 极端主义者的那一端。
如何查看 HTML 文件？
我通常直接在浏览器中本地打开它（你可以让 Claude 帮你打开），或者如果想获得可分享的链接就上传到 S3。
生成不是比 markdown 更耗时吗？
确实更耗时！HTML 的生成可能比 Markdown 慢 2-4 倍，但我发现结果是值得的。
版本控制怎么办？
这确实是 HTML 最大的缺点之一，HTML 的 diff 比 Markdown 更嘈杂也更难审查。
如何让 Claude 符合我的品味 / 不做得很丑？
frontend design 插件可以帮助 Claude 制作好看的 HTML 文件。但要匹配你自己公司的风格，你可以让 Claude 指向你的代码库来创建一个设计系统 HTML 文件。然后你可以将该设计系统文件作为其他 HTML 文件的参考。
保持参与感
以上所有内容归根结底是，我认为我使用 HTML 的真正原因是我感觉自己与 Claude 更加紧密地参与其中。我曾经开始担心，因为我不再深入阅读计划，我将不得不让 Claude 自行做出选择。
但我很高兴地说，使用 HTML 反而让我感觉自己比以往任何时候都更加参与其中。希望你也一样。