Markdown 已成为智能体（agent）与人类沟通时最主流的文件格式。它简洁、可移植、具备一定的富文本能力，而且易于编辑。Claude 甚至已经非常擅长在 Markdown 文件中使用 ASCII 字符绘制图表。

但随着智能体能力越来越强，我逐渐觉得 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 展示工作流程
• 使用绝对定位和画布表示空间数据
• 使用 img 标签嵌入图像

我甚至可以说，Claude 能读取的几乎所有信息集合，几乎都可以用 HTML 高效地表示出来。这使得 HTML 成为模型向你传递深度信息、供你审阅的一种高效方式。

我发现，在无法使用 HTML 的情况下，模型可能会在 Markdown 中采取效率更低的方式，比如绘制 ASCII 图表，或者我最喜欢的一种方式：用 Unicode 字符估算颜色（如这张来自 Claude Code 的截图所示）。

视觉清晰度与易读性

随着 Claude 能够处理越来越复杂的工作，它生成的规范和计划也越来越长。在实践中，我发现我通常不会真正去阅读超过 100 行的 Markdown 文件，更不用说让组织中的其他人去读了。

但 HTML 文档则容易阅读得多。Claude 可以通过标签、插图、链接等方式，以视觉上最理想的组织结构来呈现内容。它甚至可以实现移动端响应式布局，让你根据不同设备形态以不同方式阅读。

分享便捷性

Markdown 文件很难分享，因为大多数浏览器无法原生很好地渲染它们。你通常只能将它们作为附件添加到邮件或消息中。

而 HTML 只要上传文件（例如上传到 S3），就可以轻松分享链接。你的同事可以在任何地方打开并轻松引用。

如果你的规范、报告或 PR 说明是用 HTML 编写的，别人实际阅读的可能性会高得多。

双向交互

HTML 允许你与文档进行交互。例如，你可以要求它添加滑块或旋钮来调整设计，或者让你调整算法中的不同选项以观察结果。你还可以要求它将这些更改复制到一个提示中，以便粘贴回 Claude Code。

想了解更多关于这种双向交互的示例，请阅读我的“Playground”系列文章：https://x.com/trq212/status/2017024445244924382

数据摄取能力

为什么选择用 Claude Code 生成 HTML 文件，而不是 Claude AI 或 Claude Design？其中一个最重要原因是：Claude Code 能够摄取大量上下文信息。

例如，在撰写本文时，我让 Claude Code 读取我的代码文件夹，找出所有已生成的 HTML 文件，对它们进行分组和分类，然后创建一个包含所有类型图表的 HTML 文件。本文中的图表正是这一过程的直接成果。

除了文件系统，Claude Code 还能通过 MCP（如 Slack、Linear 等）、浏览器（配合 Chrome 中的 Claude）、Git 历史等渠道获取额外上下文。

它令人愉悦

用 Claude 制作 HTML 文档不仅更有趣，也让我感觉更投入、更参与到创作过程中——仅这一点就足够了。

如何开始？

我有点担心人们读了这篇文章后，会把它变成某种 /html 技能或类似的东西。虽然这可能有一定价值，但我想强调的是：你其实不需要做太多就能让 Claude 做到这一点。你只需简单地告诉它“生成一个 HTML 文件”或“创建一个 HTML 产物（artifact）”即可。

关键在于：你要清楚自己想要这个产物做什么，以及如何使用它。你可能最终会为此创建一个技能，但目前我建议直接从零开始提示，以熟悉在不同场景下的用法。

使用场景

为了让上述内容更具体，我为不同使用场景制作了许多不同的 HTML 文件。你可以在此查看全部：https://thariqs.github.io/html-effectiveness/，以下是概览：

规范、规划与探索

HTML 是 Claude 深入探索问题的绝佳画布。当我开始处理一个问题时，不再满足于简单的 Markdown 计划，而是期望创建一组 HTML 文件构成的“网络”。例如，我可能会先让 Claude Code 进行头脑风暴，生成几种不同方案的探索；然后让它进一步展开其中一种，可能包括制作 mockup 或代码片段；最后，当我感觉不错时，再让它撰写一份实施计划。当我对计划满意后，会开启一个新会话，将所有这些文件传入，让它执行实现。

在验证阶段，我也会让验证智能体读取这些文件，这样它就能获得更全面的上下文，了解所需内容。

示例提示：

• 我不确定登录页该朝哪个方向设计。请生成 6 种截然不同的方案——在布局、语气和信息密度上有所差异——并将它们以网格形式呈现在一个 HTML 文件中，以便我并排比较。为每种方案标注其做出的权衡。
• 创建一个详尽的实施计划 HTML 文件，务必包含一些 mockup、展示数据流，并添加你可能想审阅的重要代码片段。确保内容易于阅读和理解。

适用场景：

• 探索代码中其他实现方式
• 探索多种视觉设计方案

代码审查与理解

在 Markdown 文件中阅读代码可能很困难。但使用 HTML，我们可以渲染差异（diff）、注释、流程图、模块等。这可用于理解智能体编写的代码、进行代码审查，或向他人解释你的 PR。我发现这种方式通常比 GitHub 默认的 diff 视图效果更好，现在我每次提交 PR 都会附上一个 HTML 代码解释器。

示例提示：

帮我审查这个 PR，创建一个描述它的 HTML 产物。我对流式处理/背压逻辑不太熟悉，请重点解释这部分。用行内边注渲染实际的 diff，按严重程度对发现的问题进行颜色编码，并添加任何其他有助于清晰传达概念的内容。

适用场景：

• 创建 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）
• 调整提示、模板或文案，并实时预览
• 筛选数据集、批准/拒绝行、标记示例、导出所选内容
• 注释文档、转录稿或 diff，并导出注释
• 选择难以用文本表达的值：颜色、缓动曲线、裁剪区域、Cron 调度、正则表达式等。

常见问题

我一直在向很多人介绍我转向 HTML 的做法，也遇到了一些重复的问题。

这样不是更耗 token 吗？
虽然 Markdown 通常使用更少的 token，但我发现 HTML 更强的表达能力，以及我更可能去阅读它的现实，意味着我最终获得的质量更高的输出。在 Opus 4.7 的 100 万上下文窗口下，增加的 token 使用量在整体上下文中并不明显。

你现在还在什么时候用 Markdown？
说实话，我几乎已经完全停止使用 Markdown 了，可能我算是 HTML 的极端拥护者。

我如何查看 HTML 文件？
我通常直接在本地浏览器中打开（你可以让 Claude 帮你打开），或者上传到 S3 以获取可分享的链接。

生成 HTML 不比 Markdown 更慢吗？
确实更慢！HTML 的生成时间可能是 Markdown 的 2–4 倍，但我发现结果值得等待。

版本控制怎么办？
这确实是 HTML 最大的缺点之一。与 Markdown 相比，HTML 的 diff 噪声更大，更难审查。

如何让 Claude 符合我的审美 / 不让它做得难看？
前端设计插件可以帮助 Claude 制作优质的 HTML 文件。但如果你想匹配自己公司的风格，可以创建一个单一的设计系统 HTML 文件：让 Claude 分析你的代码库，然后以此作为其他 HTML 文件的参考。

保持同步

综上所述，我认为我使用 HTML 的真正原因是：我感觉自己与 Claude 的协作更加紧密了。我曾担心，由于不再深入阅读计划，我可能只能任由 Claude 做决定。

但很高兴地说，使用 HTML 后，我感觉比以往任何时候都更“在状态”。希望你也如此。