Claude Code 工程师：HTML 是新的 Markdown

Claude Code 团队的工程师 Thariq Shihipar 今天发了篇文章，标题叫《Using Claude Code: The Unreasonable Effectiveness of HTML》。翻译过来不到一行字：他不用 Markdown 了，全换成 HTML。

这事儿听着像是格式偏好问题，但读下去你会发现，Thariq 想说的其实不是 HTML 多好——是 agent 越来越能干之后，人这边出了问题。Claude 写的 spec 越来越长，超过 100 行的 Markdown 他自己都不想读，更别说丢给同事；Claude 想画图、想做 diff、想表达颜色，Markdown 只能让它用 ASCII 硬凑或者拿 Unicode 色块估个色。Thariq 截了张 Claude Code 用 Unicode 估色的图放在文章里，那感觉就像看一个能写 1M token 的模型在用算盘做加法。于是他换了 HTML。一篇本来该是格式安利的文章，写到最后落在了一句很意外的话上："我之前担心自己不再认真读计划，最后只能默认接受 Claude 的选择。但用 HTML 之后，我感觉自己比以前任何时候都更 in control。"

以下是 Thariq 这篇文章的编译。

Markdown 已经成为智能体与我们交流的主流文件格式。它简单、便携、具备一定的富文本能力，而且便于你编辑。Claude 甚至在使用 ASCII 在 Markdown 文件中绘制图表方面变得出奇地好。但随着智能体变得越来越强大，我感到 Markdown 正在成为一种限制性格式。超过一百行的 Markdown 文件对我来说很难阅读。我想要更丰富的可视化效果、色彩和图表，并且希望它们能方便地被分享。

我也越来越多地不再亲自编辑这些文件，而是把它们当作规范、参考文件、头脑风暴的产出物来使用。当我确实需要编辑时，通常是让 Claude 来编辑，这也就消除了 Markdown 最大的一个优势。我已经开始更偏好将 HTML 而不是 Markdown 作为输出格式，并且越来越多地看到 Claude Code 团队中的其他人也在这样做，理由如下。

（如果你想先看一些实例，可以在这里看到很多：https://thariqs.github.io/html-effectiveness，但记得回来继续阅读更多关于“为什么”的内容。）

1

为什么选择HTML？

信息密度

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

• 使用表格展示表格数据

• 使用 CSS 展示设计数据

• 使用 SVG 展示插画

• 使用 script 标签展示代码片段

• 使用 JavaScript + CSS 配合 HTML 元素展示交互

• 使用 SVG 和 HTML 展示工作流

• 使用绝对定位和 canvas 展示空间数据

• 使用 image 标签展示图片

我甚至可以说，几乎没有任何一组 Claude 能读取的信息是你无法用 HTML 相当高效地表示出来的。这使得它成为模型向你传达深度信息以及你进行审阅的一种高效方式。

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

Claude Code 尝试在 Markdown 中显示颜色

视觉清晰度与可读性

随着 Claude 能够处理更复杂的工作，它编写的规范和计划也越来越长。在实践中，我发现超过一百行的 Markdown 文件我实际上不会去读，而且我肯定没法让组织中的其他人去读它。

但 HTML 文档却更容易阅读。Claude 可以从视觉上组织结构，使其通过标签页、插画、链接等方式理想地进行导航。它甚至可以做到移动端响应式，让你能根据不同的设备形态来阅读。

分享的便捷性

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

而使用 HTML，只要把文件上传（例如上传到 S3），你就可以方便地分享链接。你的同事可以随时在任何地方打开并轻松参考。你的规范、报告或 PR 描述被人真正阅读的概率，如果以 HTML 形式呈现，会高出很多。

双向交互

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

阅读我关于"playgrounds"的帖子，了解更多关于这种双向交互的示例：https://x.com/trq212/status/2017024445244924382

数据摄取

为什么使用 Claude Code 来生成 HTML 文件，而不是 Claude.AI 或 Claude Design 呢？最重要的原因之一就是 Claude Code 能够摄取的所有上下文。

例如，在撰写本文时，我让 Claude Code 读取我的代码文件夹，找到我生成的所有 HTML 文件，将它们分组归类，然后生成一个包含所有图表类型的 HTML 文件。你在本文中看到的图表就是这项工作的直接成果。

除了文件系统，Claude Code 还能通过你的 MCP 工具（如 Slack、Linear 等）、你的浏览器（通过 Chrome 中的 Claude）、你的 git 历史等途径找到额外的上下文。

它充满乐趣

使用 Claude 来生成 HTML 文档就是更加有趣，让我感觉更投入、更参与到创作中，而这一点本身就足够了。

2

如何上手

我有点担心人们会读完这篇文章后把它做成一个 html 技能或类似的东西。虽然这样做可能有一些价值，但我想强调的是，你不需要做太多事情就能让 Claude 做到这一点。你只需直接告诉它“制作一个 HTML 文件”或“制作一个 HTML artifact”。

诀窍在于，知道你想要这个 artifact 做什么，以及你可能如何使用它。随着时间的推移，你可能会制作一个技能，但就目前而言，我建议从头开始写提示词，以便掌握在不同情况下如何使用它。

3

使用案例

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

规范、规划与探索

HTML 是一种非常适合 Claude 深入分析和拆解问题的可视化表达方式。当我开始处理一个问题时，我期望创建的是一组 HTML 文件网络，而不是一个简单的 Markdown 计划。例如，我可能会先让 Claude Code 进行头脑风暴，创建一些针对不同选项的探索方案。然后，我会让它对其中的某一个进行扩展，也许会制作一些原型或代码片段。最后，当我觉得不错时，我会让它编写一份实施计划。当我对计划感到满意时，我会创建一个新的会话，将所有这些文件传入，让它去实施。

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

示例提示词：

• "我不确定该为引导页采用哪个方向。生成 6 种截然不同的方案——在布局、语气和信息密度上做出变化——并将它们排列在一个 HTML 文件的网格中，以便我可以并排比较。在每个方案上标注它所做出的取舍。"

• "在一个 HTML 文件中创建一份详尽的实施计划，务必制作一些原型图、展示数据流，并添加我可能想审阅的关键代码片段。使其易于阅读和消化。"

可用于：

• 探索实现某段代码的其他方式

• 探索多种视觉设计方案

代码审查与理解

代码在 Markdown 文件中可能很难阅读。但借助 HTML，我们可以渲染差异对比、注释、流程图、模块等内容。使用这个方法来理解智能体已编写的代码，进行代码审查，或向审查你代码的人解释一个 PR。我发现这通常比默认的 GitHub diff 视图效果更好，而且现在我为每一个 PR 都附上了一份 HTML 代码解释器。

示例提示词：

"通过创建一个描述此 PR 的 HTML artifact 来帮助我进行审查。我对流式处理/背压逻辑不太熟悉，所以请重点讲解这一块。以内联旁注的方式渲染实际差异，按严重程度对发现进行颜色编码，以及任何其他能更好传达该概念所需的内容。"

可用于：

• 创建 PR

• 审查 PR

• 理解代码中的某个主题

设计与原型

Claude Design 之所以基于 HTML，是因为 HTML 在设计方面具有令人难以置信的表达力，即使你的最终输出界面不是 HTML。Claude 可以用 HTML 勾勒出设计方案，然后用你选择的语言（无论是 React、Swift 等）将其编写出来。

你也可以为交互制作原型，例如动画、动作等。可以考虑让 Claude 添加滑块、旋钮等，以便精确调整到你想要的效果。

示例提示词：

"我想为一个新的结账按钮制作原型，当点击时它会播放一个动画，然后迅速变为紫色。创建一个带有多个滑块和选项的 HTML 文件，让我可以尝试这个动画的不同选项，并给我一个复制按钮来复制效果好的参数。"

可用于：

• 创建设计系统 artifact

• 调整组件

• 可视化组件库

• 制作有趣的动画原型

报告、研究与学习

Claude Code 极其擅长从多个数据来源综合信息，并将其转化为具有可读性的报告。你可以提示 Claude 搜索你的 Slack、你的代码库、git 历史、互联网等，并利用这些信息为你自己、为领导层、为你的团队等生成极具可读性的报告。

你可以将其组装成一个长 HTML 文档、一个交互式解释器，甚至是一个幻灯片/演示文稿。让 Claude 使用 SVG 来制作图表以帮助可视化。

比如，在写“提示词缓存（Prompt Caching）”相关文章时，我会先让 Claude 阅读 Git 历史，再把所有与“提示词缓存”相关的改动整理成一份深入的 HTML 研究文档，方便我系统地阅读和理解。

示例提示词：

"我不理解我们的速率限制器实际上是如何工作的。阅读相关代码，并生成一个单独的 HTML 解释页面：一个展示令牌桶流程的图表，3 到 4 个带注释的关键代码片段，并在底部设立一个“注意事项”部分。针对一次性阅读进行优化。"

可用于：

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

• 向我解释一个概念

• 向你的老板汇报每周状态

• 向你的领导层汇报事故

• SVG 插画、流程图、技术图表等

自定义编辑界面

有时候，很难用纯文本框来描述你想要什么。在这种情况下，我会让 Claude 为我正在处理的具体事项构建一个临时编辑器。不是一个产品，也不是一个可重复使用的工具，而是一个单独的 HTML 文件，专门为这一份数据而构建。

诀窍始终是以一个导出功能作为收尾：一个“复制为 JSON”或“复制为提示词”的按钮，将我在 UI 中所做的任何事情转换回可以粘贴到 Claude Code 中的内容。

示例提示词：

• "我需要重新排列这 30 个 Linear 工单的优先级。为我制作一个 HTML 文件，将每个工单作为可拖动的卡片，分布在“现在/下一步/以后/砍掉”这几列中。根据你的最佳猜测预先排序。添加一个“复制为 Markdown”按钮，导出最终排序，并为每个分组附上一句话的理由。"

• "这是我们的功能开关配置。为它制作一个基于表单的编辑器，按区域对开关进行分组，显示它们之间的依赖关系，并在我要启用一个前置条件被关闭的开关时发出警告。添加一个“复制 diff”按钮，仅给出我已修改的键值。"

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

可用于：

• 对任何内容（工单、测试用例、反馈）进行重新排序、分类或归类

• 编辑结构化配置（功能开关、环境变量、带约束的 JSON/YAML）

• 通过实时预览来调整提示词、模板或文案

• 筛选数据集，批准/拒绝行，标记示例，导出所选内容

• 对文档、转录或 diff 进行注释，并导出注释

• 选取那些用文字表达很痛苦的值：颜色、缓动曲线、裁剪区域、cron 表达式、正则表达式

4

常见问题

我已经告诉过很多人我是如何转向使用 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 符合我的品味/不让它做得很丑？

前端设计插件有助于 Claude 生成好的 HTML 文件。但若要符合你自己公司的风格，你可以让 Claude 参考你的代码库来创建一个单独的设计系统 HTML 文件。然后，你可以将这个设计系统文件作为其他 HTML 文件的参考。

5

保持在 loop 里

以上内容是想说，我认为我使用 HTML 的真正原因是，我感觉自己与 Claude 的联系更加紧密了。我曾一度担心，因为自己已经不再深入阅读计划，我将只能放手让 Claude 去做它自己的选择。但我很高兴地说，在使用 HTML 时，我感觉自己比以往任何时候都更处于整个过程的循环之中。我希望你也是如此。

点击关注我哦