使用 Claude Code：HTML 的不合理有效性

来源: Claude Blog | 作者: Thariq Shihipar | 日期: 2026-05-20 原文链接: https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html

一句话总结

随着 AI agent 能力增强，HTML 正在取代 Markdown 成为更优的 agent 输出格式——它提供更高的信息密度、更好的可读性、更方便的分享方式和双向交互能力，让人类能真正保持在 AI 工作的回路中。

速览

Markdown 的瓶颈已现——超过 100 行的 Markdown 文件几乎没人读完，且无法承载丰富的可视化和交互需求
HTML 的信息密度远超 Markdown——表格、CSS、SVG、JavaScript 交互、canvas 空间数据，几乎没有 Claude 能读取但 HTML 无法表达的信息
可读性决定信息是否真正被消费——HTML 支持标签页导航、插图、链接和响应式设计，让大型规格文档真正被阅读
分享便利性是实际推动力——HTML 文件上传后可直接通过链接分享，同事可在任何设备打开，而 Markdown 需要作为附件发送
双向交互创造了专属编辑环境——通过滑块、旋钮等 HTML 控件，用户可以实时调整参数并将结果复制回 Claude Code
Claude Code 的上下文摄取能力是关键差异化优势——相比 Claude.ai，它能利用文件系统、MCP、浏览器和 git 历史生成更有上下文的 HTML
六大核心用例已成体系——规格规划、代码审查、设计原型、报告研究、自定义编辑界面，以及学习讲解
Token 成本已不是障碍——Opus 4.7 的 100 万 token 上下文窗口使 HTML 的额外 token 开销可忽略不计
HTML 的本质价值是让人保持在回路中——不是格式偏好问题，而是人在 AI 工作流中的参与度问题

核心内容

Markdown 为什么不够用了

作者 Thariq Shihipar 是 Claude Code 团队成员。他观察到一个趋势：随着 agent 能力增强，人类反而越来越不仔细阅读 agent 的输出。Markdown 作为 agent 与人类沟通的主流格式，有三个根本性限制：

超过 100 行就很难阅读，更难让团队其他人阅读
无法承载丰富的可视化——模型被迫退化为 ASCII 图表甚至用 Unicode 字符”估算颜色”
难以分享——浏览器原生不渲染 Markdown，只能作为附件发送

更关键的转变是：作者越来越少亲自编辑这些文件，而是将它们用作规格说明和参考，编辑时也是让 Claude 来做。这削弱了 Markdown”易编辑”这个最大优势。

HTML 的五大核心优势

信息密度：HTML 几乎可以表达 Claude 能读取的所有类型信息——表格数据、CSS 设计、SVG 插图、JavaScript 交互、canvas 空间数据、工作流图。作者认为”几乎没有 Claude 能读取但无法用 HTML 高效表示的信息集”。

视觉清晰度：Claude 可以用标签页、插图、链接来组织 HTML 文档的视觉结构，使其成为理想的导航体验。还支持响应式设计，可根据设备形态调整阅读方式。

易于分享：上传 HTML 文件后可直接分享链接，同事可在任何设备打开。作者指出：“如果你的规格说明、报告或 PR 文档是 HTML 格式的，别人真正阅读的可能性要高得多。”

双向交互：HTML 允许添加滑块、旋钮等控件来调整设计参数或算法选项，并可以复制更改到提示词中粘贴回 Claude Code。这为特定问题创造了专属编辑环境。

数据摄取：Claude Code 相比 Claude.ai 的核心优势是上下文摄取能力——它可以访问文件系统、MCP（Slack、Linear 等）、浏览器（Claude in Chrome）和 git 历史。作者写这篇文章时就让 Claude Code 扫描他的代码文件夹，找出所有 HTML 文件并分类生成图表。

入门方式：从简单提示开始

不需要复杂设置。只需提示 Claude “制作一个 HTML 文件”或”制作一个 HTML artifact”。关键是知道你希望 artifact 做什么以及如何使用。随时间推移可围绕重复模式构建 skill，但从头开始提示是了解不同用例的好方式。

六大实践用例及具体提示词

规格说明、规划和探索

作者不再写单一的 Markdown 计划，而是制作一系列 HTML 文件：先让 Claude Code 头脑风暴不同方案，再深入展开某个方向制作模型和接口示例，最后编写实现计划。验证时也让验证 agent 读取这些文件获得更广泛的上下文。

示例提示词：

“我不确定引导页面该走什么方向。生成 6 种截然不同的方案——在布局、语调和密度上做变化——并将它们作为单个 HTML 文件以网格形式排列，让我可以并排比较。标注每种方案所做的权衡取舍。”
“用 HTML 文件创建一个全面的实现计划，确保做一些模型，展示数据流并添加我可能想审查的重要代码片段。让它易于阅读和消化。“

代码审查和理解

HTML 可以渲染 diff、注释、流程图和模块结构，远比 Markdown 中的代码块可读。

示例提示词：“帮我审查这个 PR，创建一个描述它的 HTML artifact。我对 streaming/backpressure 逻辑不太熟悉，所以重点关注那部分。渲染实际的 diff 并附上行内边距注释，按严重程度用颜色编码发现的问题。“

设计和原型

Claude Design 本身就基于 HTML。Claude 可以用 HTML 草拟设计然后转写为 React、Swift 等。可以原型化动画、交互，通过滑块和旋钮精确调整。

示例提示词：“我想原型化一个新的结账按钮，点击时它播放一个动画然后快速变成紫色。创建一个 HTML 文件，带有几个滑块和选项让我尝试不同选项，给我一个复制按钮来复制效果好的参数。“

报告、研究和学习

Claude Code 擅长跨多个数据源综合信息。可以输出为长 HTML 文档、交互式讲解器甚至幻灯片。

示例提示词：“我不理解我们的速率限制器实际上是如何工作的。阅读相关代码并生成一个 HTML 讲解页面：一个令牌桶流程图、3-4 个关键代码片段并附注释，以及底部的’注意事项’部分。针对只阅读一次的人进行优化。“

自定义编辑界面

为特定数据构建一次性 HTML 编辑器，关键是始终以导出结尾——一个”复制为 JSON”或”复制为提示词”按钮，将 UI 操作转回可粘贴到 Claude Code 的内容。

示例提示词：

“我需要重新排列这 30 个 Linear 工单的优先级。给我做一个 HTML 文件，每个工单作为可拖拽卡片分布在’现在/下一步/以后/砍掉’四列中。添加一个’复制为 Markdown’按钮导出最终排序。”
“这是我们的功能开关配置。为它构建一个表单编辑器，按区域分组，显示依赖关系，如果我启用了前置条件未开启的标志则警告我。”
“我正在调整这个系统提示词。做一个并排编辑器：左侧可编辑提示词，变量槽位高亮；右侧三个示例输入实时渲染。添加字符/token 计数器和复制按钮。”

适用场景包括：重排优先级、编辑结构化配置、调整提示词/模板、策划数据集、注释文档、选择难以用文字表达的值（颜色、缓动曲线、裁剪区域、cron 计划、正则表达式）。

Token 成本与格式选择的现实考量

作者回应了”HTML 效率更低”的质疑：虽然 Markdown 使用更少的 token，但 HTML 的额外表达力加上更高的阅读意愿意味着总体更好的输出。Opus 4.7 的 100 万 token 上下文窗口使这个问题不再显著。

作者自称是”HTML 极端主义者”——已经几乎完全停止使用 Markdown。他的规划方式也从单一计划文件变成了多个 HTML 文件的集合：实现计划、UI 探索、设计清单，这些文件既是工作产物也是未来参考。

名言金句

“I’ve found that Markdown has become an increasingly restrictive format.”

“There is almost no set of information that Claude can read that you cannot efficiently represent with HTML.”

“The chance of someone actually reading your spec, report, or PR writeup is much higher if it’s in HTML.”

“The real reason I use HTML instead of Markdown is that it helps me feel much more in the loop with Claude.”

“The trick is always to end with an export: a ‘copy as JSON’ or ‘copy as prompt’ button.”

可行建议

立即尝试：下次让 Claude Code 生成输出时，要求它”制作一个 HTML 文件”而非 Markdown
从代码审查开始：让 Claude 用 HTML 渲染 PR diff，附带颜色编码的注释——这是最直接感受差异的场景
构建一次性编辑器：当需要调整参数或重排优先级时，让 Claude 生成带交互控件的 HTML 文件，始终包含”复制”导出按钮
用 HTML 做规划：将单一 Markdown 计划替换为多个 HTML 文件——探索、实现计划、设计清单分别独立
利用 Claude Code 的上下文优势：让它读取代码库、git 历史或 MCP 数据源后再生成 HTML 报告

资源清单

使用 Claude Code：HTML 的不合理有效性

Claude Code 团队成员为何以及如何使用 HTML 代替 Markdown 来产出更丰富、更易读且更容易分享的输出。

Markdown 已经成为 agent 与人类沟通的主流文件格式。它简洁、可移植、具有一定的富文本能力且易于编辑。Claude 甚至在 Markdown 文件中使用 ASCII 制作图表方面变得出奇地擅长。

但随着 agent 变得越来越强大，我发现 Markdown 已经成为一种越来越受限的格式。具体来说，我发现很难阅读超过一百行的 Markdown 文件；我想用 Claude 生成更丰富的可视化效果、颜色和图表；而且我希望能更方便地分享这些输出。

此外，我越来越少亲自编辑这些文件，而是将它们用作规格说明和参考文件。当我确实需要编辑时，通常是提示 Claude 来编辑，这就削弱了 Markdown 最大的优势之一。

相反，我开始偏好使用 HTML 作为输出格式而非 Markdown，并且越来越多地看到 Claude Code 团队的其他成员也在采用这种模式。在这篇文章中，我将分享我们团队为什么以及如何使用 HTML 来产出更丰富、更易读的 Claude Code 输出。如果你想跟着做，可以开始使用这些常见用例的 HTML 文件模板。

为什么使用 HTML？

有几个因素使 HTML 比 Markdown 更适合我现在使用 Claude Code 所做的工作，包括需要或涉及以下方面的任务：

信息密度

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

使用表格呈现表格数据
使用 CSS 呈现设计数据
使用 SVG 呈现插图
使用 script 标签呈现代码片段
使用 HTML 元素配合 JavaScript + CSS 实现交互
使用 SVG 和 HTML 呈现工作流
使用绝对定位和 canvas 呈现空间数据
使用 image 标签呈现图片

在我看来，Claude 能读取的几乎所有信息集，你都可以用 HTML 高效地表示。这使它成为模型向你传达深入信息以及你审阅这些信息的高效方式。

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

视觉清晰度和易读性

随着 Claude 能够处理更复杂的工作，它也能够编写越来越大的规格说明和计划。我发现我往往不会真正阅读超过 100 行的 Markdown 文件，而且我肯定无法让组织中的其他人去阅读它。

但 HTML 文档要容易阅读得多，因为 Claude 可以通过标签页、插图和链接来组织视觉结构，使其成为理想的导航方式。它甚至可以做响应式设计，让你可以根据不同的设备形态以不同方式阅读。

易于分享

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

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

如果你的规格说明、报告或 PR 文档是 HTML 格式的，别人真正阅读的可能性要高得多。

双向交互

HTML 还可以让你与文档交互；例如，你可能想让它添加滑块或旋钮来调整设计，或者让你调整算法中的不同选项来查看会发生什么。你还可以要求它让你将这些更改复制到提示词中，然后粘贴回 Claude Code。

在需要的时候，这可以让你为正在解决的特定问题创建单独的编辑环境。

数据摄取

使用 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 文件”或”制作一个 HTML artifact”。关键在于了解你希望 artifact 做什么以及你可能如何使用它。随着时间推移，围绕重复出现的模式构建一个 skill 可能是有意义的，但从头开始提示是了解它在不同用例中如何工作的好方法。

用例

为了使这种方法更加具体，以下是一些我认为使用 HTML 文件比 Markdown 更合理的示例用例。你还可以在 GitHub 上查看这些用例的 gallery，点击这里。

规格说明、规划和探索

HTML 是 Claude 深入研究问题的丰富画布。当我开始处理一个问题时，我不是写一个简单的 Markdown 计划，而是期望制作一系列 HTML 文件。例如，我可能从让 Claude Code 头脑风暴开始，创建一些不同选项的探索。然后我会让它更深入地展开其中一个，也许制作模型或类型接口的示例。最后，当我感觉不错时，我会让它编写实现计划。当我对计划满意后，我会创建一个新会话并传入所有这些文件让它实现。

在验证时，我也会让验证 agent 读取这些文件，它将对需要什么有更广泛的上下文。

示例提示词：

我不确定引导页面该走什么方向。生成 6 种截然不同的方案——在布局、语调和密度上做变化——并将它们作为单个 HTML 文件以网格形式排列，让我可以并排比较。标注每种方案所做的权衡取舍。
用 HTML 文件创建一个全面的实现计划，确保做一些模型，展示数据流并添加我可能想审查的重要代码片段。让它易于阅读和消化。

适用于：

探索代码中某个功能的其他实现方式
同时试验多种视觉设计

代码审查和理解

代码在 Markdown 文件中可能很难阅读，但使用 HTML，我们可以渲染差异对比、注释、流程图和模块。使用 HTML 来理解 agent 编写的代码、审查代码或向审查你代码的人解释 PR。

示例提示词：

帮我审查这个 PR，创建一个描述它的 HTML artifact。我对 streaming/backpressure 逻辑不太熟悉，所以重点关注那部分。渲染实际的 diff 并附上行内边距注释，按严重程度用颜色编码发现的问题，以及其他任何有助于很好地传达概念的内容。

适用于：

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

设计和原型

Claude Design 基于 HTML，因为 HTML 在设计表达方面极其强大，即使你的最终呈现层面不是 HTML。Claude 可以用 HTML 草拟设计，然后用你选择的语言编写，无论是 React、Swift 等。

你还可以原型化交互，如动画、操作等。考虑让 Claude 制作滑块、旋钮等，以精确调整你正在寻找的效果。

示例提示词：

我想原型化一个新的结账按钮，点击时它播放一个动画然后快速变成紫色。创建一个 HTML 文件，带有几个滑块和选项让我尝试这个动画的不同选项，给我一个复制按钮来复制效果好的参数。

适用于：

创建设计系统 artifact
调整组件
可视化组件库
原型化动画

报告、研究和学习

Claude Code 在跨多个数据源综合信息并将其转换为可读报告方面非常有效。你可以提示 Claude 搜索你的 Slack、你的代码库、git 历史或互联网，并用它来生成易于阅读的报告。

你可以将其组装成长 HTML 文档、交互式讲解器甚至幻灯片/演示文稿的形式。要求 Claude 使用 SVG 绘制图表来帮助可视化。

示例提示词：

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

适用于：

编写功能总结
生成讲解器
起草每周状态报告
创建事故报告
制作 SVG 插图、流程图和技术图表

自定义编辑界面

有时候纯粹在文本框中描述你想要什么是很困难的。对于这种用例，我经常会让 Claude 为我正在处理的确切内容构建一个一次性编辑器：不是产品，也不是可重用的工具，而是一个为这一条数据量身定制的 HTML 文件。

诀窍是始终以导出结尾：一个”复制为 JSON”或”复制为提示词”按钮，将你在 UI 中所做的一切转回可以粘贴到 Claude Code 或提交到文件的内容。你保持在回路中，但回路变得更紧密。

示例提示词：

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

适用于：

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

常见问题

以下是我最常被问到的关于在 Claude Code 中使用 HTML 的问题，以及我在日常实践中得出的答案：

效率不是更低吗？

虽然 Markdown 通常使用更少的 token，但我发现 HTML 的额外表达力以及我更高的阅读意愿意味着我总体上获得了更好的输出。有了 Opus 4.7 的 100 万 token 上下文窗口，增加的 token 使用量在上下文窗口中并不真正显著。

你现在什么时候还用 Markdown？

老实说，我几乎已经停止在所有场景中使用 Markdown，但我可能处于 HTML 极端主义者的一端。

这就是你替代规划的方式吗？

我发现，我倾向于不再使用单一的计划，而是为计划的不同部分/阶段准备几个不同的 HTML 文件。例如，我可能用 HTML 做一个实现计划，然后用另一个文件探索 UI，最后制作一个列出所有设计的 HTML 组件。我倾向于保留这些文件作为未来的参考，也用于验证。

与 Claude 保持在回路中

以上所有这些都是为了说明，我使用 HTML 而非 Markdown 的真正原因是它帮助我感觉与 Claude 保持更紧密的联系。随着 Claude 承担更多工作，我注意到自己阅读计划的仔细程度在下降，我想要一种方式来保持参与它的选择，而不是简单地把它们交出去。HTML 正好解决了这个问题。我现在比以往任何时候都更觉得自己在回路中。

从 Claude Code 开始。

本文由技术人员 Thariq Shihipar 撰写，表达了他个人对在 Claude Code 中使用 HTML 文件的看法和偏好。