为什么 Claude Code 团队越来越少用 Markdown，而开始偏爱 HTML

前言

有一个很反直觉的变化正在发生：当 AI agent 越来越强，Markdown 反而开始显得不够用了。

Thariq 在 X 上发布了一篇文章，讨论自己为什么在使用 Claude Code 时，越来越偏爱让 Claude 输出 HTML，而不是 Markdown。文章后来也同步发布在 Claude Blog。

这不是在说 Markdown 过时了。Markdown 依然简单、可移植、易编辑，也仍然适合笔记、README 和轻量文档。

但当 Claude Code 开始写复杂规格、产品方案、代码评审、研究报告、交互原型时，问题就变了：

不是“模型能不能写出来”，而是“人还能不能读进去、看明白、改得动、分享出去”。

作者的核心判断是：HTML 不只是更漂亮的输出格式，它能让人与 agent 的协作重新变得可见、可读、可控。

为什么是 HTML

Markdown 已经成为智能体与人沟通时最常见的文件格式。它轻量、通用、有基础富文本能力，也方便手动编辑。Claude 甚至已经很擅长在 Markdown 里用 ASCII 画图。

但作者认为，随着 agent 能做的事情越来越复杂，Markdown 正在变成限制。

一份超过一百行的 Markdown 文件，理论上很清晰，现实中却很少有人认真读完。更糟的是，规划、规格说明、研究报告、头脑风暴结果这些内容，本来就需要颜色、图表、布局、交互和更强的视觉组织。

还有一个变化更关键：很多时候，用户已经不再亲手编辑 Markdown，而是把它们当作规格、参考资料或分析输出，再让 Claude 继续修改。

这意味着 Markdown 最大的优势之一：“人可以方便地手改”，正在被 agent 工作流削弱。

信息密度：HTML 能表达更多种信息

HTML 能表达的信息远比 Markdown 丰富。除了标题、段落、加粗等基础文档结构，它还可以表达：

•表格数据；

•通过 CSS 呈现的设计信息；

•SVG 插画；

•script 标签中的代码片段；

•使用 JavaScript 和 CSS 的交互；

•用 SVG 与 HTML 组合出的工作流；

•使用绝对定位和 canvas 表示空间信息；

•通过 image 标签承载图片。

作者甚至认为：只要 Claude 能读懂某种信息，就几乎都能用 HTML 高效表达出来。

这使 HTML 成为一种高带宽沟通方式。它不只是把文本排漂亮，而是让模型能用更接近人类认知的方式展示复杂信息。

如果没有 HTML，模型可能会在 Markdown 里做一些低效表达，比如 ASCII 图，甚至用 Unicode 方块估算颜色。

Claude Code 尝试在 Markdown 中展示颜色。

可读性：不是生成更多，而是让人真的读完

随着 Claude 能处理更复杂的任务，它写出的规格说明和计划也越来越长。

作者提到，现实中自己很少真正读完超过 100 行的 Markdown 文件，更难让组织里的其他人去读。

HTML 文档可以用标签页、插图、链接、卡片、网格和分区来组织内容。它能把一份复杂计划变成一个可以浏览、跳转、比较、扫读的界面。

它还可以做响应式布局，让同一份内容在桌面、平板和手机上呈现不同阅读体验。

这一点很重要：agent 输出的价值，不只取决于它写了多少，还取决于人能不能吸收。

分享：HTML 更容易成为团队材料

Markdown 文件不太容易分享，因为浏览器通常不会原生优雅渲染 Markdown。很多时候只能把它作为邮件或聊天附件发出去。

HTML 则只要上传到一个地方，例如 S3，就可以直接分享链接。

团队成员可以在任何浏览器里打开、引用和阅读。作者认为，如果希望别人真的阅读规格说明、报告或 PR 说明，HTML 的成功概率要高得多。

一句话概括：

Markdown 更像写给自己看的草稿；HTML 更像可以交给团队阅读的工作界面。

双向交互：文档可以反过来帮你操作

HTML 不只是静态阅读格式，它还能让用户和文档互动。

例如，可以让 Claude 在文档里加入滑块、旋钮或选项控件，用来调整设计参数，或者改变算法参数并实时查看结果。

也可以让页面生成一段 prompt，方便复制回 Claude Code 继续迭代。

作者还提到，他之前关于 playgrounds 的文章里有更多这种双向交互示例。

这类 HTML 文档的价值不只是“展示”，而是让阅读者能在文档里做选择、调参数、导出结果，再把结果带回 agent 工作流。

数据摄取：为什么是 Claude Code，而不是普通聊天窗口

为什么要用 Claude Code 生成 HTML，而不是直接用 Claude.ai 或 Claude Design？

作者认为，一个关键原因是 Claude Code 能读取大量上下文。

比如这篇文章的图，就是他让 Claude Code 扫描自己的代码文件夹，找出所有生成过的 HTML 文件，分类汇总后再制作出来的。

除了文件系统，Claude Code 还能通过 MCP 获取 Slack、Linear 等上下文，也可以利用浏览器、Git 历史等信息。

换句话说，HTML 是输出形式，而 Claude Code 的本地上下文能力决定了输出内容的深度。

这也是为什么 HTML 在 Claude Code 里特别有效：它不是孤立生成一个漂亮页面，而是把本地项目、代码、历史和协作信息重新组织成可读材料。

乐趣：这不是小事

作者给了一个很主观但重要的理由：用 Claude 制作 HTML 文档更有趣，也让人更有参与感和投入感。

这一点本身就足够成为使用它的理由。

在 agent 工作流里，“乐趣”不是装饰。它直接影响用户是否愿意阅读、调整、继续追问，并保持在循环中。

如何开始：不用先做 skill

作者提醒，不必一上来就把这件事做成 /html skill。也许以后有价值，但刚开始完全不需要复杂化。

可以直接对 Claude 说：

•“做一个 HTML 文件。”

•“做一个 HTML artifact。”

关键不是命令形式，而是知道想让这个 artifact 做什么、会如何使用它。

先从具体场景开始，等用多了，再沉淀成 skill。

场景一：规格、规划与探索

HTML 是一个适合 Claude 深入问题的画布。

面对复杂问题时，作者不再期待只得到一个简单 Markdown 计划，而是希望生成一组相互关联的 HTML 文件。

常见流程是：

1先让 Claude Code 头脑风暴，生成多个探索方向；

2再扩展其中一个方向，加入 mockup、代码片段或数据流；

3最后在方向清楚后写实现计划；

4开新会话时，把这些 HTML 文件作为上下文传进去；

5验证时，也让 verifier 读取这些文件，从而获得更完整背景。

示例提示词：

我不确定 onboarding 页面应该走什么方向。生成 6 种明显不同的方法，改变布局、语气和信息密度，把它们放在一个 HTML 文件的网格里，方便并排比较。每个方案都标注它做出的取舍。 创建一个完整的 HTML 实现计划，包含 mockup、数据流，以及我可能需要审阅的重要代码片段。让它容易阅读和消化。

适合用于：

•探索代码实现方案；

•探索多个视觉设计方向。

场景二：代码评审与理解

代码在 Markdown 里并不容易阅读。但 HTML 可以渲染 diff、注释、流程图、模块关系等。

作者会用 HTML 理解 agent 写出的代码、做 code review，或者向别人解释 PR。他甚至表示，现在每个 PR 都会附一个 HTML code explainer，而且有时比 GitHub 默认 diff 更好用。

示例提示词：

帮我审这个 PR，创建一个 HTML artifact 来解释它。我不太熟悉 streaming/backpressure 逻辑，所以重点解释这部分。渲染真实 diff，加入行边注释，按严重程度给发现的问题上色，并加入任何有助于理解概念的内容。

适合用于：

•创建 PR；

•审查 PR；

•理解代码中的某个主题。

场景三：设计与原型

Claude Design 基于 HTML，是因为 HTML 对设计表达非常强。即使最终实现目标不是 HTML，Claude 也可以先用 HTML 草拟设计，再转换为 React、Swift 或其他语言。

它还适合做交互原型，例如动画、点击行为、参数调节等。可以让 Claude 加入滑块和旋钮，帮助精确调试效果。

示例提示词：

我想原型化一个新的 checkout 按钮，点击时播放动画，然后快速变成紫色。创建一个 HTML 文件，加入几个滑块和选项，让我尝试不同动画参数，并提供复制按钮，复制我调好的参数。

适合用于：

•创建设计系统 artifact；

•调整组件；

•可视化组件库；

•原型化有趣的动画。

场景四：报告、研究与学习

Claude Code 很擅长综合多个数据源，并把结果整理成可读报告。

可以让它搜索 Slack、代码库、Git 历史和互联网，然后为个人、团队或管理层生成报告。

报告形式可以是长 HTML 文档、交互式解释器，甚至是 slideshow/deck。作者建议使用 SVG 来做图表、流程图和技术插图。

作者举例说，自己在写 prompt caching 相关内容时，就让 Claude 读取 Git 历史，生成了一份深入研究的 HTML 文件。

示例提示词：

我不理解我们的 rate limiter 是怎么工作的。阅读相关代码，生成一个单页 HTML 解释器：包含 token-bucket 流程图、3 到 4 段关键代码片段注释，以及底部的 gotchas 区。优化成适合只读一遍的人理解。

适合用于：

•总结某个功能如何工作；

•解释一个概念；

•给老板写周报；

•给管理层写事故报告；

•制作 SVG 插图、流程图和技术图。

场景五：一次性编辑界面

有些需求很难只通过文本框描述清楚。作者会让 Claude 为当前任务构建一个一次性的编辑器。

这不是产品，也不是可复用工具，而是为某一份数据或某一个决策专门生成的单个 HTML 文件。

关键是：最后一定要有导出能力。例如 “copy as JSON” 或 “copy as prompt” 按钮，把用户在界面里的操作重新转回可以粘贴进 Claude Code 的文本。

示例提示词：

我需要重新排列 30 个 Linear tickets。做一个 HTML 文件，把每个 ticket 做成可拖拽卡片，分成 Now / Next / Later / Cut 四列。先按你的判断预排序。加一个 “copy as markdown” 按钮，导出最终排序和每个 bucket 的一句话理由。 这是我们的 feature flag 配置。做一个表单式编辑器，按区域分组 flag，展示依赖关系，如果打开某个前置依赖关闭的 flag 就警告我。加一个 “copy diff” 按钮，只导出发生变化的 key。 我正在调系统提示词。做一个左右分栏编辑器：左边是可编辑 prompt，并高亮变量槽位；右边是三个样例输入，实时渲染填充后的模板。加入字符/token 计数器和复制按钮。

适合用于：

•重排、分桶、筛选 tickets、测试用例或反馈；

•编辑结构化配置，如 feature flags、env vars、JSON/YAML；

•调整 prompts、模板或文案，并实时预览；

•筛选数据集、批准/拒绝行、打标签并导出；

•标注文档、转录稿或 diff，并导出标注；

•选择很难用文本表达的值，如颜色、缓动曲线、裁剪区域、cron、正则表达式。

常见问题

HTML 会不会更浪费 token？

Markdown 通常更省 token，但作者认为 HTML 的表达能力更强，而且自己更愿意阅读，因此总体效果更好。在更大的上下文窗口里，额外 token 消耗不再那么明显。

现在什么时候还用 Markdown？

作者坦言，自己几乎已经不用 Markdown 做大多数事情，不过这也可能是比较极端的 HTML 最大化立场。

怎么查看 HTML 文件？

通常直接在本地浏览器打开，也可以上传到 S3 获取可分享链接。

生成 HTML 会不会更慢？

会。HTML 可能比 Markdown 慢 2 到 4 倍，但作者认为结果值得。

版本控制怎么办？

这是 HTML 的主要缺点之一：HTML diff 很吵，比 Markdown 难审。

怎样让 Claude 生成符合品味、不要难看的 HTML？

可以使用 frontend design plugin 帮 Claude 生成更好的 HTML。若要贴合公司风格，可以让 Claude 读取代码库，生成一份设计系统 HTML 文件，再把它作为后续 HTML 文件的参考。

最后的观点：让人保持在循环里

作者最后说，自己使用 HTML 的真正原因，是它让自己更能参与 Claude 的工作过程。

当他发现自己不再仔细阅读 Markdown 计划时，曾担心自己只能放手让 Claude 自行决策。但改用 HTML 后，他反而比以前更能理解、审阅和参与 Claude 的工作。

这也是整篇文章最重要的结论：

HTML 不只是更漂亮的输出格式，它让人与 agent 的协作回到了更可见、更可读、更可控的循环中。

真正值得借鉴的不是“以后所有文档都必须用 HTML”，而是这个判断：

当 agent 的输出越来越复杂，输出格式本身就会成为协作质量的一部分。

声明

本文由山行整理自：X 原帖[1] 与 Claude Blog 同源文章[2]，如果对您有帮助，请帮忙点赞、关注、收藏，谢谢～

参考链接

[1] X 原帖: https://x.com/trq212/status/2052809885763747935

[2] Claude Blog 同源文章: https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html