一、Markdown 的瓶颈

Markdown 曾是 AI Agent 和人类沟通的默认格式。简单、可移植、有一点富文本能力，还能用 ASCII 画图。Claude 甚至在 Markdown 里做 ASCII 图表，水准不低。

但随着 Agent 越来越强，Thariq 觉得 Markdown 成了限制。他说了一句话很诚实：超过 100 行的 Markdown 文件，我根本不会认真读。

问题是，Claude Code 生成的规划、方案、分析越来越长——100 行是底线，500 行不稀奇。如果输出格式决定了用户会不会看，那格式本身就是瓶颈。

还有一个微妙的变化：他不再自己编辑这些文件了。文件是拿来读的、做参考的、给 AI 改的。Markdown 最大的卖点——"人类容易编辑"——对他已经不存在了。

他做了个彻底的转变：开始用 HTML 替代 Markdown。

· · ·

二、为什么是 HTML

这不是追求好看。Thariq 列出了几个硬核理由。

信息密度

HTML 能承载的信息类型远超 Markdown：

他的判断很强硬：没有哪类信息是 Claude 能读但不能用 HTML 高效表达的。 相比起来，Markdown 想展示颜色，只能用 Unicode 字符凑合——Claude Code 里有一张截图，Agent 试图用彩色字符来"画"颜色，看得很心酸。

视觉清晰度

Agent 越做越复杂，输出的规格文档也越来越厚。但 100 行的 Markdown，Thariq 承认他自己都不读——更别提让团队其他人读了。

HTML 不同。Claude 可以用视觉结构来组织信息：标签页、插图、链接、响应式布局。手机上看一个版式，电脑上看另一个。读起来轻松得多。

易于分享

Markdown 文件最难的一步不是写，是让别人看。大多数浏览器对 Markdown 渲染不佳，你只能当附件发邮件。

HTML 往 S3 上一丢，一个链接甩过去。同事在哪儿都能打开。

核心观点

一份规格文档、报告或 PR 总结——用 HTML 格式，被真正读完的概率大幅提升。

双向交互

HTML 文档可以不是静态的。加几个滑块、旋钮，调一个设计参数，看看效果。加一个"复制到剪贴板"按钮，把改好的东西直接粘回 Claude Code 的对话框。

这不是网页应用，这是一次性的、专门为这组数据定制的交互界面。用完就丢，但用的时候体验极好。

数据摄取

为什么用 Claude Code 生成 HTML 而不是 Claude.ai 或 Claude Design？因为 Claude Code 能摄入的上下文远超想象。

Thariq 举了个例子：写这篇推广文章时，他让 Claude Code 扫描整个代码文件夹，找到所有他生成过的 HTML 文件，分组归类，然后生成一个 HTML 文件——里面用图表展示了每一类文件的可视化摘要。

除了文件系统，Claude Code 还能通过 MCP 读 Slack、Linear，通过浏览器插件读网页，通过 git 历史读变更。这些数据合在一起，生成的 HTML 报告含金量不是粘贴几个链接能比的。

· · ·

三、实用场景

Thariq 在 Claude Code 团队工作，他的实践覆盖了几个典型场景。

规格与规划

以前用 Markdown 写规划，现在他用 HTML 做一整套探索型文件。流程是这样的：

  1. 让 Claude Code 头脑风暴，生成不同方案的探索性 HTML
  2. 选一个方向展开——加交互原型、代码片段
  3. 最终生成实施计划 HTML
  4. 新 session 里把这些文件全部传给 Claude Code，照着实现

他说：验证环节也要把 HTML 文件读进去——Agent 有了完整的视觉上下文，理解远超纯文本。

代码审查

代码在 Markdown 文件里很难读。HTML 可以渲染 diff 对比、注解、流程图、模块结构。他把 HTML 版的代码解读附在每一个 PR 里——比 GitHub 默认对比视图还好用。

"帮我审查这个 PR，生成一个 HTML 文件来解释它。我对 streaming/backpressure 逻辑不熟，重点解释那部分。把实际 diff 渲染出来，边距加注解，按严重程度标颜色。"

设计与原型

Claude Design 之所以基于 HTML，是因为 HTML 的设计表达能力实在太强。可以在 HTML 里画完设计稿，再转写成 React、Swift 等目标语言。而且可以加滑块调参数、试动画，找到感觉再定稿。

报告与研究

Claude Code 最擅长跨数据源做信息综合。读 Slack、读代码库、读 git 历史、读网页，然后生成一份可读性爆表的 HTML 报告。

Thariq 自己做 prompt caching 研究时，就让 Claude Code 读了全部 git 历史，出了一份带 SVG 图表的深度研究报告。

一次性的编辑界面

有时候你想做一件事，但用文本描述太麻烦了。那就让 Claude 给你做一个一次性的 HTML 编辑工具——只针对这一份数据、专门解决这一个问题。

关键诀窍：最后一定要加一个"导出"按钮——"复制为 JSON"或"复制为 prompt"，把你在界面上调整的结果变回文本，粘回 Claude Code。

· · ·

四、常见问题

❓
会不会更耗 token？
Markdown 确实更省 token。但 Thariq 认为：HTML 的表达力换来的是你真正会读——这点收益远大于 token 的开销。Opus 4.7 的 100 万上下文窗口让这个问题几乎不成问题。
❓
什么时候还用 Markdown？
"我几乎完全停用 Markdown 了。" 他自认是 HTML 最大化主义者。
❓
生成速度是不是更慢？
对，HTML 比 Markdown 慢 2-4 倍。但他觉得值得。
❓
版本控制怎么办？
这是 HTML 最大的短板。HTML diff 比 Markdown diff 吵闹得多，不好审查。
❓
怎么让 HTML 好看、不丑？
可以给 Claude 一个设计系统 HTML 文件做参考。让 Claude 读你的代码库，自动提取设计规范，后续生成的 HTML 都统一风格。
· · ·

五、写在最后

Thariq 说了一句值得反复琢磨的话：

他的感受

用 Markdown 的时候，我开始害怕自己不再深入阅读 Agent 的规划——只能放手让 Claude 自己做决定。但用 HTML 之后，我第一次感觉真正「在状态」了。

不是工具炫技。是 HTML 让他更愿意读、更容易理解、更愿意参与。这一点，比任何格式争论都重要。