最近 Anthropic 工程师 Thariq 的一篇文章《Using Claude Code: The Unreasonable Effectiveness of HTML》传得很广。他在使用 Claude Code 的过程中，用 HTML 替换 Markdown 来呈现信息，认为这样能得到更好的可读性。这篇文章拆解他的论点，也说说我自己的想法。
原文的论点
他认为 HTML 比 Markdown 效果更好，主要基于几个判断：
- Markdown 超过 100 行之后，人类实际阅读的概率骤降。
- HTML 的信息密度是 Markdown 的三到五倍。Markdown 是线性的信息，HTML 可以承担可视化程度更高的内容。
- 生成 HTML 的 token 数量更高，生成速度比 Markdown 慢两到四倍，但可读性的回报更高。
- 现在大模型的上下文窗口已经很大，Opus 4 有 100 万上下文，token 变多之后，上下文不再是 Agent 在两种格式之间取舍时的限制。
他使用 HTML 的真正原因，是在 Agent 的工作循环里，HTML 能让人比阅读 Markdown 文档更深入地参与进来，更好地跟 Agent 交互。
HTML 的六个优势
原文提到的优势可以分成六条：信息密度、视觉清晰度、易于分享、双向交互、数据摄取和更有乐趣。
信息密度和视觉清晰度是相近的两点。HTML 是做网页的，任何形式的信息都可以用它呈现，比如表格、SVG、Canvas 和可点击的 JS 交互，还能在水平空间上排布内容。Markdown 在终端里虽然能被大多数 AI Agent 原生渲染，但遇到复杂的 UI 交互，只能画 ASCII 图，也没办法表达颜色，信息大多是垂直线性的，一行一行的列表密度很低。Markdown 也可以装渲染器改善效果，但始终不如 HTML 灵活。
易于分享这一点我不太苟同。他认为浏览器没办法原生渲染 Markdown，HTML 上传之后更容易分发。但 Markdown 有一个很大的好处：原始内容是可读的。就算不渲染，我们看到里面的井号和横杠也能看懂结构。HTML 在没有渲染的环境里，比如在微信里点开，完全看不了原始信息。
双向交互是 HTML 确实独有的能力。HTML 里面可以写 JS，承担复制上下文的功能。图中是我之前做的一个生成落地页的 skill，中间页面用 HTML 呈现：选择一个样式之后，点击右下角的「告诉 Agent」，本质上就是复制一段提示词，粘贴回 Agent 就能看到，内容就是主题的名字。
也就是说，我们可以让 Agent 生成一个带选项或表单的 HTML，填写之后点一下复制，再把提示词粘回 Agent。Markdown 做不到这一点。
数据摄取指的是 Claude Code 可以直接读取文件系统、MCP、浏览器的信息，再生成一份综合报告。现在很多通用 Agent 都喜欢用 HTML 呈现报告，因为可以做得丰富好看。但这一点跟格式是 Markdown 还是 HTML 没有本质关系，仍然是信息呈现的问题。
更有乐趣、能让人投入创作循环这一点我是认可的。和 Agent 交互做出一个产物的时候，HTML 作为中间介质，呈现的信息更直观易读。但 Anthropic 的工程师不缺 token，有最好的算力，不用担心用量。对大多数普通人来说，HTML 的 token 开销是 Markdown 的两到四倍，大多数时候用 Markdown 已经能比较直观地看懂信息，我认为不划算，除非内容跟样式相关，必须看颜色、看交互，这时候 HTML 是不得不做的。
五个适合 HTML 的场景
原文还列了一些 Markdown 完全做不到、或者人读起来很困难的场景。
- 规格和规划：PRD 文档可以做得非常丰富，新人上手的 onboarding 页面可以做成多种方案并排放在网格里，标注每个的取舍，让人直观比较。
- 代码审查：Markdown 的代码 diff 不够丰富，除非装渲染器。HTML 除了用颜色区分变更，还可以按严重程度调整颜色深浅，让 Agent 自己决定哪些部分需要认真阅读，还可以在上面写评论。
- 设计和原型：交互动画、参数滑块、实时预览，Markdown 完全无法表达。
- 报告和研究：深度研究里的饼图、环状图、柱状图，Markdown 完全无法表示。流程图也是，Mermaid 画出来的效果不如 HTML 里更复杂的可视化。
- 自定义编辑器：临时做一个表单呈现交互，用完就不再需要，Markdown 同样做不到。
另外，在 Agent 对话里做选择，大多数时候我们用 Agent 内置的 ABCD 选项，或者手动回答 1234。如果有 HTML 的交互，体验肯定会更好。
常见问题和我的补充
原作者对常见问题有自己的回答。
- Token 开销更高？他认为 HTML 的表现力回报高于成本，而且 Opus 4 的 100 万上下文让 HTML 输出对上下文的侵占不再是问题。
- 什么时候还用 Markdown？他说对他来说几乎不用了。
- 怎么查看 HTML？本地浏览器直接打开，使用 AI Agent 的人电脑上不太可能没有能渲染 HTML 的工具。
- 生成更慢？确实，token 数量更大。
除了生成更慢，我认为还有一个更严重的问题：HTML 对模型的要求更高。一个很长的 HTML 是结构化的，Markdown 中间某个符号写错了，完全不影响渲染和其他文本的可读性；但一个七八百行的 HTML，后半段某个标签被写错，整个页面在浏览器里就渲染不出来了。如果模型能力没有 Claude 这么强，让它在一个很大的 HTML 里排查某个结构问题，其实很难发现。为了呈现一个中间阅读用的文件，要先写几百行代码，写错了还要再修，浪费很多上下文，这是很不友好的。
还有版本控制的问题。很多 Markdown 会跟着 Git 放进仓库，HTML 变化时的 diff 无论对 Agent 还是对人类，可读性都很差，里面全是样式、结构、JS 变更的噪声，很难评审。
另一个重点是，不是每个 Agent 写出来的 HTML 效果都一样。模型能力不同，产出差很多。比如我现在这个文档的 UI，大多数是用 Gemini 设计好以后做成 skill，再让其他 Agent 按统一的默认风格生成。想让 Codex 或 Claude 一次性写出同样样式的文档是很难的。原文的建议是让 Claude 查看代码库，写一个 design system 的 HTML 文件作为参考，这一点我自己有一个更顺手的方案，后面会讲。
Reddit 社区的争议
Reddit 社区对这篇文章也有很多争论，和我刚才的质疑接近。
第一是 token 与成本。不是每个人都像 Anthropic 的工程师那样有充足的用量、能用最好的模型。对大多数人来说，Claude Opus 这个级别的模型是要省着用的，不管什么套餐都不太够用。第二就是生成速度，成本之外，慢也是一个大问题。社区里也有人认为，原作者对一些质疑的回答并不是真正的解决方案。
我的做法：把样式和组件提前写好
我自己认为 HTML 确实是一种很好的信息呈现形式。我之前做的 CityCraft skill 会用 HTML 呈现中间交互，另一个叫 Panova 的 skill 会解析一个产品，以产品经理的视角把里面的业务讲清楚，最终产物也是 HTML。
可以看到它也是一个线性的结构，但里面能嵌入很多交互，整体比纯 Markdown 文档清爽。不过让 AI Agent 直接生成 HTML 这件事，有一些中间的解法，可以既节省成本又生成得快：用程序化的方式提前把 CSS 写好，把大多数 HTML 结构规范好，AI Agent 只需要写少量代码，就能生成一个可视化效果比 Markdown 好的 HTML 文档。
我现在这个文档就是用自己的 skill 生成的，最近已经开源，仓库在 html-doc。它的设计原理是内置一套样式，比如一个 baseCSS，AI 生成的时候不用重复写样式。
除此以外还有很多提前写好交互的组件，以及一个用来合成最终 HTML 的脚本。AI Agent 大多数时候只需要读一下里面的组件规范，把内容文件写出来，再运行脚本生成最终的 HTML。这样做出来的文档可视化效果比较好，同时 Agent 生成的代码量很少。
这篇文章的源文件总共 400 行，跟一个普通的 Markdown 长度差不多。只是 AI Agent 需要理解 skill 里预制的一些结构，比如 matrix 或者 hero 页这些组件。
这其实跟前端开发的理念相似：想让后续开发更简单，就做组件化、模块化，后面的人只要写少量代码、复用大多数内容，就能呈现比较好的效果。
另外，我觉得 AI 写文档还是需要一些人的洞察。AI 很喜欢写车轱辘话，我最开始做这个 skill 的时候只把它当成信息呈现的工具，后来还给它注入了怎么把文档写得让人更可读的约束。之前它会用不同的好看模块呈现相同的信息，前面说一遍后面说一遍，对概念的解释也过多，这是一种浪费。我认为人最可读的信息结构类似 PPT：文字少、可视化信息多、排版丰富。PPT 对一个文档来说信息密度太低，但可以把每一页 PPT 的理念串成一个完整的文档。这个 skill 生成的文档左侧还有一个大目录，可以快速跳到想看的区域。
还有一个思路是在 AI Agent 里接入飞书的 CLI。飞书文档的信息结构比传统 Markdown 更丰富，也内置了类似的组件，但写的 token 同样比较多，而且我们得切到飞书里用，不用飞书的人就得多装一个软件。浏览器是每个人都有的，如果大家想让 HTML 承担更好的信息展示，可以尝试自己写一个这样的 skill，或者直接把我这个 skill 装到自己的 AI Agent 上，按照喜欢的风格调整信息呈现的方式。这样既能少消耗 token，也能得到更好的可视化效果。