为什么 Anthropic 工程师放弃 Markdown，改用 HTML 当 Agent 输出格式

Thariq（Claude Code 团队）写了一篇内部博客，标题直接致敬 Rich Sutton 的经典论文——"HTML 的非比寻常的有效性"。他的核心主张很简单：当 Agent 从"帮你写代码"进化到"帮你做完整项目"，Markdown 这个 100 行就没人读的格式，已经撑不住了。

一、Markdown 的黄昏：100 行就是认知天花板

Thariq 的原话很直接：

"I tend to not actually read more than a 100-line markdown file, and I certainly am not able to get anyone else in my organization to read it."

这不是个人偏好，是一个组织层面的硬约束。当 Claude Code 能做的事越来越复杂——写 spec、画架构图、做原型、审代码——Markdown 的表达能力跟不上了。

更致命的是，Markdown 的"可编辑性"优势正在消失。Thariq 说：

"When I do make edits, I'm usually prompting Claude to edit them, which removes one of markdown's largest benefits."

如果编辑本身也是通过 prompt 让 Agent 做，那 Markdown 的"人类易编辑"这个卖点就失效了。你不需要一个"人类容易改"的格式，你需要一个"Agent 能表达丰富信息、人类愿意读"的格式。

二、HTML 的六张牌：为什么它能赢

1. 信息密度：几乎无限

Markdown 能做的事 HTML 都能做，但 HTML 能做的 Markdown 大部分做不到：

Thariq 甚至举了一个细节：Claude 在 Markdown 里表示颜色时，只能用 Unicode 字符 "估算"——比如用 🟥🟩🟦 这种方块。而 HTML 里直接写 CSS background-color。

2. 视觉清晰：人类真的愿意读

HTML 可以：

• 用 tab 组织不同章节
• 用侧边栏做导航
• 用颜色区分 severity（code review 里的 critical/warning/info）
• 做 mobile responsive，手机上也好看

这些不是"锦上添花"，是"从 0 到 1"——没有它们，文档根本没人读。

3. 易分享：一个链接就行

Markdown 文件很难分享：

• 浏览器不原生渲染
• 发邮件要当附件
• 同事收到后大概率不看

HTML 上传到 S3（或任何静态托管），得到一个链接。同事打开就能看，没有任何 friction。

4. 双向交互：文档不是死的

Thariq 举了几个例子：

• 设计原型：slider 调整动画参数，实时看到效果
• 算法调参：knob 改变量，图表实时更新
• 配置编辑：改完点"copy as JSON"，粘贴回 Claude Code

这打破了"Agent 输出 → 人类阅读 → 人类反馈 → Agent 再输出"的线性循环，变成了人在文档里直接操作。

5. 数据摄取：Claude Code 的上下文优势

为什么要用 Claude Code 做 HTML，而不是 Claude.ai 或 Claude Design？

因为 Claude Code 能读你的代码库。

Thariq 写这篇文章时，让 Claude Code 读遍他的代码文件夹，找出所有生成的 HTML 文件，分类归纳，然后用 SVG 画出每种类型的示意图。这些图直接出现在了最终文章里。

此外，Claude Code 还能读：

• MCP（Slack、Linear 等）
• 浏览器（Claude in Chrome）
• Git history

这是纯聊天界面做不到的上下文深度。

6. 趣味性：让人更投入

"Making HTML documents with Claude is just more fun and makes me feel more involved and invested in the creation, and that by itself is enough."

这不是感性废话。当人类对输出更有参与感，就更愿意审阅、反馈、迭代——整个 Agent 工作流的反馈循环就加速了。

三、五个实战场景：HTML 取代 Markdown 的具体用法

场景一：Spec & Planning（探索与规划）

不用：Markdown 清单列几个方向
改用：HTML 网格并排展示 6 种不同设计，每个标注 tradeoff

Thariq 的做法是"做一网页"而不是"写一文档"——从 brainstorming 到 mockup 到 implementation plan，全是 HTML 文件。最后把这些文件打包丢给 implementation session 当上下文。

场景二：Code Review（代码审查）

不用：GitHub diff view
改用：HTML 文件，带 inline margin annotations，按 severity 颜色编码

Thariq 说："I attach a HTML code explainer to every PR I make now."

这比 GitHub 默认 diff 好在哪里？可以聚焦特定逻辑（比如"我不熟悉 streaming/backpressure，重点讲这块"），可以加流程图，可以标注 risk level。

场景三：Design & Prototypes（设计与原型）

Claude Design 本身就是基于 HTML 的。先用 HTML 画设计系统（tokens → swatches，components → contact sheets），然后让 Claude 翻译成 React/Swift/任何目标平台。

Thariq 的案例：做一个 checkout 按钮的动画原型，带 slider 调参数，调好了一键 copy 参数值。

场景四：Reports & Research（报告与研究）

Claude Code 可以跨多个数据源（Slack、代码库、git history、互联网）合成信息，输出 HTML 报告。

格式可以是：

• 长文档 + collapsible sections
• 交互式 explainer
• 幻灯片/deck（几个 <section> 标签 + 20 行 JS）

场景五：Custom Editing Interfaces（自定义编辑界面）

这是最有想象力的场景。当"用文字描述"太痛苦时，让 Agent 做一个一次性 HTML 编辑器：

• 优先级排序：30 张 Linear ticket 做成可拖拽卡片，分 Now/Next/Later/Cut 四列，排好点"copy as markdown"
• Feature flag 编辑：表单式编辑器，显示依赖关系，prerequisite 没开就 warning
• Prompt 调优：左侧可编辑 prompt，右侧三个 sample input 实时渲染，带 token counter

核心模式：Agent 做 UI → 人类在 UI 里操作 → 点 export 把结果贴回 Agent。人一直在 loop 里，但 loop 更紧了。

四、FAQ：五个常被问到的问题

Q1: Token 效率不是更低吗？

Markdown 确实用更少 token。但 Thariq 的回应很直接：

"With the 1MM context window in Opus 4.7, the increased token usage is not really noticeable."

上下文窗口已经到 100 万 token 了，HTML 多花的 token 在宏观上可忽略。而且更重要的是：表达力提升带来的"人类实际阅读"的收益，远大于 token 成本的损失。

Q2: 那什么时候还用 Markdown？

Thariq："I have honestly stopped using markdown altogether for almost everything."

他自称 "HTML maximalist"——已经几乎完全不用 Markdown 了。

Q3: 生成时间不是更长吗？

是的，2-4x。但 Thariq 认为结果值得。

这里有一个隐含的逻辑：如果 Agent 的输出人类不读，那生成再快也是 0 价值。HTML 虽然慢，但被阅读的概率高得多。

Q4: 版本控制怎么办？

Thariq 坦承：

"This is honestly one of the biggest downsides of HTML, HTML diffs are noisy and hard to review compared to Markdown."

这是 HTML 方案的最大软肋。没有好的解决方案，只能接受。

Q5: 怎么让 Claude 的设计品味不丑？

两个方法：

1. 用 Anthropic 的 frontend design plugin
2. 自己创建一个 design system HTML 文件（让 Claude 读你的代码库提取风格），以后所有 HTML 文件都引用它

五、20 个示例：从探索到自定义编辑器

Thariq 做了一个展示页面（https://thariqs.github.io/html-effectiveness ），放了 20 个自包含的 .html 文件，按类别分组：

每个文件都是"你会略过的文档"变成"你真的会读的东西"的实例。

六、一句话总结

Thariq 的这篇文章不是技术方案，是一个范式声明：当 Agent 的输出从"人类会编辑的文本"变成"人类会阅读的信息载体"，格式选择的逻辑就彻底变了。Markdown 的简洁性在 100 行以内是优势，超过 100 行就是瓶颈。HTML 的"重"不是负担，是承载复杂信息的必要成本。

而最核心的洞察在最后一句：

"I feel much more in the loop with Claude... instead of leaving Claude to make its choices."

HTML 没有让 Agent 更自主，反而让人类更在场了。

参考信息

• 原文：https://www.anthropic.com/engineering/claude-code-html
• 示例页面：https://thariqs.github.io/html-effectiveness（20 个 HTML 文件）
• 作者：Thariq（Claude Code 团队，Anthropic）
• 灵感来源：Rich Sutton《The Bitter Lesson》→ 本文标题致敬 "The Unreasonable Effectiveness of HTML"
• 上下文窗口：Claude Opus 4.7 支持 1M token
• 关键数据：HTML 生成时间 2-4x 于 Markdown、100 行 Markdown 认知天花板、20 个实战示例
• 核心主张：Markdown 适合短文本编辑，HTML 适合复杂信息表达与双向交互

读完这篇文章，我意识到一个反直觉的事实：Agent 时代，人类和机器的沟通格式不是在"简化"，而是在"复杂化"。Markdown 是 Web 1.0 时代的产物——它假设人类会读、会编辑、会维护。但 Agent 时代的真相是：人类读不动 100 行以上的纯文本，编辑也交给了 Agent。所以格式需要承载的不是"可编辑性"，而是"信息密度"和"可交互性"。HTML 赢了，不是因为它更简单，恰恰是因为它更复杂——复杂到足以承载 Agent 想表达的一切。

#AI开发 #ClaudeCode #HTML #Markdown #Agent输出格式 #Anthropic #Thariq