Claude Code 工程师：HTML 是新的Markdown

本文来自微信公众号： 硅星GenAI ，作者：大模型机动组，原文标题：《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，但记得回来继续阅读更多关于“为什么”的内容。）

为什么选择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文档就是更加有趣，让我感觉更投入、更参与到创作中，而这一点本身就足够了。

如何上手

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

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

使用案例

为了让这些内容更具体，我为不同的使用场景制作了许多不同的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文件的参考。

保持在loop里

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