原文作者：Thariq（@trq212）
原文链接：x.com/trq212/status/2052809885763747935
译者注：本文介绍为何越来越多 Claude Code 用户转向 HTML 作为 Agent 的输出格式。
Markdown 已经成为 Agent 与我们沟通的主流文件格式。它简洁、可移植、支持基本的富文本，也方便手动编辑。Claude 甚至已经能在 Markdown 文件里用 ASCII 画出相当不错的图表。
但随着 Agent 能力越来越强，我开始感到 Markdown 变成了一种束缚。超过一百行的 Markdown 文件，我基本读不下去。我想要更丰富的可视化效果、颜色和图表，也想方便地分享给别人。
而且我越来越少亲手编辑这些文件，更多是把它们当作规格文档、参考资料、头脑风暴输出物来用。就算要改，我通常也是让 Claude 来改——这就抹去了 Markdown 最大的优势之一。
我开始倾向于用 HTML 作为输出格式，也越来越多地看到 Claude Code 团队的其他成员这样做。这就是原因。
HTML 能表达的信息远比 Markdown 丰富，它不只能做基本的文档结构和格式，还能表达：
<img> 标签插入图片我甚至可以说，Claude 能读取的任何信息，几乎都可以用 HTML 高效地表达出来。这让 HTML 成为模型向你传递深度信息的极佳媒介。
相比之下，当模型无法做到这些时，往往会在 Markdown 里做一些低效的替代——比如用 ASCII 画图，或者我最喜欢的例子：用 Unicode 字符来模拟颜色（如 Claude Code 的截图所示）。
随着 Claude 能处理越来越复杂的工作，它写的规格文档和计划也越来越长。实践中我发现，超过一百行的 Markdown 文件我基本不会真正通读，更不用说让团队其他人读了。
而 HTML 文档读起来容易得多。Claude 可以用标签页、插图、链接等方式在视觉上组织内容，方便导航。甚至可以做成响应式页面，根据你的设备以不同方式呈现。
Markdown 文件很难分享——大多数浏览器无法原生渲染，你往往需要把它作为附件发邮件或发消息。
HTML 则不同，只要把文件上传（比如上传到 S3），就能分享链接，同事在任何地方都可以打开，轻松查阅。
你的规格文档、报告或 PR 说明被人真正阅读的概率，用 HTML 会大得多。
HTML 可以让文档变得可交互。比如，你可以让 Claude 在文档里加上滑块或旋钮，来调整设计参数，或者让你微调算法里的不同选项，实时看效果。你还可以让它加一个"复制"按钮，把你调整好的参数拷贝成 Prompt，直接粘回 Claude Code。
为什么要用 Claude Code 生成 HTML，而不是用 Claude.ai 或 Claude Design 呢？一个最重要的原因是 Claude Code 可以摄入大量上下文。
比如在写这篇文章时，我让 Claude Code 扫描我的代码文件夹，找出所有我生成过的 HTML 文件，对它们分组归类，然后生成一个 HTML 文件，用图表展示每种类型。这篇文章里的图表就是这样来的。
除了文件系统，Claude Code 还可以通过 MCP（如 Slack、Linear 等）、浏览器、Git 历史等获取额外上下文。
用 Claude 生成 HTML 文档就是更有意思，让我觉得自己更投入、更有参与感——光这一点就够了。
我有点担心读完这篇文章，大家会立刻去做一个 /html skill。这样做或许有些价值，但我想强调的是：让 Claude 输出 HTML 根本不需要做什么特别的事。你只需要直接说「生成一个 HTML 文件」或「生成一个 HTML artifact」就行了。
关键在于知道你想让这个 artifact 做什么、怎么用它。随着时间推移你可能会做一个 skill，但现在我建议先直接用 Prompt 从头摸索，感受它在不同场景下的用法。
HTML 是 Claude 深入分析问题的绝佳画布。当我开始处理一个问题时，我不再只是写一个简单的 Markdown 计划，而是期望形成一组 HTML 文件。比如，我会先让 Claude Code 头脑风暴，生成几种不同方向的探索；然后让它深入其中某一个，做出原型或代码片段；最后当我觉得方向对了，再让它写实施计划。准备实现时，我会开一个新会话，把这些文件全部传进去。
示例 Prompt：
我不确定新手引导页面该走哪个方向。生成 6 种风格迥异的方案——布局、语气、信息密度各有不同——整合成一个 HTML 文件，网格排列，方便我并排比较。每种方案标注其取舍权衡。
生成一份详细的实施计划 HTML 文件，包含设计稿、数据流图、以及我可能需要审查的关键代码片段。让它读起来清晰易懂。
适用场景： 探索不同实现方式、对比多种视觉设计
代码在 Markdown 里很难阅读。但用 HTML 可以渲染 diff、注释、流程图、模块依赖等。用它来理解 Agent 写的代码、进行代码审查，或者向代码审查者解释 PR——我发现这比默认的 GitHub diff 视图更好用。现在我每个 PR 都会附上一个 HTML 代码说明文件。
示例 Prompt：
帮我审查这个 PR，生成一个 HTML artifact 来描述它。我对 streaming/backpressure 逻辑不太熟悉，请重点解释这部分。渲染实际的 diff，在旁边加注释，按严重程度对发现问题进行颜色标注。
适用场景： 创建 PR、审查 PR、理解代码中的某个主题
Claude Design 基于 HTML，正是因为 HTML 在设计表达上极具灵活性——即使你最终使用的不是 HTML。Claude 可以先用 HTML 画出设计草图，然后再用你的目标语言（React、Swift 等）实现。
你还可以用 HTML 原型来测试交互效果，比如动画、操作等。让 Claude 加上滑块、旋钮等控件，让你精确调整想要的效果。
示例 Prompt：
我想原型一个新的结账按钮，点击后先播放动画，然后快速变成紫色。做一个带滑块和选项的 HTML 文件，让我可以试验不同的动画参数，加一个"复制参数"按钮，把调好的值复制出来。
适用场景： 创建设计系统 artifact、调整组件、可视化组件库、原型交互动画
Claude Code 在跨多数据源综合信息、生成可读性强的报告方面表现出色。你可以让它搜索你的 Slack、代码库、Git 历史、互联网等，生成供个人、领导层或团队阅读的报告。
可以做成长篇 HTML 文档、交互式说明页，甚至是幻灯片/演示文稿。让 Claude 用 SVG 画图表来辅助可视化。
示例 Prompt：
我不明白我们的限流器到底是怎么工作的。读相关代码，生成一个 HTML 说明页：包含 token-bucket 流程图、3-4 个关键代码片段加注释，以及底部的"坑"章节。为只读一遍的人优化可读性。
适用场景： 梳理某功能的工作原理、解释某个概念、向上级汇报周报、撰写故障报告、SVG 插图和技术图表等
有时候，纯文字无法准确描述你想要什么。这时，我会让 Claude 帮我构建一个一次性的专用编辑器，专门针对我当前处理的数据，而不是一个通用工具或可复用产品。
关键是结尾要有一个导出按钮——"复制为 JSON"或"复制为 Prompt"——把我在 UI 里的操作结果转换成可以粘回 Claude Code 的内容。
示例 Prompt：
我需要重新排列这 30 张 Linear 工单的优先级。做一个 HTML 文件，每张工单是一个可拖拽卡片，分布在 Now / Next / Later / Cut 四列。先按你的最佳判断预排序。加一个"复制为 Markdown"按钮，导出最终排序，每个分组附一行理由说明。
这是我们的功能开关配置。给它做一个表单编辑器，按功能区分组，展示开关之间的依赖关系，如果我开启了某个依赖项未满足的开关就警告我。加一个"复制 diff"按钮，只给出改动的 key。
适用场景： 对任何内容（工单、测试用例、反馈）进行排序和分类、编辑结构化配置、调整 Prompt 和模板、标注数据集、选取难以用文字描述的值（颜色、缓动曲线、Cron 时间等）
这不是更耗 Token 吗？
Markdown 通常用的 Token 更少，但我发现 HTML 的表达力更强，而且我真正阅读它的概率大得多，整体产出反而更好。Opus 4.7 的 100 万上下文窗口让 Token 增加基本不成问题。
你什么时候还会用 Markdown？
说实话，我几乎已经完全不用 Markdown 了——但我可能是 HTML 最大化主义那一端的极端案例。
怎么查看 HTML 文件？
我通常直接在本地浏览器打开（可以让 Claude 帮你打开），或者上传到 S3 获取可分享的链接。
生成 HTML 不是比 Markdown 更慢吗？
确实更慢，HTML 可能比 Markdown 慢 2-4 倍。但我觉得效果值得。
版本控制怎么办？
这确实是 HTML 最大的缺点——HTML 的 diff 很嘈杂，比 Markdown 难审查得多。
怎么让 Claude 生成的 HTML 符合我的审美？
Frontend Design 插件可以帮助 Claude 生成更美观的 HTML。要匹配公司风格，你可以让 Claude 分析你的代码库，生成一个设计系统 HTML 文件，然后用它作为其他 HTML 文件的参考。
以上种种，归根结底是：我使用 HTML 的真正原因是，它让我对 Claude 的工作更有参与感。我曾经开始担心，因为我不再深入阅读计划文档，我只能任由 Claude 自己做决定。
但令我高兴的是，用 HTML 之后，我反而比以前更清楚地知道 Claude 在做什么。希望你也有同样的感受。