前言
一个颇为反直觉的趋势正在悄然浮现：当AI agent的能力持续增强时，Markdown这一传统文档格式，反而开始暴露出一些力不从心之处。
近期，开发者Thariq在X平台上发布了一篇分享，详细讲述了他使用Claude Code的亲身实践——他越来越倾向于让Claude直接生成HTML格式，而非常规的Markdown文档。这篇文章随后也被Claude官方博客收录并推荐。
这并非宣告Markdown的终结。Markdown凭借其简洁性、高可移植性以及易于编辑的特点，在撰写笔记、README文件或轻量级文档时，依然是非常理想的选择。
但随着Claude Code开始涉足更复杂的应用场景——例如撰写详细的技术规格说明书、产品方案、代码审查报告、深度研究报告，乃至交互式原型设计时，问题的性质就发生了根本性变化。
Thariq的核心判断在于：HTML的价值绝不仅仅在于输出格式更加美观，其真正的意义在于，它让人与AI agent之间的协作重新变得可见、可读、可控。
为什么是HTML
Markdown如今已成为AI与人类沟通时默认的文档格式。它轻量、通用、具备基础的富文本能力，且手动编辑非常便捷。Claude甚至早已擅长在Markdown中使用ASCII字符绘制图表。
然而问题也随之而来——随着agent能够处理的任务越来越复杂，Markdown反而逐渐演变为潜在的效率瓶颈。
一份超过百行的Markdown文件，理论上结构清晰，但现实中，很少有人能真正逐字逐句地完整阅读。更为关键的是，像规划文档、规格说明、研究报告、头脑风暴成果这类内容，本质上就需要借助颜色、图表、布局、交互以及更强的视觉组织能力来强化信息传递。
还有一个更为深刻的变化：如今在很多场景下，用户已经不再亲自动手修改Markdown，而是将其作为一份规格说明、参考资料或分析输出，再交由Claude进行后续迭代。这意味着，Markdown曾经最大的传统优势之一——"方便人工手动修改"——正在被agent工作流的演进所逐渐削弱。
信息密度：HTML能承载更丰富的信息类型
HTML所能承载的信息类型，远比Markdown丰富得多。除了标题、段落、加粗等基本文档结构，它还能表达：
- 表格数据；
- 通过CSS呈现的设计信息；
- SVG插画；
- script标签中的代码片段；
- 通过Ja vaScript与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文件。
常见的流程大体是这样：
- 先让Claude Code做头脑风暴，生成多个探索方向；
- 再挑选其中一个方向深入，加入mockup、代码片段或数据流；
- 方向明确之后，写具体的实现计划；
- 新开会话时，把这些HTML文件作为上下文传进去；
- 验证阶段，也让verifier读取这些文件，从而获得更完整的背景信息。
示例提示词：（此处原文可能有具体的提示词，但未能精准解析，此处保留原文结构）
这个场景适合用于：探索代码实现方案，或者探索多个视觉设计方向。
场景二：代码评审与理解
代码在Markdown中查看，体验其实并不好。但HTML可以渲染diff、注释、流程图、模块关系等复杂信息。
Thariq会用HTML来理解agent写出的代码、做代码审查，或者向团队里的其他人解释PR。他甚至表示，现在自己每发一个PR，都会附带一个HTML版的code explainer，而且有时候它比GitHub默认的diff视图还要好用。
示例提示词：（此处原文可能有具体的提示词，但未能精准解析，此处保留原文结构）
这个场景尤其适合：创建PR、审查PR、理解代码库中的某个特定主题。
场景三：设计与原型
Claude Design底层基于HTML，正是因为HTML在设计表达上能力极强。即便最终的目标实现语言不是HTML，Claude也可以先用HTML把设计草图做出来，再转换成React、Swift或者其他语言。
它还很适合做交互原型，比如动画、点击行为、参数调节等。可以让Claude加入滑块和旋钮，帮助精确调试各种效果。
示例提示词：（此处原文可能有具体的提示词，但未能精准解析，此处保留原文结构）
这个场景适用于：创建设计系统artifact、调整组件、可视化组件库、原型化有趣的动画效果。
场景四：报告、研究与学习
Claude Code非常擅长综合多个数据源，并把结果整理成结构清晰的可读报告。可以让它去搜索Slack、代码库、Git历史和互联网，然后为个人、团队甚至管理层生成针对性的报告。
报告形式可以很灵活，长HTML文档、交互式解释器，甚至做成slideshow/幻灯片都行。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"这种简单粗暴的思路，而是背后这个洞察——
（本文内容基于原作者的分享进行整理，所有核心观点、数据、案例及图片均保持原样。相关参考链接已置于原文。）
