Claude Code 团队成员分享：为什么用 HTML 替代 Markdown 作为 Agent 输出格式

Markdown 已成为智能体与人类沟通时使用的主流文件格式。它简单、可移植、具备一定的富文本能力，而且易于编辑。Claude 甚至已经非常擅长在 Markdown 文件中用 ASCII 绘制图表。

但随着智能体变得越来越强大，我发现 Markdown 已经逐渐成为一种限制性越来越强的格式。具体来说，我发现超过一百行的 Markdown 文件就很难阅读；我希望用 Claude 生成更丰富的可视化、颜色和图表；我也希望能够更轻松地分享这些输出。

我也越来越少亲自编辑这些文件，而是把它们当作规格说明和参考文件来使用。当我确实需要编辑时，通常也是让 Claude 去改，这就抹掉了 Markdown 最大的优势之一。

于是，我开始更倾向于用 HTML 而不是 Markdown 作为输出格式，并且看到 Claude Code 团队中越来越多的人也在采用这种模式。在这篇文章中，我将分享我们团队为什么以及如何使用 HTML 来产出更丰富、更易读的 Claude Code 输出。如果你想跟着一起做，也可以开始使用这些针对常见用例的 HTML 文件模板。

为什么要用 HTML？

对于我现在用 Claude Code 做的这类工作而言，有几件事让 HTML 比 Markdown 更合适，包括那些需要或涉及以下内容的任务：

信息密度

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

• 使用表格呈现的表格数据
• 使用 CSS 呈现的设计数据
• 使用 SVG 呈现的插图
• 使用 script 标签呈现的代码片段
• 使用 HTML 元素配合 javascript + CSS 实现的交互
• 使用 SVG 和 HTML 呈现的工作流
• 使用绝对定位和 canvas 呈现的空间数据
• 使用 image 标签呈现的图像

在我看来，几乎不存在 Claude 能读取、而你又无法用 HTML 高效表示的信息。这使得它成为一种非常高效的方式，让模型向你传达深入的信息，也让你审阅这些信息。

我发现，在无法做到这一点时，模型可能会在 Markdown 中做一些效率更低的事，比如 ASCII 图表，或者我最喜欢的——用 unicode 字符来估算颜色。

视觉清晰度与易读性

随着 Claude 能够处理更复杂的工作，它也能写出越来越长的规格说明和计划。我发现，超过 100 行的 Markdown 文件我往往根本不会去读，更不用说让我组织里的其他人去读了。

但 HTML 文档要易读得多，因为 Claude 可以从视觉上组织结构，通过标签页、插图和链接让它非常适合浏览。它甚至还能做到移动端自适应，让你可以根据设备形态以不同方式阅读。

易于分享

Markdown 文件相当难以分享，因为大多数浏览器无法很好地原生渲染它们。你往往不得不把它们作为附件添加到邮件或消息中。

而只要上传 HTML 文件，你就能轻松分享链接。你的同事可以在任何他们想用的地方打开它，并轻松引用。

如果你的规格说明、报告或 PR 说明是 HTML 格式，别人真正去读它的可能性会高得多。

双向交互

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

在有用的时候，这可以让你针对正在处理的具体问题创建单独的编辑环境。

数据摄取

使用 Claude Code 而不是 Claude.ai 或 Claude Design 来制作 HTML 文件的最大原因之一，是 Claude Code 可以摄取的所有上下文。例如，在撰写本文时，我让 Claude Code 通读我的代码文件夹，找出我生成的所有 HTML 文件，对它们进行分组和分类，然后制作一个 HTML 文件，用图表表示每种类型。你在本文中看到的图表正是这样产生的。

除了文件系统之外，Claude Code 还可以使用你的 MCP（如 Slack、Linear 等）、你的网络浏览器（通过 Claude in Chrome）以及你的 git 历史记录来查找额外的上下文。

入门

有一点值得注意：你不需要做太多就能让 Claude 生成这样的 HTML。你只需提示它“制作一个 HTML 文件”或“制作一个 HTML artifact”。关键在于知道你想要这个 artifact 做什么，以及你可能如何使用它。随着时间推移，围绕反复出现的模式构建一项技能可能是有意义的，但从头开始提示是了解它在不同用例中如何工作的好方法。

用例

为了让这种方法更具体，下面是一些示例用例，我认为在这些场景中使用 HTML 文件比 Markdown 更合理。你也可以在 GitHub 上查看这些用例的画廊，在这里。

规格、规划与探索

HTML 是 Claude 深入探究问题的丰富画布。当我开始处理一个问题时，我期望的不是简单的 Markdown 计划，而是一张由 HTML 文件构成的网。例如，我可能会先让 Claude Code 进行头脑风暴，并创建对不同选项的一些探索。然后我会让它进一步展开其中一个，也许制作该类型界面的模型或示例。最后，当我感觉不错时，我会让它编写一份实现计划。当我对计划满意时，我会创建一个新会话，并传入所有这些文件让它实现。

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

示例提示词：

• 我不确定引导屏幕该往哪个方向做。生成 6 种截然不同的方法——在布局、语气和密度上有所变化——并将它们以网格形式排布在一个 HTML 文件中，以便我并排比较。为每一种标注它所做出的权衡。
• 在一个 HTML 文件中创建一份详尽的实现计划，务必制作一些模型，展示数据流，并添加我可能想查看的重要代码片段。让它易于阅读和消化。

用于：

• 探索在代码中实现某事的其他方式
• 同时试验多种视觉设计

代码审查与理解

在 Markdown 文件中阅读代码可能很困难，但借助 HTML，我们可以渲染差异、注释、流程图和模块。使用 HTML 来理解智能体编写的代码、审查代码，或向审查你代码的人解释 PR。

示例提示词：

帮我审查这个 PR，创建一个描述它的 HTML 工件。我对流式/背压逻辑不太熟悉，所以重点放在那上面。渲染实际的差异，并附上内联边注，按严重程度对发现进行颜色编码，以及传达概念所需的其他任何内容。

适用于：

• 创建 PR
• 审查 PR
• 理解代码中的某个主题

设计与原型

Claude Design 基于 HTML，因为 HTML 在设计方面极具表现力，即使你的最终界面不是 HTML。Claude 可以用 HTML 勾勒出设计，然后用你选择的语言编写，无论是 React、Swift 等。

你还可以对交互进行原型设计，例如动画、操作等。可以考虑让 Claude 制作滑块、旋钮等，以精确调出你想要的效果。

示例提示词：

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

适用于：

• 创建设计系统工件
• 调整组件
• 可视化组件库
• 原型设计动画

报告、研究与学习

Claude Code 非常擅长跨多个数据源综合信息，并将其转换为易于阅读的报告。你可以让 Claude 搜索你的 Slack、代码库、git 历史或互联网，并用它生成易于阅读的报告。

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

示例提示词：

我不理解我们的限流器实际上是如何工作的。阅读相关代码并生成一个单一的 HTML 讲解页面：一张令牌桶流程的图、3–4 个带注释的关键代码片段，以及底部的“注意事项”部分。针对只读一次的人进行优化。

适用于：

• 撰写功能总结
• 生成讲解
• 起草每周状态报告
• 创建事件报告
• 制作 SVG 插图、流程图和技术图表

自定义编辑界面

有时很难仅用文本框描述你想要的东西。对于这种用例，我经常会让 Claude 为我正在处理的具体内容构建一个一次性的编辑器：不是产品，也不是可复用的工具，而是一个单一的 HTML 文件，专为这一份数据而构建。

诀窍始终是以导出收尾：一个“复制为 JSON”或“复制为提示词”按钮，将我在 UI 中所做的一切转换回可以粘贴到 Claude Code 或提交到文件中的内容。你仍然在循环中，但循环变得紧密得多。

示例提示词：

• 我需要重新调整这 30 个 Linear 工单的优先级。给我做一个 HTML 文件，每个工单都是一张可拖拽的卡片，分布在 Now / Next / Later / Cut 四列中。按你最好的猜测预先排序。加一个“复制为 Markdown”按钮，导出最终排序，并为每个分组附上一行理由。
• 这是我们的功能开关配置。为它构建一个基于表单的编辑器，按区域对开关分组，显示它们之间的依赖关系，如果我要启用某个开关但其前置条件未开启，就警告我。加一个“复制 diff”按钮，只给我变更的键。
• 我正在调优这个系统提示词。做一个并排编辑器：左侧是可编辑的提示词，变量槽位高亮显示；右侧是三个示例输入，实时重新渲染填充后的模板。加一个字符/token 计数器和一个复制按钮。

适用于：

• 对任何内容重新排序、分类或分组（工单、测试用例、反馈）
• 编辑结构化配置（功能开关、环境变量、带约束的 JSON/YAML）
• 通过实时预览调优提示词、模板或文案
• 整理数据集——批准/拒绝行、给示例打标签、导出所选内容
• 为文档、转录文本或 diff 添加注释并导出注释
• 选择难以用文本表达的值：颜色、缓动曲线、裁剪区域、cron 计划、正则表达式

常见问题

这些是我最常被问到的关于将 HTML 与 Claude Code 一起使用的问题，并附上我日常实践中形成的实用习惯：

这样不是效率更低吗？

虽然 Markdown 通常使用更少的 token，但我发现 HTML 更强的表现力，以及我更有可能去阅读它，意味着我总体上能得到更好的输出。借助 Opus 4.7 的 1MM 上下文窗口，增加的 token 用量在上下文窗口中并不明显。

那你现在什么时候用 Markdown？

老实说，我几乎在所有事情上都已经完全不再使用 Markdown 了，不过我大概属于 HTML 极端主义者那一端。

这是你替代规划的方式吗？

我发现，与其只有一个计划，我倾向于为计划的不同部分/阶段准备几个不同的 HTML 文件。例如，我可能会用 HTML 做一个实现计划，然后再做一个文件来探索 UI，最后再做一个 HTML 组件列出每个设计。我倾向于保留这些文件，作为未来的参考，也用于验证。

与 Claude 保持同步

以上所有这些都说明，我使用 HTML 而不是 Markdown 的真正原因是，它让我感觉与 Claude 更加同步。随着 Claude 承担越来越多的工作，我注意到自己阅读计划时不再那么仔细，我想要一种方式来持续参与它的选择，而不是直接把它们交出去。HTML 恰好就是这种方式。我现在感觉自己比以往任何时候都更同步。

开始使用 Claude Code。

本文由技术团队成员 Thariq Shihipar 撰写，表达了他个人对于将 HTML 文件与 Claude Code 一起使用的观点——以及喜爱。