使用 Claude Code：HTML 的惊人效果

Markdown 已成为智能体与我们沟通时使用的主流文件格式。它简洁、可移植、具备一定的富文本能力，而且方便你编辑。Claude 甚至已经相当擅长在 markdown 文件中用 ASCII 绘制图表。

但随着智能体能力越来越强，我逐渐觉得 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 高效表示的。这使得 HTML 成为模型向你传达深度信息、以及你进行审查的一种高效方式。

我发现，如果无法做到这一点，模型可能会在 markdown 中做更低效的事情，比如 ASCII 图表，或者我最喜欢的——用 unicode 字符来估计颜色，就像下面这个 Claude Code 截图一样。

Claude Code 尝试在 markdown 中展示颜色

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 进行头脑风暴，创建一些不同选项的探索。然后我会要求它进一步展开其中一个选项，可能制作一些模型或代码片段。最后，当我感觉不错时，我会让它编写一个实现计划。当我对计划满意时，我会创建一个新的会话，并将所有这些文件传入供其实现。

在验证时，我也会要求验证代理读取这些文件，这样它就能对需求有更广泛的了解。

示例提示：

• 我不确定入职屏幕应该朝哪个方向。生成 6 种截然不同的方案——在布局、语气和密度上有所变化——并将它们排列在单个 HTML 文件的网格中，方便我并排比较。为每个方案标注它所做出的取舍。
• 创建一个详尽的实现计划 HTML 文件，确保制作一些模型，展示数据流，并添加我可能要审查的重要代码片段。要做到易读易消化。

使用场景：

• 探索在代码中实现某事物的其他方式
• 探索多种视觉设计

代码审查与理解

代码在 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 Code 读取 git 历史中我们对提示缓存所做的所有更改，然后准备一份深入的 HTML 研究文件供我阅读。

示例提示：

我不理解我们的速率限制器实际上是如何工作的。阅读相关代码并生成一个单独的 HTML 解释页面：一个令牌桶流程图、3-4 个关键代码片段并带注释，以及底部一个“陷阱”部分。针对一次性阅读的人进行优化。

使用此功能用于：

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

自定义编辑界面

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

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

示例提示：

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

使用此功能用于：

• 重新排序、分类或分组任何事物（工单、测试用例、反馈）
• 编辑结构化配置（功能开关、环境变量、带约束的 JSON/YAML）
• 调整提示、模板或文案，带有实时预览
• 整理数据集、审批/拒绝行、标记示例、导出选择结果
• 标注文档、转录文本或 diff，并导出标注
• 挑选那些难以用文字表达的值：颜色、缓动曲线、裁剪区域、cron 计划、正则表达式。

常见问题解答

我一直在向很多人介绍我如何切换到 HTML，并看到了一些反复出现的问题。

这样不是会消耗更多令牌吗？ 虽然 markdown 通常使用更少的令牌，但我发现 HTML 额外的表现力以及我阅读它的可能性大大提高，最终我获得了更好的输出。在 Opus 4.7 的 100 万上下文窗口中，增加的令牌使用量实际上并不明显。

你现在什么时候还使用 markdown？ 老实说，我已经几乎完全停止使用 markdown，但我可能属于 HTML 最大化主义者那一端。

我如何查看 HTML 文件？ 我通常在本地浏览器中打开它（你可以让 Claude 打开它），或者如果你想要一个可分享的链接，就上传到 S3。

生成 HTML 会不会比 markdown 更慢？ 确实会慢！HTML 可能比 Markdown 慢 2-4 倍，但我发现结果值得等待。

版本控制怎么办？ 这实际上是 HTML 最大的缺点之一，HTML 的 diff 噪声很大，相比 Markdown 不容易审查。

如何让 Claude 符合我的品味 / 不让它变得难看？ 前端设计插件可以帮助 Claude 制作好看的 HTML 文件。但要匹配你自己公司的风格，你可以通过指向你的代码库让 Claude 创建一个单一的设计系统 HTML 文件。然后你可以将该设计系统文件用作其他 HTML 文件的参考。

保持参与感

以上所有内容都在说明，我使用 HTML 的真正原因是我感觉自己与 Claude 的互动更加紧密。我曾担心，因为我已不再深入阅读计划，我只能让 Claude 自行决策。

但我很高兴地表示，在使用 HTML 时，我比以往任何时候都感觉更处于参与状态。希望你也如此。