使用 Claude Code：HTML为什么更有效？

Markdown 已经成为 Agent 与我们沟通时使用的主导文件格式。它简单、可移植，具备一定的富文本能力，而且方便你编辑。Claude 甚至已经非常擅长在 Markdown 文件里用 ASCII 做图了。

但随着 Agent 越来越强大，我觉得 Markdown 已经成为一种束缚。超过一百行的 Markdown 文件我就很难读进去。我想要更丰富的可视化、颜色和图表，还想要能方便地分享它们。

而且我也越来越不是自己在编辑这些文件了，而是把它们当作规格说明、参考文档、头脑风暴的产出物来使用。当我真的需要修改时，通常也是让 Claude 来改，这就消除了 Markdown 最大的一个优势。

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

（如果你想先看一些例子，可以去这里查看，看完记得回来读更多原因。）

HTML 的表达力

HTML 相比 Markdown 能够传达丰富得多的信息。它当然可以做简单的文档结构，比如标题和格式，但还能表示各种其他信息：

用 table 做表格数据。用 CSS 做设计数据。用 SVG 做插图。用 script 标签嵌入代码片段。用 HTML 元素加上 JavaScript + CSS 实现交互。用 SVG 和 HTML 做工作流。用绝对定位和 canvas 做空间数据。用 image 标签嵌入图片。

我甚至敢说，几乎没有 Claude 能读取的信息是你不能用 HTML 相当高效地表示出来的。这让 HTML 成为模型向你在深度上传达信息、以及你来审阅信息的一种高度高效的途径。

我发现在无法做到这一点的情况下，模型会在 Markdown 中做一些效率更低的事情，比如画 ASCII 图表，或者我最喜欢的——用 Unicode 字符来估算颜色，就像这张 Claude Code 截图所示。

可读性

随着 Claude 能做更复杂的工作，它写的规格说明和计划也越来越大。实际上，我发现超过一百行的 Markdown 文件我基本不会真正读完整，更别提让组织里的其他人来读了。

但 HTML 文档就好读得多。Claude 可以用标签页、插图、链接等方式组织视觉结构，让导航变得轻松。它甚至可以做响应式设计，让你根据不同的设备来阅读。

可分享性

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

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

你的规格说明、报告或 PR 描述被别人真正阅读的概率，用 HTML 格式会比 Markdown 高得多。

交互性

HTML 可以让你与文档进行交互。比如你可以让它添加滑块或旋钮来调整设计，或者让你调整算法中的不同选项来看看效果。你还可以让它把你的修改复制到一个 prompt 中，然后粘贴回 Claude Code。关于这种双向交互的更多例子，可以阅读我的 playgrounds 文章。

数据获取

为什么用 Claude Code 来生成 HTML 文件，而不是 Claude AI 或 Claude Design 呢？最大的原因之一是 Claude Code 能获取大量上下文。比如写这篇文章的时候，我让 Claude Code 读取我的代码文件夹，找到我生成的所有 HTML 文件，分组归类，然后做一个包含各种类型图表的 HTML 文件。你在本文中看到的图表就是直接的结果。

除了文件系统，Claude Code 还可以通过 MCP（比如 Slack、Linear 等）、浏览器（Claude in Chrome）、Git 历史等获取额外上下文。

用 Claude 做 HTML 文档本身也更有趣，让我感觉自己更深度地参与了创作过程，光是这一点就足够了。

我有点担心人们读了这篇文章会把它变成一个 /html skill 之类的。虽然这样做可能有一定价值，但我想强调的是，你不需要做太多就能让 Claude 做到这些。你只需要对它说"做一个 HTML 文件"或"做一个 HTML artifact"就行了。

关键是知道你想让 artifact 做什么，以及你可能会怎么使用它。随着时间推移你可能会做一个 skill，但现在我建议直接从零开始 prompt，去感受在不同场景下怎么用。

为了更具体，我为不同用例做了很多不同的 HTML 文件。你可以在[这里]查看全部，下面是概览。

HTML 是 Claude 深入探索问题的丰富画布。当我开始研究一个问题时，我不会只做一个简单的 Markdown 计划，而是期望做一系列 HTML 文件。比如我可能先让 Claude Code 头脑风暴，对不同的方案做一些探索。然后让它深入扩展其中一个，可能做 mockup 或代码片段。最后当我感觉不错时，再让它写一个实现计划。当我对计划满意后，我会创建一个新 session，把所有这些文件传进去让它实现。

在做验证时，我也会让验证 Agent 读取这些文件，这样它对需要做什么会有更全面的上下文理解。

Prompt 示例：

我不确定新手引导屏幕该往哪个方向走。生成 6 个明显不同的方案——变化布局、风格和密度——放在一个 HTML 文件里排成网格，方便我并排对比。给每个方案标注它所做的权衡。

用例：

用不同方式在代码中实现某个功能。探索多种视觉设计方案。

Code Explainer

在 Markdown 文件中阅读代码很困难。但有了 HTML，我们可以渲染 diff、注释、流程图、模块等。用它来理解 Agent 写的代码，做 Code Review，或者向代码审查者解释一个 PR。我发现这通常比 GitHub 默认的 diff 视图效果更好，我现在给每个 PR 都会附上一个 HTML 代码解释器。

Prompt 示例：

帮我审查这个 PR，创建一个 HTML artifact 来描述它。我不太熟悉 streaming / backpressure 的逻辑，请重点讲这块。渲染实际的 diff，用行内边距标注，按严重程度用颜色编码，再加一些其他能清楚传达概念的内容。

用例：

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

Claude Design

Claude Design 基于 HTML，因为 HTML 在设计方面极其富有表现力，即使你的最终界面不是 HTML。Claude 可以用 HTML 画出一个设计方案，然后用你选择的语言来写它，不管是 React、Swift 还是其他的。

你还可以做交互原型，比如动画、动作等。考虑让 Claude 做滑块、旋钮等，让你精确调出你想要的效果。

Prompt 示例：

我想做一个新的结算按钮的原型，点击后播放一个动画然后快速变成紫色。做一个 HTML 文件，带几个滑块和选项让我尝试这个动画的不同效果，加一个复制按钮让我复制那些效果好的参数。

适用场景：

创建设计系统 artifact。调整组件。可视化组件库。做有趣的动画原型。

Reports & Explainers

Claude Code 非常擅长跨多个数据源综合信息，转化为可读的报告。你可以让 Claude 搜索你的 Slack、代码库、Git 历史、互联网等，然后用它生成极其易读的报告——给你自己、给领导、给你的团队等。

它可以组装成一个完整的 HTML 文档、一个交互式解释器，甚至是一个幻灯片。让 Claude 用 SVG 做图表来可视化。比如，关于 prompt caching 的文章，我让 Claude 在阅读了 Git 历史后为我准备一份关于我们所有 prompt caching 变更的深度研究 HTML 文件。

Prompt 示例：

我不理解我们的限流器到底是怎么工作的。阅读相关代码，生成一个 HTML 解释页面：token bucket 流程图、3-4 个关键代码片段的注释，底部加一个"坑点"部分。为只读一次的人优化。

适用场景：

总结某个功能的工作原理。给我解释一个概念。给老板的周报。给领导的事故报告。SVG 插图、流程图、技术图表等。

Playgrounds

有时候很难在纯文本框里描述你想要什么。这种情况下，我会让 Claude 给我正在做的东西建一个一次性编辑器。不是产品，不是可复用工具，而是一个单独的 HTML 文件，专门为这一份数据定制。

诀窍永远是最后加一个导出功能：一个"复制为 JSON"或"复制为 prompt"的按钮，把你在 UI 中做的任何操作转回可以粘贴到 Claude Code 中的内容。

Prompt 示例：

我需要重新排列这 30 张 Linear 工单。给我做一个 HTML 文件，每张工单是一张可拖动的卡片，分布在 Now / Next / Later / Cut 四个列中。按你的最佳猜测预排序。加一个"复制为 Markdown"按钮，导出最终排序并为每个分组附上一行理由。

这是我们的 feature flag 配置。给我做一个表单编辑器，按功能区分组，显示它们之间的依赖关系，如果我启用了前置条件未开启的 flag，给出警告。加一个"复制 diff"按钮，只给我有变化的 key。

我在调这个 system prompt。做一个左右分栏编辑器：左边是可编辑的 prompt，变量槽高亮显示；右边是三个示例输入，实时重新渲染填充后的模板。加一个字符/token 计数器和一个复制按钮。

适用场景：

重新排序、分类或分桶（工单、测试用例、反馈等）。编辑结构化配置（feature flags、环境变量、有约束条件的 JSON/YAML）。调 prompt、模板或文案，带实时预览。整理数据集，逐行审批/拒绝、打标签、导出选择。标注文档、转录稿或 diff，并导出标注。挑选在文本中难以表达的值：颜色、缓动曲线、裁剪区域、cron 表达式、正则表达式等。

常见问题

我告诉过很多人我已经转向 HTML，有几个问题被反复问到。

不太费 token 吗？

虽然 Markdown 通常用更少的 token，但我发现 HTML 带来的表达力提升，加上我真正去阅读的概率大大增加，意味着整体输出效果更好。有了 Opus 4.7 的 100 万 token 上下文窗口，多花的 token 在上下文中几乎感觉不到。

现在什么时候还用 Markdown？

说实话，我几乎已经完全不再用 Markdown 了，但我可能算是 HTML 极端主义者那一端的。

怎么查看 HTML 文件？

我一般直接在浏览器中打开本地文件（你可以让 Claude 帮你打开），或者上传到 S3 如果你想有个可分享的链接。

生成时间不会更长吗？

确实会更长！HTML 可能比 Markdown 多花 2-4 倍时间，但我觉得结果值得。

版本控制怎么办？

这确实是 HTML 最大的缺点之一。HTML 的 diff 比 Markdown 噪杂且难以审查。

怎么让 Claude 符合我的审美/不做得太丑？

前端设计插件能帮助 Claude 做出好的 HTML 文件。但要匹配你自己公司的风格，你可以让 Claude 读取你的代码库，创建一个单独的设计系统 HTML 文件。然后你可以把这个设计系统文件作为其他 HTML 文件的参考。

总结

以上这些想说的是，我觉得我用 HTML 的真正原因是——我感到自己与 Claude 的协作更加紧密了。我一度开始担心，因为我已经不再深入阅读计划了，我就只能把选择权交给 Claude。

但我很高兴地告诉你，使用 HTML 后，我感觉比以往任何时候都更融入其中。希望你也是。