为何Claude Code中HTML比Markdown更有效

3. 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 标签的代码片段
• 使用 JavaScript + CSS 的 HTML 元素交互
• 使用 SVG 和 HTML 的工作流程
• 使用绝对定位和 Canvas 的空间数据
• 使用图片标签的图像

我甚至可以说，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 artifact”。

诀窍在于知道你想要 artifact 做什么以及你将如何使用它。随着时间的推移，你可能会形成一个技能，但现在我建议从零开始提示，以掌握如何在不同情况下使用它。

使用场景

为了更具体，我针对不同使用场景制作了许多不同的 HTML 文件。你可以在这里查看所有文件：https://thariqs.github.io/html-effectiveness/ ，下面是概述。

规范、规划与探索

HTML 是 Claude 深入探索问题的丰富画布。当我开始处理一个问题时，我不会只做一个简单的 Markdown 计划，而是期望制作一个 HTML 文件网络。例如，我可能会先让 Claude Code 进行头脑风暴，并创建一些探索不同选项的内容。然后我会要求它更深入地展开其中一个选项，可能制作线框图或代码片段。最后，当我感觉良好时，我会要求它编写一个实现计划。当我对计划满意时，我会创建一个新的会话，并将所有这些文件传递给它来实现。

在验证时，我也会让验证 agent 读取这些文件，这样它就会对所需内容有更广泛的上下文。

示例提示：

• 我不确定入门屏幕应该采用什么方向。生成 6 种截然不同的方法——改变布局、风格和密度——并将它们作为一个 HTML 文件以网格形式展示，以便我可以并排比较。为每个方法标注其做出的权衡。
• 在一个 HTML 文件中创建一个全面的实现计划，一定要制作一些线框图，展示数据流，并添加我可能想查看的重要代码片段。让它易于阅读和理解。

使用场景：

• 探索用代码实现某功能的其他方法
• 探索多种视觉设计

代码审查与理解

在 Markdown 文件中阅读代码可能很困难。但通过 HTML，我们可以渲染差异、注释、流程图、模块等。利用这一点来理解 agent 编写的代码、获取代码审查，或者向审查你代码的人解释一个 PR。我发现这通常比默认的 GitHub diff 视图效果更好，现在我为每个 PR 都附上一个 HTML 代码解释器。

示例提示：

帮我审查这个 PR，创建一个描述它的 HTML artifact。我对流式/背压逻辑不太熟悉，所以请重点说明。渲染实际的 diff，并添加行内边距注释，根据严重程度对发现的问题进行颜色编码，以及任何其他可能需要的元素来很好地传达这个概念。

使用场景：

• 创建 PR
• 审查 PR
• 理解代码中的某个主题

设计与原型

Claude Design 基于 HTML，因为 HTML 在设计方面极具表现力，即使你的最终界面不是 HTML。Claude 可以用 HTML 勾勒设计，然后用你选择的语言（如 React、Swift 等）编写。

你还可以制作交互原型，例如动画、动作等。考虑要求 Claude 制作滑块、旋钮等来精确调整你想要的参数。

示例提示：

我想制作一个结账按钮的原型，点击时它会播放一个动画，然后快速变成紫色。创建一个 HTML 文件，包含几个滑块和选项，让我可以尝试这个动画的不同设置，并提供一个复制按钮来复制效果好的参数。

用于：

• 构建设计系统 artifact
• 调整组件
• 可视化组件库
• 制作有趣的动画原型

报告、研究与学习

Claude Code 非常擅长综合多个数据源的信息，并将其转化为可读性强的报告。你可以让 Claude 搜索你的 Slack、代码库、git 历史、互联网等，并利用它为自己、领导层或团队生成极具可读性的报告。

你可以将其组织成一份长 HTML 文档、交互式解释器，甚至幻灯片/演示文稿。要求 Claude 使用 SVG 制作图表来帮助可视化。例如，在我关于提示缓存的文章中，我让 Claude 在读取 git 历史后，准备一份深入的 HTML 格式的研究文件供我阅读。

示例提示：我不理解我们的速率限制器实际是如何工作的。阅读相关代码并生成一个 HTML 解释页面：包含Token桶流程的图表、注释过的 3-4 个关键代码片段，以及在底部的“注意事项”部分。优化为适合一次性阅读。

用于：

• 总结功能工作原理
• 解释某个概念
• 向老板汇报每周状态
• 向领导层报告事件
• SVG 插图、流程图、技术图表等

自定义编辑界面

有时很难纯粹在文本框中描述你想要的东西。在这种情况下，我会让 Claude 为我正在做的具体事情构建一个一次性的编辑器。不是产品，也不是可复用的工具，而是一个针对这一数据专门构建的单个 HTML 文件。

诀窍总是以导出功能结束：一个“复制为 JSON”或“复制为提示”的按钮，将我在 UI 中所做的操作转换回可以粘贴到 Claude Code 的内容。

示例提示：

• 我需要重新排定这 30 个 Linear 工单的优先级。给我做一个 HTML 文件，每个工单作为一个可拖拽的卡片，分布在“现在 / 下一步 / 之后 / 砍掉”列中。先按你的最佳猜测进行预排序。添加一个“复制为 markdown”按钮，导出最终排序，并为每个桶附带一行理由。
• 这是我们的功能开关配置。为它构建一个基于表单的编辑器，按区域分组标志，显示它们之间的依赖关系，如果我启用一个依赖前置条件关闭的标志，则发出警告。添加一个“复制差异”按钮，只给出更改的键。
• 我正在调整这个系统提示。制作一个并排编辑器：左侧是可编辑的提示，高亮显示变量插槽，右侧是三个示例输入，实时重新渲染填充后的模板。添加一个字符/Token 计数器和一个复制按钮。

用于：

• 重新排序、分类或分组任何事物（工单、测试用例、反馈）
• 编辑结构化配置（功能标志、环境变量、带约束的 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 文件。但要匹配你自己公司的风格，你可以通过将 Claude 指向你的代码库来创建一个统一的设计系统 HTML 文件。然后你可以将该设计系统文件作为其他 HTML 文件的参考。

保持参与

以上所有这些，我想说的是，我使用 HTML 的真正原因是，我感觉与 Claude 的互动更加紧密了。我曾开始担心，因为我不再深入阅读计划，我将不得不让 Claude 自行做出选择。

但我很高兴地说，在使用 HTML 时，我感觉比以往任何时候都更加投入。我希望你也如此。

• 原文链接： x.com/trq212/status/2052...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～