Claude Code 团队成员 Thariq 分享：为什么他放弃了 Markdown，开始让 Claude 输出 HTML——更丰富的可视化、更容易分享、更高的实际阅读率。

在 Claude Code 中用 HTML 替代 Markdown

来源：@trq212（2026 年 5 月 10 日）

Markdown 一直是 Agent 与我们沟通的主流格式。它简单、轻便、有基础的富文本能力，而且你可以直接编辑。Claude 甚至已经能用 ASCII 在 Markdown 文件里画出像样的图表。

但随着 Agent 越来越强大，我越来越觉得 Markdown 开始成为一种限制。超过一百行的 Markdown 文件，我根本读不下去。我想要更丰富的可视化——颜色、图表，并且能方便地分享出去。

另外，我现在越来越少自己编辑这些文件，更多是把它们当作规格文档、参考资料或头脑风暴的输出来用。即便要修改，也是让 Claude 来改——这样一来 Markdown 最大的优势之一（易于手动编辑）也就消失了。

我已经开始用 HTML 代替 Markdown 作为输出格式，而且我注意到 Claude Code 团队里越来越多的人也在这样做。这篇文章说说原因。

为什么 HTML 更强

HTML 能传递的信息远比 Markdown 丰富。基本的文档结构（标题、格式）当然没问题，但它还能表达：

用表格呈现结构化数据
用 CSS 呈现设计信息
用 SVG 绘制插图
用 <script> 标签展示代码片段
用 JavaScript + CSS 实现交互
用 SVG + HTML 描述工作流
用绝对定位和 Canvas 呈现空间数据
用 <img> 标签嵌入图片

可以这样说：Claude 能读懂的任何信息，你都能用 HTML 高效地表达出来。这让 HTML 成为模型向你传递深度信息、供你审阅的极佳载体。

没有 HTML 的时候，模型往往会在 Markdown 里做一些低效的替代，比如用 ASCII 画图，或者——我最爱举的例子——用 Unicode 字符来"估算"颜色：

Claude Code 在 Markdown 里试图用 Unicode 字符表示颜色

可读性更强

随着 Claude 能完成越来越复杂的工作，它写的规格文档和计划也越来越长。实际上，超过一百行的 Markdown 文件我基本不会认真读，更不用说让团队里其他人去读了。

HTML 文档就好多了——Claude 可以用标签页、插图、链接等方式组织视觉结构，让导航变得很自然。甚至可以做成移动端自适应，根据你的设备显示不同的布局。

更容易分享

Markdown 文件很难分享，因为大多数浏览器无法原生渲染它。你通常需要把它作为附件发送。

HTML 就不一样了——只要把文件上传到 S3 之类的地方，你就能直接分享链接，对方在任何地方都可以打开，随时引用。

你的规格文档、报告、PR 说明，被人真正阅读的概率，用 HTML 要高得多。

可交互

HTML 让文档变得可交互。比如你可以让 Claude 加上滑块或旋钮，实时调整设计参数，或者切换算法的不同选项，看看效果如何。还可以让它加一个"复制"按钮，把修改内容直接复制成 Prompt，粘贴回 Claude Code 继续操作。

为什么用 Claude Code 而不是 Claude.ai 生成 HTML

最大的原因是上下文摄入能力。Claude Code 可以读取你的整个代码库、调用 MCP（Slack、Linear 等）、访问浏览器（Chrome 插件）、翻阅 Git 历史……

举个例子：在写这篇文章的时候，我让 Claude Code 扫描我的代码文件夹，找出所有生成过的 HTML 文件，按类型分组，然后做成一个带图解的 HTML 总览页面。文章里那些图表，就是这样来的。

另外，让 Claude 生成 HTML 文件本身就更有意思，让我感觉更有参与感——光这一点就够了。

我有点担心有人读完这篇文章就去做一个 /html Skill。这样也许有点用，但我想强调：你根本不需要做什么特殊配置。直接告诉它"做一个 HTML 文件"或者"做一个 HTML Artifact"就行了。关键是想清楚你要这个文件做什么、怎么用它。

六大使用场景

1. 规划与头脑风暴

HTML 是一块可以深入探索问题的富画布。开始一个新问题时，我不再要一个简单的 Markdown 计划，而是期待产出一系列 HTML 文件：

先让 Claude Code 头脑风暴，生成几个不同方向的探索文档
再深入展开其中一个方向，生成 Mockup 或代码片段
满意后再写实现计划
新开一个 Session，把这些文件全部传入让它执行

验收时也可以让验证 Agent 读入这些文件，它能获得更全面的上下文。

示例提示词：

我不确定新手引导页面该往哪个方向走。生成 6 种风格截然不同的方案——布局、语气、信息密度各有差异——把它们并排排在一个 HTML 文件的网格里，方便我对比。每个方案标注它在做什么权衡取舍。

写一份完整的实现计划，用 HTML 文件，加上 Mockup、数据流图和我可能需要审阅的关键代码片段。要易于阅读和消化。

2. 代码审查与 PR 说明

代码在 Markdown 里很难阅读，但 HTML 可以渲染 diff、注释、流程图、模块关系图等。用这个来理解 Agent 写的代码、做代码审查，或者向审查者解释一个 PR。

我发现这往往比 GitHub 默认的 diff 视图更好用，现在我每个 PR 都会附上一个 HTML 代码解读文件。

示例提示词：

帮我审查这个 PR，做一个 HTML Artifact 来描述它。我对 streaming/backpressure 逻辑不太熟，重点讲这部分。用带行内注释的 diff 渲染，按严重程度给发现的问题标颜色，再加上其他有助于理解的内容。

3. 设计原型

Claude Design 本身就基于 HTML，因为 HTML 在设计表达上极其灵活——即便你最终的目标平台不是 HTML 也没关系。Claude 可以先在 HTML 里画出设计草图，然后再转成 React、Swift 等你需要的语言。

你还可以原型化交互效果，比如动画、手势等。可以让 Claude 加上滑块和旋钮，精确调出你想要的效果。

示例提示词：

我想给结算按钮做一个原型：点击后先播放一个扩散动画，然后迅速变成紫色。做一个 HTML 文件，加几个滑块和选项让我试不同的动画参数，再加一个"复制参数"按钮，方便我把调好的参数复制出来。

4. 报告与技术解读

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

可以做成长篇 HTML 文档、交互式解读页面，甚至幻灯片。让 Claude 用 SVG 画图来辅助说明。

示例提示词：

我搞不清楚我们的限速器到底是怎么工作的。读相关代码，生成一个 HTML 解读页面：Token Bucket 的流程图、3-4 个关键代码片段加注释、底部一个"注意事项"部分。针对只读一遍的人优化。

适用场景：

解释某个功能的运作原理
向领导汇报周进展
写故障复盘报告
生成 SVG 插图、流程图、技术架构图

5. 一次性定制编辑器

有时候你很难用纯文字描述你想要什么。这时我会让 Claude 给我做一个专门为当前任务定制的编辑器——不是产品，不是可复用工具，就是一个一次性的 HTML 文件，专门用来处理这一份数据。

关键点：最后一定要加导出功能——一个"复制为 JSON"或"复制为提示词"的按钮，把我在 UI 里做的操作转回可以粘贴进 Claude Code 的内容。

示例提示词：

我需要重新排列这 30 个 Linear 工单的优先级。做一个 HTML 文件，把每个工单做成可拖拽的卡片，分成"现在 / 下一步 / 以后 / 砍掉"四列。按你的判断预排序。加一个"复制为 Markdown"按钮，导出最终排列顺序，每个 bucket 附一行理由说明。

这是我们的功能开关配置。给它做一个表单式编辑器，按功能区域分组，显示开关之间的依赖关系，如果我启用了一个前置条件未开启的开关就发出警告。加一个"复制 diff"按钮，只输出改动的键。

我在调这个 System Prompt。做一个左右分栏编辑器：左边是可编辑的提示词，变量槽高亮显示；右边三个示例输入，实时渲染填充后的效果。加字符/Token 计数器和复制按钮。

常见问题

Token 消耗不是更多吗？ Markdown 通常用更少的 Token，但 HTML 的表达力更强，而且我实际读它的概率也高得多——综合来看输出质量更好。有了 Opus 4.7 的 100 万 Token 上下文窗口，增加的 Token 消耗根本感觉不到。

你什么时候还会用 Markdown？ 说实话，我现在几乎完全不用 Markdown 了——但我可能是 HTML 重度派里走得比较远的一个。

怎么查看 HTML 文件？ 直接在浏览器里本地打开（可以让 Claude 帮你打开），或者上传到 S3 获得可分享的链接。

生成时间不是更长吗？ 确实，HTML 比 Markdown 慢 2-4 倍。但结果值得等。

版本控制怎么办？ 这是 HTML 最大的缺点之一——HTML diff 比 Markdown diff 噪音更多、更难审查。

怎么让 Claude 做出符合我品味的设计？ frontend-design 插件能帮 Claude 生成更好看的 HTML。如果想匹配公司风格，可以先让 Claude 扫描你的代码库，生成一个设计系统 HTML 文件，之后用它作为其他 HTML 文件的参考。

小结

我用 HTML 的真正原因，是它让我对 Claude 的工作始终有掌控感。

我曾经担心：因为我不再深读计划文档，只能把决策权完全交给 Claude。但现在，用了 HTML 之后，我反而比以前更清楚它在做什么了。