相关链接：https://simonwillison.net/2026/May/8/unreasonable-effectiven…

使用 Claude Code：HTML 的惊人效力

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 呈现工作流程
• 使用绝对定位和 Canvas 呈现空间数据
• 使用 img 标签嵌入图片

我甚至认为，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 artifact“即可。关键在于，你要清楚自己希望这个 artifact 做什么，以及你打算如何使用它。随着时间推移，你可能会形成一套技巧，但目前我建议从零开始提示，先摸索出如何在不同场景中运用它。

使用场景

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

规格说明、规划与探索

HTML 是一块丰富的画布，让 Claude 可以深入探索问题。当我开始处理一个问题时，我期望生成一个由多个 HTML 文件组成的网络，而不是简单的 Markdown 计划。例如，我可能先让 Claude Code 进行头脑风暴，并创建一些不同选项的探索。然后让它深入展开其中一个，也许生成一些模型图或代码片段。最后，当我感觉满意时，再让它写一份实施计划。对计划满意后，我会开启一个新的会话，将所有这些文件传入，让它进行实施。在验证时，我也会让验证 Agent 读取这些文件，这样它就能对需求有更全面的上下文。

示例提示：

• 我不确定引导页（onboarding screen）应该朝哪个方向走。请生成 6 种截然不同的方案——布局、风格和信息密度各有差异——并将它们并排排列在一个 HTML 文件的网格中，方便我对比。每种方案都要标注它所做出的权衡。
• 请在 HTML 文件中创建一份详尽的实施计划，一定要包含一些模型图、展示数据流，并加入我可能需要审阅的重要代码片段。让它易于阅读和理解。

适用场景：

• 探索代码的不同实现方式
• 探索多种视觉设计方案

代码审查与理解

在 Markdown 文件中阅读代码比较困难。但有了 HTML，我们可以渲染 diff、注释、流程图、模块关系等。用它来理解 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 bucket 流程图、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 上下文窗口下，token 用量的增加在上下文窗口中几乎感觉不到。

你现在什么时候还会用 Markdown？ 说实话，我几乎已经完全停用 Markdown 了，不过我可能站在 HTML 最大化主义者这一端。

怎么查看 HTML 文件？ 我通常直接在浏览器中本地打开（可以让 Claude 帮你打开），如果需要分享链接，就上传到 S3。

生成时间不是比 Markdown 更长吗？ 确实更长！HTML 可能比 Markdown 需要多 2-4 倍的时间，但我发现结果是值得的。

版本控制怎么办？ 说实话，这是 HTML 最大的缺点之一——与 Markdown 相比，HTML 的 diff 噪音很大，审查起来比较困难。

怎么让 Claude 生成符合我审美的 HTML，避免做出来很难看？ 前端设计插件能帮助 Claude 生成更好看的 HTML 文件。但如果想匹配你公司自己的风格，可以让 Claude 分析你的代码库，生成一个设计系统 HTML 文件，然后将这个设计系统文件作为其他 HTML 文件的参考。

保持同步

以上种种，说到底，我使用 HTML 的真正原因是：它让我与 Claude 的协作更加同步。我曾经担心，由于我不再深入阅读计划文档，只好把所有决定都交给 Claude 自己做。但我很高兴地说，使用 HTML 之后，我反而比以往任何时候都更了解 Claude 的工作进展。希望你也能有同样的感受。