文章作者：Thariq

文章编译、来源：0x9999in1，ME News

Markdown 已经成为智能体（Agents）与我们交流时使用的主要文件格式。它简单、便携，具备一定的富文本能力，且非常便于你编辑。Claude 甚至在使用 ASCII 码在 Markdown 文件中绘制图表方面，表现得出奇地好。

但随着智能体变得越来越强大，我开始觉得 Markdown 变成了一种具有局限性的格式。我发现阅读超过百行的 Markdown 文件非常困难。我渴望更丰富的可视化效果、色彩和图表，并且希望能轻松地分享它们。

我也越来越少自己动手去编辑这些文件，而是将它们用作规范说明、参考文件、头脑风暴的产出等。当我真的需要修改时，我通常也是写提示词（Prompt）让 Claude 来修改，这就抹杀了 Markdown 最大的优势之一。

我开始倾向于使用 HTML 作为输出格式而不是 Markdown，并且我看到 Claude Code 团队的其他成员也越来越多地这样做，以下是原因。

为什么选择 HTML？

信息密度

与 Markdown 相比，HTML 能够传达丰富得多的信息。除了标题排版等简单的文档结构外，它还能呈现各种其他信息，例如：

• 使用表格（tables）呈现表格数据
• 使用 CSS 呈现设计数据
• 使用 SVG 呈现插图
• 使用 script 标签呈现代码片段
• 使用 HTML 元素结合 Javascript + CSS 实现交互
• 使用 SVG 和 HTML 呈现工作流
• 使用绝对定位和 Canvas 呈现空间数据
• 使用 img 标签呈现图像

我甚至敢说，Claude 能读取的信息中，几乎没有什么是不能用 HTML 高效呈现出来的。这使它成为模型向你传达深度信息以及供你审阅的一种极其高效的方式。

我发现，如果无法使用 HTML，模型可能会在 Markdown 中采用一些效率低下的方式，比如绘制 ASCII 图表，或者我最喜欢的一个例子——像这张 Claude Code 截图里那样，用 Unicode 字符来估算和展示颜色。

（附图：Claude Code 试图在 Markdown 中显示颜色）

视觉清晰度与阅读便利性

随着 Claude 能够处理更复杂的工作，它编写的规范和计划也越来越庞大。在实践中，我发现自己往往没有耐心去读超过 100 行的 Markdown 文件，我也绝对无法让我组织里的其他人去读它。

但 HTML 文档阅读起来要容易得多。Claude 可以对其结构进行视觉层面的组织，使其非常适合通过标签页、插图、链接等进行导航。它甚至可以做成移动端响应式的，让你根据设备的尺寸形态以不同的方式阅读。

分享的便利性

Markdown 文件很难分享，因为大多数浏览器无法在原生状态下很好地渲染它们。你通常不得不将它们作为电子邮件或消息的附件发送。

而对于 HTML，只要你上传文件（例如上传到 S3 等云存储），你就可以轻松分享链接。你的同事可以在他们喜欢的任何地方打开它并轻松查阅。如果你的规范文档、报告或 PR（Pull Request）说明是 HTML 格式的，别人真正去阅读它的概率会高得多。

双向交互

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

你可以阅读我关于 Playgrounds 的帖子以查看这种双向交互的示例：https://x.com/trq212/status/2017024445244924382

数据摄取

为什么使用 Claude Code 而不是 ClaudeAI 或 Claude Design 等工具来生成 HTML 文件？最大的原因之一是 Claude Code 能够摄取极大的上下文。

例如，在写这篇文章时，我让 Claude Code 浏览我的代码文件夹，找到我生成的所有 HTML 文件，对它们进行分组和分类，然后生成一个包含每种类型代表性图表的 HTML 文件。你在本文中看到的图表就是这一操作的直接成果。

除了文件系统之外，Claude Code 还可以利用你的 MCPs（如 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 进行头脑风暴，并探索不同的设计方向。然后我会让它将其中一个方案展开，也许是制作视觉草图或代码片段。最后，当我感觉方向正确时，我会让它写一份实施计划。当我对计划满意后，我会创建一个新会话，并将所有这些文件传给它去执行。

在进行验证时，我也会要求负责验证的智能体读取这些文件，这样它对需要完成的内容就会有更全面的上下文理解。

提示词示例：

适用场景：

• 探索在代码中实现某项功能的其他方案
• 探索多种视觉设计

代码审查与理解

在 Markdown 文件中阅读代码非常吃力。但是借助 HTML，我们可以渲染差异（Diffs）、注释、流程图、模块关系等。你可以利用这一点来理解智能体编写的代码，进行代码审查，或者向审查你代码的同事解释你的 PR。我发现这通常比 GitHub 默认的代码差异视图效果更好，我现在在提交的每个 PR 中都会附带一个 HTML 代码说明文件。

提示词示例：

适用场景：

• 创建 PR 时撰写说明
• 审查他人的 PR
• 理解代码中的特定复杂主题

设计与原型

Claude Design 是基于 HTML 构建的，因为 HTML 在设计方面具有极强的表现力，即便你的最终落地平台不是网页（HTML）。Claude 可以用 HTML 快速勾勒出设计草图，然后用你选择的语言（如 React、Swift 等）将其写出来。

你还可以对交互进行原型设计，例如动画效果、用户动作等。考虑让 Claude 制作滑块、控制旋钮等，以便你精确调试出你想要的参数。

提示词示例：

适用场景：

• 创建设计系统工件
• 调整 UI 组件
• 组件库可视化
• 快速构建有趣的动画原型

报告、研究与学习

Claude Code 极其擅长跨多个数据源综合信息，并将其转化为具有极佳可读性的报告。你可以提示 Claude 搜索你的 Slack、代码库、Git 历史记录或互联网，并将其用于为你自己、高管层或你的团队生成非常易于阅读的报告。

你可以将其组装成一份长篇 HTML 文档、一个交互式的解释性页面、甚至是一份幻灯片演示文稿（Deck）。让 Claude 使用 SVG 绘制图表来帮助数据可视化。

例如，针对我关于提示词缓存（Prompt Caching）的系列文章，我让 Claude 在读取了相关的 Git 历史记录后，为我准备了一份 HTML 格式的深度研究文件，详细列出了我们对提示词缓存所做的所有更改。

提示词示例：

适用场景：

• 总结某项功能是如何运作的
• 向我解释一个晦涩的概念
• 向你的老板提交周报
• 向领导层提交的事故分析报告（Incident reports）
• 生成 SVG 插图、流程图、技术架构图等

自定义编辑界面

有时，纯粹用文本框很难准确描述你想要的效果。在这种情况下，我会让 Claude 为我正在处理的特定数据构建一个“用完即走”的专属编辑器。它不是一个成熟的产品，也不是一个可重用的工具，而是一个仅为当前这项任务量身定制的单一 HTML 文件。

这里的诀窍始终是以“数据导出”作为闭环：包含一个“复制为 JSON”或“复制为提示词”的按钮，把我在 UI 界面里做的任何操作变回可以粘贴进 Claude Code 的文本结构。

提示词示例：

适用场景：

• 对任何内容进行重新排序、分类或分组分桶（如工单、测试用例、反馈意见等）
• 编辑结构化配置（功能开关、环境变量、带有约束条件的 JSON/YAML）
• 通过实时预览来微调提示词、模板或文案
• 整理和清洗数据集，批准/拒绝数据行，为示例打标签，并导出所选项
• 对文档、音视频转录稿或代码差异进行标注，并导出标注内容
• 挑选那些用纯文本极难表达的参数值：颜色代码、动画缓动曲线、裁剪区域坐标、Cron 定时任务表达式、正则表达式。

常见问题解答

我一直在跟很多人分享我是如何转投 HTML 怀抱的，在此期间我也遇到了一些被反复问及的问题。

• 这会不会降低 Token 的使用效率？
• 虽然 Markdown 通常消耗的 Token 更少，但我发现 HTML 所增加的表现力，以及它大幅提高了我去阅读文档的意愿，意味着我总体上获得了更好的输出结果。在 Opus 4.7 模型 100 万 Token 的庞大上下文窗口下，这部分增加的 Token 消耗其实是无感的。
• 那你现在什么时候还会用 Markdown？
• 老实说，我几乎在所有事情上都已经完全弃用 Markdown 了，不过在这个问题上，我可能属于极端的“HTML 原教旨主义者”。
• 我该如何查看生成的 HTML 文件？
• 我通常直接在本地的浏览器中打开它（你也可以直接让 Claude 帮你打开），如果你想要生成一个可分享的链接，可以将其上传到 S3 等服务。
• 生成这个是不是比生成 Markdown 耗时更长？
• 确实耗时更长！生成 HTML 的时间可能是 Markdown 的 2 到 4 倍，但我发现最终的结果值得这多出来的等待时间。
• 版本控制怎么处理？
• 说实话，这是使用 HTML 最大的一处劣势。与 Markdown 相比，HTML 的代码差异（Diffs）非常杂乱，且极难在代码审查中阅读。
• 我该如何让 Claude 迎合我的审美 / 不要把界面做得太丑？
• 前端设计插件有助于 Claude 制作出精良的 HTML 文件。但如果你想与你们公司的视觉风格保持一致，你可以让 Claude 浏览你的代码库，由此创建一个全局的“设计系统 HTML 文件”。之后，你可以将该设计系统文件作为上下文参考，让它去生成其他的 HTML 文件。

保持深度参与感

说了这么多，我认为我使用 HTML 的最根本原因在于，它让我感觉自己能更紧密地留在与 Claude 的交互反馈循环中（Stay in the loop）。我曾一度担心，因为我不再深入细读那些冗长的文本计划，我最终只能彻底放手让 Claude 替我做所有的决定。

但我现在非常高兴地表示，相反，通过使用 HTML，我感觉自己前所未有地掌握着主动权和参与感。希望你们也能有同样的体验。