Claude Code团队弃用Markdown转HTML的深度解析

引言

一个反直觉的趋势正在成型：随着AI Agent的能力边界持续扩展，Markdown在处理复杂输出时逐渐暴露出结构性短板。

近期，开发者Thariq在X平台分享了他使用Claude Code的实战经验——他越来越倾向于引导模型直接输出HTML，而非常规的Markdown。这一观点随后被Claude官方博客收录并推荐。

这并非宣告Markdown的终结。Markdown凭借其简洁、便携和易编辑的特性，在笔记、README或轻量文档场景中仍然无可替代。

但当Claude Code开始处理更复杂的任务——如撰写详尽的规格文档、产品方案、代码审计、研究报告，甚至构建交互式原型时，问题性质就完全不同了。

Thariq的核心判断是：HTML的真正价值不在于输出格式的视觉提升，而在于它让人与AI agent之间的协作重新变得透明、易读且可控。

为何选择HTML

Markdown目前已成为AI与人类沟通的标准文件格式。它轻量、通用、具备基础富文本能力，手动编辑也极为便捷。Claude甚至早已擅长在Markdown中通过ASCII字符绘制图表。

但问题随之浮现：当Agent能处理的事务愈发复杂时，Markdown反而成了一个隐性瓶颈。

一份超过100行的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能处理的任务越来越繁重，它产出的规格说明和计划也变得越来越长。一个严峻的现实是——Thariq坦言，自己都很少真正读完超过100行的Markdown文件，更别提团队中的其他人了。

HTML文档则不同。它可以通过标签页、插图、链接、卡片、网格和分区来组织内容。本质上，它将一份复杂计划转化成了一个可浏览、跳转、比较和扫读的界面。

不仅如此，HTML还能实现响应式布局，让同一份内容在桌面、平板和手机上呈现截然不同的阅读体验。

这一点至关重要：Agent输出的价值，不仅取决于它生成了多少内容，更关键在于人能否真正消化与吸收。

分享：HTML更易转化为团队文档

Markdown文件的分享体验并不理想，因为浏览器通常不会原生地优雅渲染它。多数情况下，只能作为邮件或聊天软件附件发送。

HTML则简单直接：只要上传到某个位置，比如S3存储，直接分享链接即可。团队成员可以在任何浏览器中打开、引用和阅读。如果你希望团队成员真正阅读那些规格说明、报告或PR描述，HTML的“成功率”显然更高。

换句话说，就是：

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

HTML不仅仅是静态的阅读格式，它还能让用户与文档产生真实互动。

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

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

Thariq提到，他之前一篇关于playgrounds的文章中提供了更多这类双向交互的案例。

这类HTML文档的价值远超“展示”范畴，而是让阅读者能在文档中做选择、调参数、导出结果，再将结果重新注入Agent工作流。

数据摄取：为何是Claude Code，而非普通聊天窗口

那么问题来了，为什么一定要用Claude Code来生成HTML，而不是直接用Claude.ai或Claude Design？

关键原因在于，Claude Code能够读取大量上下文信息。

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

不止文件系统，Claude Code还能通过MCP获取Slack、Linear等上下文信息，也能利用浏览器、Git历史等数据。换句话说，HTML只是输出形式，而Claude Code的本地上下文能力，才是决定输出内容深度的根本所在。

这也解释了为什么HTML在Claude Code中特别有效——它并非孤立地生成一个漂亮页面，而是把本地项目、代码、历史记录和协作信息重新组织成一份高可读性的材料。

乐趣：这不是小事

Thariq给出了一个非常主观、但又极具分量的理由：用Claude制作HTML文档，整个过程更有趣，也让人更有参与感和投入度。

这一点本身，就已经足够成为使用它的理由了。在Agent工作流中，“乐趣”并不仅仅是锦上添花的点缀，它直接影响用户是否愿意阅读、调整、继续追问，并持续保持协作的循环。

如何开始：无需先创建skill

Thariq特别提醒，不必一开始就想着把这个流程固化为一个/html skill。将来或许有价值，但起步时完全没必要把事情复杂化。

直接对Claude说就行：

• “帮我写一个HTML文件。”*
• “做一个HTML artifact。”*

关键不在于命令的具体措辞，而是你希望这个artifact实现什么功能，以及你打算如何使用它。先从实际场景出发，等用熟练了，再沉淀为skill。

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

HTML是适合Claude“深入挖掘问题”的画布。面对复杂问题时，Thariq说他已经不再期待只得到一个简单的Markdown计划，而是希望生成一组相互关联的HTML文件。

常见流程大致如下：

1. 先让Claude Code进行头脑风暴，生成多个探索方向；
2. 再挑选其中一个方向深入，加入mockup、代码片段或数据流；
3. 明确方向后，撰写具体的实现计划；
4. 新开会话时，将这些HTML文件作为上下文传入；
5. 验证阶段，也让verifier读取这些文件，从而获得更完整的背景信息。

示例提示词：（此处原文可能有具体的提示词，但未能精准解析，此处保留原文结构）

这个场景适用于：探索代码实现方案，或探索多个视觉设计方向。

场景二：代码评审与理解

代码在Markdown中查看，体验并不理想。但HTML可以渲染diff、注释、流程图、模块关系等复杂信息。

Thariq会用HTML来理解Agent生成的代码、进行代码审查，或向团队中其他人解释PR。他甚至表示，现在每次发PR，都会附带一个HTML版的代码解释器，而且有时它比GitHub默认的diff视图更好用。

示例提示词：（此处原文可能有具体的提示词，但未能精准解析，此处保留原文结构）

这个场景尤其适合：创建PR、审查PR、理解代码库中的特定主题。

场景三：设计与原型

Claude Design底层基于HTML，正是因为HTML在设计表达上能力极强。即便最终的目标实现语言不是HTML，Claude也可以先用HTML生成设计草图，再转换成React、Swift或其他语言。

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

示例提示词：（此处原文可能有具体的提示词，但未能精准解析，此处保留原文结构）

这个场景适用于：创建设计系统artifact、调整组件、可视化组件库、原型化有趣的动画效果。

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

Claude Code非常擅长综合多个数据源，并将结果整理成结构清晰的可读报告。可以让它搜索Slack、代码库、Git历史和互联网，然后为个人、团队甚至管理层生成针对性报告。

报告形式可以很灵活：长HTML文档、交互式解释器，甚至做成幻灯片都行。Thariq特别推荐用SVG制作图表、流程图和技术插图。

他举了个例子，自己在写一篇关于prompt caching的文章时，让Claude Code读取Git历史，生成了一份深度研究型HTML文件。

示例提示词：（此处原文可能有具体的提示词，但未能精准解析，此处保留原文结构）

这个场景适用于：总结某个功能的工作方式、解释一个概念、给老板写周报、给管理层写事故报告、制作SVG插图、流程图和技术示意图。

场景五：一次性编辑界面

有些需求很难单纯通过文本输入框描述清楚。针对这点，Thariq的做法是让Claude为当前具体任务构建一个一次性的编辑器。

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

这里有一个关键点：最后必须具备导出能力。例如设置一个“copy as JSON”或“copy as prompt”按钮，将用户在界面中的操作结果，重新转回可粘贴进Claude Code的文本。

示例提示词：（此处原文可能有具体的提示词，但未能精准解析，此处保留原文结构）

这个场景的应用范围很广，包括：重排、分桶、筛选tickets、测试用例或反馈；编辑结构化配置（如feature flags、env vars、JSON/YAML）；调整prompts、模板或文案并实时预览；筛选数据集、批准/拒绝行、打标签并导出；标注文档、转录稿或diff，并导出标注；选择颜色、缓动曲线、裁剪区域、cron、正则表达式这类难以用纯文本表达的值。

常见问题

HTML会不会更浪费token？

Markdown通常确实更省token。但Thariq认为，HTML的表达能力更强，而且自己也更愿意阅读，所以整体效果更好。在更大的上下文窗口下，这点额外的token消耗，已经不再是主要矛盾了。

现在什么时候还用Markdown？

Thariq坦言，自己几乎已经不用Markdown来应对大多数事情了。当然，这可能也是一种比较极端的“HTML最大化”立场。

怎么查看HTML文件？

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

生成HTML会不会更慢？

确实会慢一些。相比之下，HTML的生成速度可能比Markdown慢2到4倍。但Thariq认为，最终的效果值得这部分时间成本。

版本控制怎么办？

这是HTML的主要缺点之一：HTML的diff看起来非常“吵”，比Markdown难审查得多。

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

可以使用frontend design plugin来帮助Claude生成更优质的HTML。想要贴合公司风格，可以尝试让Claude读取代码库，先生成一份设计系统的HTML文件，并将其作为后续所有HTML文件的美学参考。

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

Thariq最后总结说，自己坚持使用HTML的真正原因，在于它让自己更能真正地参与到Claude的工作过程中。

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

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

真正值得借鉴的，并不是“以后所有文档都改用HTML”这种简单粗暴的思路，而是背后这个洞察——

（本文内容基于原作者的分享进行整理，所有核心观点、数据、案例及图片均保持原样。相关参考链接已置于原文。）

来源：互联网