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 展示的工作流程
- 使用绝对定位和画布展示的空间数据
- 使用图片标签展示的图像
我甚至可以说，几乎没有任何 Claude 能读取的信息集，是你无法用 HTML 高效表示的。这使得它成为模型向你传达深度信息以及你进行审查的一种高效方式。
我发现，如果无法做到这一点，模型可能会在 Markdown 中采用更低效的方式，比如 ASCII 图表，或者我最喜欢的——用 Unicode 字符来估算颜色，就像 Claude Code 的这个截图一样。
Claude Code 试图在 Markdown 中显示颜色
视觉清晰度与易读性
随着 Claude 能够处理更复杂的工作，它也在编写越来越大的规格说明和计划。实际上，我发现我通常不会真正阅读超过 100 行的 Markdown 文件，而且我肯定无法让组织中的其他人去阅读它。
但 HTML 文档更容易阅读，Claude 可以在视觉上优化结构，使其更适合通过标签页、插图、链接等方式进行导航。它甚至可以自适应移动端，让你根据不同的设备获得不同的阅读体验。
易于分享
Markdown 文件很难分享，因为大多数浏览器无法很好地原生渲染它们。你通常需要将它们作为附件添加到电子邮件或消息中。
而使用 HTML，只要你上传文件（例如上传到 S3），就可以轻松分享链接。你的同事可以在任何地方打开它，并轻松引用。
如果文件是 HTML 格式，别人真正阅读你的规格说明、报告或 PR 总结的可能性会高得多。
双向交互
HTML 允许你与文档进行交互，例如，你可以要求它添加滑块或旋钮来调整设计，或者允许你调整算法中的不同选项来观察效果。你还可以让它让你将这些更改复制到一个提示中，然后粘贴回 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 技能之类的东西。虽然这可能有一些价值，但我想强调的是，你不需要做太多事情就能让 Claude 做到这一点。你只需要告诉它“制作一个 HTML 文件”或“制作一个 HTML 制品”。
关键在于知道你想要这个制品做什么，以及你打算如何使用它。随着时间的推移，你可能会创建一个技能，但现在我建议你从头开始提示，以掌握如何在不同情况下使用它。
使用场景
为了更具体，我针对不同的使用场景制作了许多不同的 HTML 文件。你可以在这里查看所有文件：https://thariqs.github.io/html-effectiveness/，但以下是概述。
规格说明、规划与探索
HTML 是 Claude 深入探索问题的丰富画布。当我开始处理一个问题时，我不会只做一个简单的 Markdown 计划，而是期望制作一个 HTML 文件网络。例如，我可能会先让 Claude Code 进行头脑风暴，创建一些不同选项的探索。然后我会要求它进一步展开其中一个选项，可能制作一些模拟图或代码片段。最后，当我感觉良好时，我会要求它编写一个实施计划。当我对计划满意时，我会创建一个新的会话，并将所有这些文件传递给它来实施。
在验证时，我也会让验证 Agent 读取这些文件，这样它就能对所需内容有更广泛的了解。
示例提示：
- 我不确定引导屏幕应该采用什么方向。生成 6 种截然不同的方法——在布局、风格和信息密度上有所变化——并将它们以网格形式排列在一个 HTML 文件中，以便我可以并排比较。为每种方法标注其权衡之处。
- 在一个 HTML 文件中创建一个详尽的实施计划，确保制作一些模拟图，展示数据流，并添加我可能想要审查的重要代码片段。使其易于阅读和理解。
使用场景：
- 探索在代码中实现某功能的其他方式
- 探索多种视觉设计
代码审查与理解
在 Markdown 文件中阅读代码可能很困难。但使用 HTML，我们可以渲染差异、注释、流程图、模块等。利用这一点来理解 Agent 编写的代码、进行代码审查，或者向审查你代码的人解释 PR。我发现这通常比默认的 Github 差异视图效果更好，现在我提交的每个 PR 都会附带一个 HTML 代码解释器。
示例提示：
帮我审查这个 PR，创建一个描述它的 HTML 制品。我对流式/背压逻辑不太熟悉，所以请重点关注这部分。渲染实际的差异，并在页边距添加内联注释，根据严重程度对发现的问题进行颜色编码，以及任何其他可能有助于传达概念的内容。
使用场景：
- 创建 PR
- 审查 PR
- 理解代码中的某个主题
设计与原型
Claude Design 基于 HTML，因为 HTML 在设计方面具有极强的表现力，即使你的最终界面不是 HTML。Claude 可以用 HTML 勾勒出一个设计，然后用你选择的语言（如 React、Swift 等）编写出来。
你还可以制作交互原型，例如动画、动作等。考虑让 Claude 制作滑块、旋钮等，以精确调整你正在寻找的效果。
示例提示：
我想制作一个新的结账按钮原型，点击时它会播放一个动画，然后快速变成紫色。创建一个 HTML 文件，包含几个滑块和选项，让我可以尝试这个动画的不同参数，并提供一个复制按钮来复制效果良好的参数。
用于：
- 创建设计系统制品
- 调整组件
- 可视化组件库
- 制作有趣的动画原型
报告、研究与学习
Claude Code 非常擅长综合来自多个数据源的信息，并将其转换为易于阅读的报告。你可以提示 Claude 搜索你的 Slack、代码库、Git 历史、互联网等，并利用它为你自己、领导层、团队等生成极具可读性的报告。
你可以将其组装成一份长 HTML 文档、一个交互式解释器，甚至是一个幻灯片/演示文稿。让 Claude 使用 SVG 制作图表来帮助可视化。
例如，在我关于提示缓存的文章中，我让 Claude 在读取 Git 历史后，准备一份深入的 HTML 研究文件供我阅读，内容涵盖我们对提示缓存所做的所有更改。
示例提示：
我不明白我们的限速器实际上是如何工作的。阅读相关代码，生成一个单一的 HTML 解释页面：一个令牌桶流程的图表，3-4 个带注释的关键代码片段，以及底部的“注意事项”部分。优化它，让读者只看一次就能理解。
用于：
- 总结某个功能的工作原理
- 向我解释一个概念
- 向老板提交每周状态报告
- 向领导层提交事故报告
- SVG 插图、流程图、技术图表等
自定义编辑界面
有时很难仅通过文本框来描述你想要的东西。在这种情况下，我会让 Claude 为我正在处理的具体内容构建一个一次性的编辑器。不是产品，也不是可重复使用的工具，而是一个单一的 HTML 文件，专门为这一份数据量身定制。
诀窍总是以导出结束：一个“复制为 JSON”或“复制为提示”按钮，将我在 UI 中所做的任何操作转换回可以粘贴到 Claude Code 中的内容。
示例提示：
- 我需要重新排列这 30 个 Linear 工单的优先级。为我制作一个 HTML 文件，将每个工单作为可拖动的卡片，分布在“现在 / 下一步 / 稍后 / 放弃”列中。根据你的最佳猜测预先排序。添加一个“复制为 Markdown”按钮，导出最终排序，并为每个分组提供一行理由。
- 这是我们的功能标志配置。为其构建一个基于表单的编辑器，按区域对标志进行分组，显示它们之间的依赖关系，如果我启用了一个前提条件已关闭的标志，则发出警告。添加一个“复制差异”按钮，只给出更改过的键。
- 我正在调整这个系统提示。制作一个并排编辑器：左侧是可编辑的提示，高亮显示变量插槽；右侧是三个示例输入，实时重新渲染填充后的模板。添加一个字符/令牌计数器和一个复制按钮。
用于：
- 重新排序、分类或分组任何内容（工单、测试用例、反馈）
- 编辑结构化配置（功能标志、环境变量、带约束的 JSON/YAML）
- 调整提示、模板或文案，并实时预览
- 整理数据集、批准/拒绝行、标记示例、导出选择
- 注释文档、转录稿或差异，并导出注释
- 选择难以用文本表达的值：颜色、缓动曲线、裁剪区域、Cron 调度、正则表达式。
常见问题解答
我已经向很多人介绍了我如何转向 HTML，并且看到了一些反复出现的问题。
这不是更消耗令牌吗？
虽然 Markdown 通常使用更少的令牌，但我发现 HTML 更强的表现力以及我阅读它的可能性大大提高，这意味着我总体上获得了更好的输出。在 Opus 4.7 的 100 万上下文窗口中，增加的令牌使用量在上下文窗口中并不明显。
你现在什么时候使用 Markdown？
老实说，我几乎已经完全不使用 Markdown 了，但我可能属于 HTML 最大化主义的那一端。
如何查看 HTML 文件？
我通常直接在本地浏览器中打开它（你可以让 Claude 打开它），或者如果需要可分享的链接，就上传到 S3。
生成 HTML 不是比 Markdown 更耗时吗？
确实更耗时！HTML 的生成时间可能是 Markdown 的 2-4 倍，但我发现结果是值得的。
版本控制怎么办？
这确实是 HTML 最大的缺点之一，与 Markdown 相比，HTML 的差异噪声很大，难以审查。
如何让 Claude 符合我的品味 / 不让它变得难看？
前端设计插件有助于 Claude 制作出好的 HTML 文件。但要匹配你自己公司的风格，你可以通过让 Claude 指向你的代码库来创建一个单一的设计系统 HTML 文件。然后你可以将该设计系统文件作为其他 HTML 文件的参考。
保持参与
综上所述，我认为我使用 HTML 的真正原因是，我感觉与 Claude 的参与度更高了。我曾经开始担心，因为我不再深入阅读计划，所以我只能让 Claude 自行做出选择。
但我很高兴地说，在使用 HTML 时，我感觉比以往任何时候都更参与其中。希望你也如此。
