用HTML替代Markdown作为Claude Code输出格式

# 使用Claude Code：HTML的惊人效力

此文现已同步发布于Claude博客。

Markdown已成为智能体与我们沟通所使用的主流文件格式。它简洁、可移植，具备一定的富文本能力，也便于编辑。Claude甚至已经出人意料地擅长在Markdown文件中用ASCII字符绘制图表。（https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html）

然而，随着智能体变得越来越强大，我愈发感到Markdown已成为一种限制性格式。超过一百行的Markdown文件，我很难读下去。我希望拥有更丰富的可视化效果、颜色和图表，并且希望能够轻松地分享它们。

我也越来越少亲自编辑这些文件，而是将它们用作规格说明、参考文件、头脑风暴输出等。即便需要修改，通常也是提示Claude来完成，这使Markdown最大的优势之一也随之消失。

我已经开始更倾向于使用HTML作为输出格式，而非Markdown，并且越来越多地看到Claude Code团队中的其他人也在这样做，原因就在于此。

（如果你想先看一些示例，可以在这里找到很多：https://thariqs.github.io/html-effectiveness, 但请务必回来继续阅读，了解更多背后的原因。）（https://thariqs.github.io/html-effectiveness/）

# 为什么选择HTML？

## 信息密度

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

- 使用表格呈现表格数据

- 使用CSS呈现设计数据

- 使用SVG绘制插图

- 使用script标签嵌入代码片段

- 结合JavaScript和CSS，通过HTML元素实现交互

- 使用SVG和HTML呈现工作流程

- 使用绝对定位和画布呈现空间数据

- 使用图片标签嵌入图像

我甚至可以说，几乎没有任何Claude能够读取的信息集合，是无法用HTML高效表示的。这使得HTML成为模型向你传达深度信息、供你审阅的一种高效方式。

我发现，在无法使用HTML的情况下，模型可能会在Markdown中采取一些效率较低的方式，比如绘制ASCII图表，或者我最喜欢举的例子——用Unicode字符来估算颜色，就像这张Claude Code截图中所示的那样。

## 视觉清晰度与阅读便利性

随着Claude能够完成越来越复杂的工作，它所撰写的规格说明和计划文档也变得越来越长。在实际操作中，我发现我往往不会真正阅读超过一百行的Markdown文件，更不可能让组织中的其他人去读它。

而HTML文档则更易于阅读，Claude可以通过选项卡、插图、链接等方式，将结构在视觉上组织得便于浏览。它甚至可以做到移动端自适应，让你根据不同设备形态以不同方式阅读。

## 分享便利性

Markdown文件很难分享，因为大多数浏览器无法原生地良好渲染它们。你通常不得不将其作为附件添加到电子邮件或消息中。

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

如果你的规格说明、报告或PR说明是HTML格式，别人实际阅读它的可能性会大大提高。

## 双向交互

HTML 可以让你与文档进行交互，例如你可以要求它添加滑块或旋钮来调整设计，或者让你调整算法中的不同选项以查看效果。你还可以要求它将这些更改复制到一个提示词中，粘贴回 Claude Code。

阅读我关于 playgrounds 的文章，查看这种双向交互的示例：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 进行头脑风暴，创建一些不同选项的探索。然后让它进一步展开其中某个方向，也许制作一些原型或代码片段。最后，当我感觉满意时，我会让它编写一个实施计划。当我对计划满意后，我会创建一个新的会话，并将所有这些文件传入以供实施。

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

示例提示词：

- 我不确定入门界面应该采用哪个方向。生成 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 说明文档：包含令牌桶流程图、3–4 段关键代码片段及注释，以及底部的"注意事项"部分。针对只读一次的读者进行优化。

适用场景：

- 总结某个功能的工作原理

- 向我解释某个概念

- 向上司汇报的每周状态报告

- 向领导层提交的事故报告

- SVG 插图、流程图、技术架构图等

# 自定义编辑界面

有时很难仅凭文字描述清楚你想要什么。在这种情况下，我会让 Claude 为我正在处理的具体内容构建一个一次性编辑器——不是产品，也不是可复用工具，而是一个专门为这份数据量身定制的单个 HTML 文件。

关键在于最后一定要加上导出功能：一个"复制为 JSON"或"复制为提示词"按钮，将我在界面中完成的操作转化回可以粘贴到 Claude Code 的内容。

示例提示词：

- 我需要重新排列这30个Linear工单的优先级。帮我生成一个HTML文件，将每张工单做成可拖拽的卡片，分布在"现在 / 接下来 / 以后 / 砍掉"四列中，并按你的最佳判断预先排序。添加一个"复制为Markdown"按钮，导出最终排序结果，每个桶附带一句话的理由说明。

- 这是我们的功能开关配置。为它构建一个基于表单的编辑器，按功能区域对开关分组，展示它们之间的依赖关系，如果我启用了一个前置条件未开启的开关，请向我发出警告。添加一个"复制差异"按钮，只给我显示已更改的键。

- 我在调试这个系统提示词。做一个并排编辑器：左侧是可编辑的提示词，变量槽位高亮显示；右侧是三个示例输入，实时渲染填充后的模板。添加字符/Token计数器和复制按钮。

适用场景：

- 对任意内容重新排序、分类或归桶（工单、测试用例、反馈）
- 编辑结构化配置（功能开关、环境变量、带约束的JSON/YAML）
- 调试提示词、模板或文案，并实时预览
- 整理数据集、批准/拒绝行、标注示例、导出选定内容
- 对文档、对话记录或差异进行标注并导出标注结果
- 选取难以用文字表达的值：颜色、缓动曲线、裁剪区域、Cron表达式、正则表达式

## 常见问题解答

我已经向很多人讲述了自己转向HTML的经历，也看到了一些反复被问到的问题。

**Token效率会更低吗？**
虽然Markdown通常使用更少的Token，但我发现HTML更强的表现力，以及我更高概率会真正阅读它，综合来看能带来更好的输出结果。在Opus 4.7的100万上下文窗口下，Token用量的增加在上下文窗口中几乎感觉不到。

**你现在还用Markdown吗？**
老实说，我几乎已经完全停止在任何场景下使用Markdown了，不过我可能处于HTML极端主义的那一端。

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

**生成速度会比Markdown慢吗？**
确实会慢一些！HTML的生成时间可能比Markdown长2到4倍，但我觉得结果是值得的。

**版本控制怎么办？**
这确实是HTML最大的缺点之一——HTML的差异对比噪音大，审查起来远不如Markdown直观。

**如何让Claude符合我的审美、不做出难看的设计？**
前端设计插件能帮助Claude生成质量更好的HTML文件。如果要匹配公司自有风格，可以让Claude参考你的代码库，生成一个设计系统HTML文件，之后再以该文件作为其他HTML文件的设计参考。

## 保持参与感

以上所说的一切，归根结底是想表达：我使用HTML的真正原因，是它让我感觉自己与Claude的协作更加紧密。我曾经担心，因为不再深入阅读计划内容，我只能任由Claude自行做出各种决策。

但我很高兴地说，使用HTML之后，我比以往任何时候都更有参与感。希望你也能有同样的体验。