为什么 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 大部分做不到：

信息类型	Markdown	HTML
文档结构	✅ headers, bold, lists	✅ + tabs, collapsible
表格数据	✅ 简单表格	✅ 复杂表格 + 排序 + 筛选
设计数据	❌	✅ CSS 样式系统
插图	❌ ASCII 画	✅ SVG 矢量图
代码片段	✅ code block	✅ + syntax highlight + 交互运行
交互控件	❌	✅ slider, knob, button
工作流图	❌ ASCII 箭头	✅ SVG 流程图
空间数据	❌	✅ absolute position, canvas
图片	❌	✅ 标签

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（几个
标签 + 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 文件，按类别分组：

类别	数量	说明
Exploration & Planning	3	并排对比不同方案，选一个再展开
Code Review	3	Annotated diff、call graph、模块框图
Design	2	Design system artifact、component contact sheet
Prototyping	2	动画调参、交互原型
Illustrations & Diagrams	2	SVG 流程图、技术插图
Decks	1	HTML 幻灯片，方向键翻页
Research & Learning	2	Collapsible explainer、tabbed code sample
Reports	2	Status update、post-mortem
Custom Editors	3	拖拽排序、表单编辑器、prompt 调优界面

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

---

六、一句话总结

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