Claude Code 团队工程师：我为什么放弃 Markdown，全面转向 HTML

作者：Thariq (@trq212) 原文发表于 2026 年 5 月 9 日

Markdown 已经成为 AI agent 与我们沟通时的主流文件格式。它简洁、可移植，具备一定的富文本能力，并且便于编辑。Claude 甚至已经擅长在 Markdown 文件中用 ASCII 字符绘制图表。

但随着 agent 能力越来越强，我开始觉得 Markdown 成了一种束缚。超过 100 行的 Markdown 文件我读起来就很吃力。我想要更丰富的可视化效果——色彩、图表，并且希望能轻松分享。

我也越来越少亲自编辑这些文件，而是把它们当作规格说明、参考文档、头脑风暴的产物。当我确实需要修改时，通常也是让 Claude 来改，这就抹掉了 Markdown 最大的优势之一。

我现在已经开始更倾向于把 HTML 作为输出格式，而不是 Markdown。我也看到 Claude Code 团队的越来越多人这么做。下面就说说为什么。

如果你想直接看一些示例，可以访问：thariqs.github.io/html-effect… 不过看完记得回来读完原因部分。

为什么选 HTML？

信息密度

相比 Markdown，HTML 能承载的信息要丰富得多。它当然能处理文档基本结构，比如标题和格式化文本，还能表达：

image.png

• 表格数据：通过 table
• 设计数据：通过 CSS
• 插图：通过 SVG
• 代码片段：通过 script 标签
• 交互：通过 HTML 元素 + JavaScript + CSS
• 工作流：通过 SVG 和 HTML
• 空间数据：通过绝对定位和 canvas
• 图片：通过 image 标签

我甚至想说：几乎所有 Claude 能读懂的信息，都可以用 HTML 高效地表达出来。这让 HTML 成为模型向你深度传达信息、以及你回顾这些信息的高效媒介。

我发现，在没有 HTML 时，模型会做一些 Markdown 里效率很低的事情，比如画 ASCII 图，或者我最爱的——用 unicode 字符来近似呈现颜色（就像下面这张 Claude Code 的截图）。

image.png

视觉清晰度与阅读体验

随着 Claude 能完成的工作越来越复杂，它写的规格说明和方案也越来越长。实际上我发现，自己很少会真的读完一个超过 100 行的 Markdown 文件，团队里其他人就更难指望了。

image.png

但 HTML 文档读起来要轻松得多。Claude 可以在视觉上组织好结构，使用标签页、插图、链接等使导航更直观。它甚至可以做成响应式的，让你在不同设备上都有合适的阅读体验。

易于分享

Markdown 文件不太好分享，因为大多数浏览器不能原生渲染它们。你常常需要把它作为附件加到邮件或消息里。

而 HTML 只要上传一下（比如到 S3），就能直接分享链接。同事可以在任何地方打开它、随时引用。

把规格说明、报告或 PR 描述写成 HTML，别人真的会去读的概率要高得多。

双向交互

HTML 让文档变得可交互。比如，你可以让它加上滑块和旋钮来调整设计，或让你尝试算法中不同选项产生的效果。你甚至可以让它加一个按钮，把这些改动复制成 prompt，再粘贴回 Claude Code。

image.png

更多关于这种双向交互的例子，可以读我那篇 playground 相关的帖子：x.com/trq212/stat…

数据接入

为什么是用 Claude Code 来生成 HTML，而不是 ClaudeAI 或 Claude Design？最大的原因之一就是 Claude Code 能接入的上下文实在太丰富了。

举个例子，写这篇文章时，我让 Claude Code 翻遍我的代码目录，找出所有我生成过的 HTML 文件，做分类整理，然后生成一个用图表展示每种类型的 HTML 文件。本文中那些图表就是这么来的。

除了文件系统，Claude Code 还能通过你的 MCP（如 Slack、Linear 等）、浏览器（用 Claude in Chrome）、git 历史等渠道获取上下文。

让人愉悦

用 Claude 生成 HTML 文档这件事本身就更有趣，让我感觉自己更深入地参与并投入到创造之中。光这一点，就足够了。

如何开始

我有点担心有人读完这篇文章会去搞个 /html skill 之类的东西。虽然这或许有点价值，但我想强调：你几乎不需要做什么就能让 Claude 这么干。直接说"做一个 HTML 文件"或"做一个 HTML artifact"就行。

关键在于你知道自己想要这个 artifact 做什么，以及怎么用它。也许你以后会做一个 skill，但目前我建议你先从零开始 prompt，找找在不同场景下使用它的感觉。

使用案例

为了让讨论更具体，我做了大量不同用途的 HTML 文件。完整示例可以看：thariqs.github.io/html-effect… 这里我做个概览。

规格说明、规划与探索

HTML 是 Claude 深入剖析问题的丰富画布。开始处理一个问题时，我不再是写一个简单的 Markdown 方案，而是期望生成一组 HTML 文件构成的网络。

比如，我可能先让 Claude Code 头脑风暴并探索一些不同方案；然后挑一个深入展开，做做原型或代码片段；最后觉得满意了，让它写一份实施方案。当我对方案满意后，开一个新会话，把这些文件都传进去让它实施。

image.png

验证阶段，我也会让验证 agent 读取这些文件，它就能获得更广的上下文。

示例 Prompt：

我不确定该往哪个方向做引导界面。生成 6 种截然不同的方案——在布局、调性、信息密度上都要有差异——把它们排成网格放在一个 HTML 文件里供我对比。每个都标注它在做什么取舍。

写一份详尽的实施方案到一个 HTML 文件里，要包括一些原型图、数据流，以及我可能想看的关键代码片段。让它易读易消化。

适用场景：

• 探索代码实现的不同方式
• 探索多种视觉设计方案

代码评审与理解

代码在 Markdown 文件里很难读。但 HTML 可以渲染 diff、注释、流程图、模块图等。可以用它来理解 agent 写的代码、做代码评审、或者向他人解释你的 PR。我发现这经常比 GitHub 默认的 diff 视图更好用，现在我每个 PR 都会附上一个 HTML 代码讲解。

示例 Prompt：

帮我评审这个 PR，做一个 HTML artifact 来描述它。我对其中的流式/背压逻辑不太熟悉，重点关注那部分。把 diff 渲染出来，在边栏加上行内注释，按严重程度给发现的问题着色，以及任何能更好表达概念所需的内容。

image.png

适用场景：

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

设计与原型

Claude Design 是基于 HTML 的，因为 HTML 在表达设计方面非常有表现力，即使你最终的目标不是 HTML。Claude 可以先用 HTML 勾勒设计，然后再翻译成你想用的语言——React、Swift 都行。

你也可以原型化交互，比如动画、操作等等。可以让 Claude 加上滑块、旋钮，方便你精细调出想要的效果。

image.png

示例 Prompt：

我想做一个新的结账按钮原型，点击时先播放一个动画然后快速变成紫色。做一个 HTML 文件，提供多个滑块和选项让我尝试这个动画的不同效果，加一个复制按钮让我能复制效果好的参数。

适用场景：

• 创建设计系统 artifact
• 调整组件
• 可视化组件库
• 制作富有趣味的动画原型

报告、研究与学习

Claude Code 非常擅长综合多个数据源的信息，把它转化为可读性极强的报告。你可以让 Claude 搜索你的 Slack、代码库、git 历史、互联网等等，生成给自己、给领导、给团队看的报告。

可以做成长篇 HTML 文档、交互式讲解，甚至幻灯片/演示稿。让 Claude 用 SVG 画图来辅助可视化。

image.png

比如，写关于 prompt caching 的帖子时，我让 Claude 读完 git 历史后，准备了一份关于我们对 prompt caching 所做修改的深度 HTML 研究文档。

示例 Prompt：

我搞不懂我们的限流器到底是怎么工作的。读相关代码，输出一个 HTML 讲解页：一张令牌桶流程图，3-4 段加注释的关键代码片段，底部加一个"易踩坑点"小节。优化为只读一遍就能看懂的形式。

适用场景：

• 总结一个功能的工作原理
• 向我解释一个概念
• 向老板汇报每周状态
• 向领导上报事故报告
• SVG 插图、流程图、技术示意图等

自定义编辑界面

有时候，纯文本框很难描述清楚你想要的东西。这种情况下，我会让 Claude 给我做一个一次性的编辑器，专门针对我手头这件事。不是产品，也不是可复用的工具——就是一个 HTML 文件，专门为这一份数据服务。

image.png

诀窍永远是：以一个导出按钮收尾——"复制为 JSON"或"复制为 prompt"，把我在 UI 中做的事变成可以粘回 Claude Code 的内容。

示例 Prompts：

我需要重新排序这 30 个 Linear 工单。做一个 HTML 文件，每个工单是一张可拖拽的卡片，分布在 Now / Next / Later / Cut 四列中。先按你的最佳猜测排好。加一个"复制为 markdown"按钮，导出最终排序，每一列附一行简短的理由。

这是我们的功能开关配置。给我做一个表单式编辑器：按领域分组，展示开关之间的依赖关系，如果我打开了一个开关但其前置开关是关闭的就发出警告。加一个"复制 diff"按钮，只给我变更过的 key。

我在调一个系统 prompt。做一个并排编辑器：左边是可编辑的 prompt，变量插槽要高亮；右边是三个示例输入，实时渲染填充后的模板。加一个字符/token 计数器和一个复制按钮。

适用场景：

• 重排序、分诊、归类任何东西（工单、测试用例、反馈）
• 编辑结构化配置（功能开关、环境变量、带约束的 JSON/YAML）
• 调试 prompt、模板、文案，带实时预览
• 整理数据集，逐行批准/拒绝、打标签、导出选中项
• 给文档、转录稿或 diff 加注释，导出注释结果
• 选择那些用文字很难表达的值：颜色、缓动曲线、裁剪区域、cron 时间、正则表达式

常见问题

跟很多人聊过我转向 HTML 的事情，遇到了一些反复出现的问题。

Q：HTML 不是更费 token 吗？

虽然 Markdown 通常用更少的 token，但我发现 HTML 带来的额外表达能力，加上我读它的可能性大大提高，整体收益更好。在 Opus 4.7 1MM 的上下文窗口下，多用一些 token 在窗口里几乎感受不到。

Q：你现在还在哪些场景用 Markdown？

老实说我几乎已经完全不用 Markdown 了，不过我可能算 HTML 极端派。

Q：怎么查看 HTML 文件？

我一般直接在本地浏览器打开（可以让 Claude 帮你打开），或者上传到 S3 获得分享链接。

Q：生成 HTML 不是比 Markdown 更慢吗？

确实更慢！HTML 比 Markdown 慢 2-4 倍，但我觉得结果是值得的。

Q：版本控制怎么办？

这老实说是 HTML 最大的缺点之一。HTML 的 diff 又乱又难评审，不如 Markdown。

Q：怎么让 Claude 符合我的审美/不做出丑东西？

frontend design 插件能帮 Claude 写出好看的 HTML 文件。如果想匹配你公司的风格，可以让 Claude 读你的代码库，生成一个统一的设计系统 HTML 文件。然后把这个设计系统文件作为其他 HTML 文件的参考。

保持在环（Stay in the Loop）

上面这一切归根结底是要说：我用 HTML 的真正原因是，我感觉自己和 Claude 协作时更"在环"中。

之前我开始担心，因为不再深入读方案，我就只能放手让 Claude 自己做选择。但现在使用 HTML 让我反而比以前更觉得自己在环中。希望你也有同样的体验。

原作者：Thariq（@trq212），Claude Code 团队成员。曾就读 YC W20、@southpkcommons、@medialab。