这篇文章也发布在 Claude 博客上了。
Markdown 已经成为 Agent 与我们交流时使用的主流文件格式。它简洁、可移植、具备一定的富文本能力，而且方便你编辑。Claude 甚至已经相当擅长用 ASCII 在 markdown 文件里画图。
但随着 Agent 越来越强大，我开始感觉 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 表示的空间数据
- 用图片标签表示的图像
我甚至敢说，几乎没有任何 Claude 能读到的信息是你无法用 HTML 高效表达的。这使得它成为模型向你传达深度信息、以及你进行审查的一种高效方式。
我发现，如果不能这样做，模型可能会在 markdown 里做一些低效的事情，比如 ASCII 图表，或者我最喜欢的——用 Unicode 字符来估算颜色，就像这张 Claude Code 截图里那样。
视觉清晰 & 易于阅读
随着 Claude 能处理更复杂的工作，它写出的规格和计划也越来越庞大。实际上，我发现我根本不会去读超过一百行的 markdown 文件，更别指望团队里其他人会读了。
但 HTML 文档读起来容易得多，Claude 可以用视觉效果来组织结构，使其以标签页、插图、链接等方式达到理想的导航效果。它甚至可以自适应移动端，这样你可以根据设备不同以不同方式阅读。
易于分享
Markdown 文件很难分享，因为大多数浏览器不能很好地原生渲染它们。你通常得把它们作为附件添加到邮件或消息里。
而用 HTML，只要你上传文件（比如传到了 S3），就能轻松分享链接。你的同事可以在任何地方打开它，方便地引用。
如果换成 HTML，别人真正去读你的规格、报告或 PR 总结的概率会高得多。
双向交互
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 skill 之类的。虽然可能也有点价值，但我想强调，你不需要做太多就能让 Claude 做这件事。你只需要跟它说“生成一个 HTML 文件”或“做一个 HTML artifact”就行。
关键在于你想让这个 artifact 做什么，以及你打算怎么用它。随着时间的推移，你可能会做一个 skill，但现在我建议直接从零开始写提示词，先掌握在不同场景下怎么用它。
使用场景
为了让这个更具体，我已经为不同的使用场景生成了很多 HTML 文件。你可以在这里看到全部：https://thariqs.github.io/html-effectiveness/，下面是概览。
规格、计划与探索
HTML 是 Claude 深入问题的一个丰富画板。当我开始处理一个问题时，我预期会做出一系列 HTML 文件，而不是一个简单的 markdown 计划。例如，我可能会先让 Claude Code 进行头脑风暴，创建一些不同选项的探索。然后让它进一步展开其中一个，可能做出模拟图或代码片段。最后，当我感觉不错时，再让它写一个实现计划。计划满意后，我会开启一个新会话，把所有文件传进去让它实现。
在验证时，我也会让验证 agent 读取这些文件，这样它就能对所需内容有更全面的上下文。
示例提示词：
我不确定引导页该往哪个方向做。生成6种截然不同的方案——在布局、风格和信息密度上各有侧重——把它们排在一个HTML文件的网格里，方便我并排对比。每种方案都标注出它所做的权衡取舍。
创建一个详尽的实施计划HTML文件，务必包含一些模拟图，展示数据流，并附上我可能需要回顾的关键代码片段。让它易于阅读和理解。
使用场景：
探索代码的其他实现方式
探索多种视觉设计方案
代码审查与理解
在Markdown文件中阅读代码可能很困难。但借助HTML，我们可以渲染差异对比、注释、流程图、模块等。用它来理解Agent编写的代码、进行代码审查，或向审查你PR的人解释代码。我发现这通常比默认的GitHub差异视图效果更好，现在我提交的每个PR都会附带一个HTML代码解释器。
示例提示词：
帮我审查这个PR，创建一个描述它的HTML制品。我对流式/背压逻辑不太熟悉，所以请重点讲解这部分。渲染实际的差异对比，在行内添加边距注释，按严重程度用颜色标注发现的问题，以及任何有助于清晰传达概念的内容。
使用场景：
- 创建PR
- 审查PR
- 理解代码中的某个主题
设计与原型
Claude Design基于HTML，因为HTML在设计方面表现力极强，即使你的最终界面不是HTML。Claude可以用HTML勾勒出设计草图，然后用你选择的语言（如React、Swift等）实现。
你还可以原型化交互，比如动画、动作等。可以请Claude制作滑块、旋钮等控件，来精确调到你想要的效果。
示例提示词：
我想原型化一个新的结账按钮，点击时播放一个动画，然后快速变成紫色。创建一个HTML文件，包含几个滑块和选项，让我可以尝试这个动画的不同参数，给我一个复制按钮来复制效果好的参数。
用于：
- 创建设计系统制品
- 调整组件
- 可视化组件库
- 原型化有趣的动画
报告、研究与学习
Claude Code非常擅长综合多个数据源的信息，并将其转化为易于阅读的报告。你可以提示Claude搜索你的Slack、代码库、Git历史、互联网等，并为你、为领导层、为团队等生成极其易读的报告。
你可以将其整理成一份长HTML文档、一个交互式解释器，甚至是一个幻灯片/演示文稿。请Claude使用SVG绘制图表来帮助可视化。
例如，在我关于提示缓存的文章中，我请Claude在阅读Git历史后，为我准备一份关于我们所有提示缓存变更的深度研究HTML文件。
示例提示词：
我不太理解我们的限流器到底是怎么工作的。阅读相关代码，生成一个单页的HTML解释页面：包含令牌桶流程的图表、3-4个带注释的关键代码片段，以及底部的"注意事项"部分。优化成让读者看一遍就能理解。
用于：
- 总结某个功能的工作原理
- 向我解释一个概念
- 给老板的每周状态报告
- 给领导层的事件报告
- SVG插图、流程图、技术图表等
自定义编辑界面
有时很难纯粹在文本框中描述你想要的东西。这种情况下，我会让Claude为我正在处理的具体内容构建一个一次性的编辑器。不是一个产品，也不是一个可复用的工具，而是一个单一的HTML文件，专为这一份数据量身定制。
诀窍是始终以导出功能结尾：一个"复制为JSON"或"复制为提示词"的按钮，将你在UI中做的所有操作转换回可以粘贴到Claude Code中的内容。
示例提示词：
我需要重新排列这30个Linear工单的优先级。给我做一个HTML文件，每个工单是一个可拖拽的卡片，分布在"现在/下一步/稍后/放弃"列中。按你的最佳判断预先排序。添加一个"复制为Markdown"按钮，导出最终排序结果，并为每个分组附上一行理由。
这是我们的功能开关配置。为它构建一个基于表单的编辑器，按区域对开关进行分组，显示它们之间的依赖关系，如果我启用了一个依赖项被关闭的开关，请发出警告。添加一个"复制差异"按钮，只输出发生变化的键。
我正在调整这个系统提示词。做一个并排编辑器：左侧是可编辑的提示词，高亮显示变量插槽；右侧是三个示例输入，实时渲染填充后的模板。添加一个字符/令牌计数器和一个复制按钮。
用于：
- 重新排序、分类或分组任何内容（工单、测试用例、反馈）
- 编辑结构化配置（功能开关、环境变量、带约束的JSON/YAML）
- 调整提示词、模板或文案，并实时预览
- 整理数据集，批准/拒绝行，标记示例，导出选择结果
- 注释文档、转录文本或差异对比，并导出注释
- 选取难以用文本表达的值：颜色、缓动曲线、裁剪区域、Cron调度、正则表达式
常见问题
我一直在向很多人介绍我如何转向使用HTML，也看到了一些反复出现的问题。
这样不是更消耗令牌吗？
虽然Markdown通常使用更少的令牌，但我发现HTML更强的表现力以及我阅读它的可能性大大提高，意味着我总体上能获得更好的输出。借助Opus 4.7中100万令牌的上下文窗口，增加的令牌使用量在上下文中几乎感觉不到。
你现在什么时候用Markdown？
老实说，我现在几乎在所有事情上都完全不用Markdown了，但我可能属于HTML最大化主义那一端。
如何查看HTML文件？
我通常直接在本地浏览器中打开它（你可以让Claude打开它），或者如果你想获得一个可分享的链接，就上传到S3。
使用 Claude Code：HTML 出人意料的有效性
生成 HTML 不是比 Markdown 更花时间吗？
确实更花时间！HTML 比 Markdown 多花 2-4 倍时间，但我觉得结果值得。
那版本控制怎么办？
说实话，这是 HTML 最大的缺点之一——HTML 的 diff 很杂乱，比 Markdown 难审阅。
如何让 Claude 符合我的审美 / 不让它做出来很丑？
前端设计插件能帮助 Claude 生成不错的 HTML 文件。但要想匹配你自己公司的风格，你可以让 Claude 指向你的代码库，创建一份统一的设计系统 HTML 文件。然后你就可以拿这份设计系统文件作为其他 HTML 的参考。
保持参与感
以上所有这些，都是想说：我真正用 HTML 的原因，是感觉自己跟 Claude 的交流更紧密了。我之前担心，因为不再深度阅读计划，只能放手让 Claude 自己做选择。
但很高兴地告诉大家，恰恰相反，用 HTML 让我比以往任何时候都更有参与感。希望对你也是如此。