Back to Blog

Claude Code 团队为什么抛弃 Markdown 改用 HTML？5 个理由说服了我

2026-05-10T10:40:00+08:00
Claude Code HTML Markdown Anthropic Agent

Claude Code 团队为什么抛弃 Markdown 改用 HTML？5 个理由说服了我

Anthropic Claude Code 的工程负责人 Thariq Shihipar 发了一篇长文，标题就叫"HTML 的不合理有效性"。16 小时内 440 万阅读、8200 赞、15700 收藏，Hacker News 上吵翻了。

核心观点就一句：Markdown 已经追不上 Agent 的能力了，HTML 才是 AI 输出的正确格式。

这不是一个程序员在发牢骚。Shihipar 是 Anthropic Claude Code 的工程负责人，他说的"改用 HTML"是 Anthropic 内部已经在做的事——计划文档、代码审查、设计系统、技术报告，全部从 Markdown 切到了 HTML。

我花了一个下午消化这篇文章和他的 20 个示例，说说我的理解。

本文提纲

  1. Markdown 赢了格式战争，但输了 Agent 时代
  2. 理由一：信息密度——一个 HTML 文件顶十个 Markdown
  3. 理由二：超过 100 行的 Markdown 没人读
  4. 理由三：分享——HTML 打开就能看，Markdown 要装东西
  5. 理由四：双向交互——不只是输出，还是输入
  6. 理由五：可读性是工程问题，不是审美问题
  7. 20 个真实案例速览
  8. 社区的三个质疑
  9. 三个 prompt 马上就能试

Markdown 赢了格式战争，但输了 Agent 时代

Markdown 简单、便携、哪里都能写。所有人都爱它，包括 Shihipar 自己。他不否认 Markdown 的价值，他的论点是：Agent 的发展速度超过了格式的承载能力。

Claude 从 Opus 4.7 开始有了 100 万 token 的上下文窗口。一个 Agent 可以读完整代码库、跨 10 个文件做修改、生成几百行的实现计划。这种复杂度的输出，Markdown 扛不住了。

用 Shihipar 的话说：当 Claude 被迫"在 Markdown 里表示颜色"时，它用 Unicode 字符去近似——这个方案很创新，但也恰恰说明格式的极限。

理由一：信息密度——一个 HTML 文件顶十个 Markdown

Markdown 能做段落、列表、链接、代码块、简单表格。到此为止。

HTML 在一个自包含文件里可以做：复杂表格（sticky header）、SVG 矢量图、可执行代码片段、JavaScript 交互、绝对定位布局、canvas 绘图、base64 内联图片、作用域样式表。

这不是炫技。当开发者要审核一个复杂功能的实现计划，需要同时看两套 UI 方案并排对比，或者快速理解一个 PR 改了哪些数据流——每一个额外的视觉元素都在缩短决策时间。按分钟算，乘以每周的任务量，差距是实实在在的。

理由二：超过 100 行的 Markdown 没人读

Shihipar 直说了：包括他自己，没人真的去读一个超过 100 行的 Markdown 文件。

但 Claude 的输出经常是好几百行的实现计划和技术规格。Markdown 里就是一面文字墙。

HTML 文档在这个长度下能活下来，因为可以做：

  • 标签页：8 个 section 用 tab 切换，不用滚
  • 侧边目录：快速跳转
  • 可折叠区域：细节默认收起，需要时展开
  • 响应式布局：桌面横排，手机自动竖排

同样的信息量，读起来完全是两个体验。

理由三：分享——HTML 打开就能看，Markdown 要装东西

团队协作的实际情况：浏览器不渲染 Markdown。发个 .md 文件给别人，对方要么装编辑器，要么手动转格式，要么当附件下载。

HTML 呢？上传到 S3 或公司 CDN，一个链接发出去，任何设备点开就能看。不需要安装任何东西。

Shihipar 观察到一个反直觉的现象：当文档是 HTML 格式时，别人真正读它的概率非线性上升。不是内容更好，是门槛更低。

对于分布式团队来说，这个论点很难反驳。

理由四：双向交互——不只是输出，还是输入

这是最有意思的一个点。

HTML 不只是输出格式，它还是输入格式。加几行 JavaScript，Claude Code 可以生成一个包含滑块的文档——拖动滑块调参数，点按钮把当前状态转成 prompt，粘贴到下一个 Claude 会话里。

这意味着开发者不再只是收到一个静态产物去批准或拒绝，而是拿到了一个小型定制工具来探索决策空间。

三个实际场景：

  1. 动画参数调优：HTML 里放滑块调 duration 和 easing，实时预览效果
  2. 设计 token 探索：颜色、间距、字体的可视化选择器
  3. Prompt 调试器：在 UI 里调参数，一键导出为新的 prompt

这个模式把"读文档"变成了"用工具"。

理由五：可读性是工程问题，不是审美问题

Shihipar 最后一个论点很实际：精心排版的 HTML 文档和 monospace 字体的 Markdown 文本，在阅读体验上是两个物种。

这不是为了好看，是为了减少理解成本。一个复杂的 PR review，用 HTML 做成带颜色标注、侧边注释、严重性标签的页面，比看 GitHub 的 diff 视图快得多。Shihipar 说他现在每个 PR 都会附一个 HTML 说明文件。

20 个真实案例速览

Shihipar 在 thariqs.github.io/html-effectiveness 放了 20 个自包含 HTML 文件，全部由 Claude Code 生成。按 9 个类别分布：

类别 数量 典型场景
探索与规划 3 三种方案并排对比、UI 方案矩阵、带时间线的实现计划
代码审查 3 带注释的 diff、PR 说明、模块依赖图
设计 2 可点击的设计 token、组件状态展示
原型 2 动画参数调优、可点击的多屏流程
图表与插图 2 SVG 矢量图、可点击的部署流程图
演示文稿 1 键盘导航的 slide deck，替代 PPT
研究与学习 2 带折叠区域的 explainer、带术语表的教程
报告 2 带图表的周报、带时间线的 post-mortem
自定义编辑器 3 拖拽看板、Feature Flag 编辑器、Prompt 调试器

每个案例的思路都一样：一次性工具，解决一个具体问题，用完即弃。Claude Code 不是在做一个产品，是在做一个小工具帮你完成手头的任务。

社区的三个质疑

Hacker News 上这篇帖子拿了超过 1000 分，质疑也很集中：

质疑一：HTML 让人很难共同编辑

tmhrtly 的评论说得很直接："如果是一份复杂东西的规格文档，我希望能直接进去编辑。HTML 文档比 Markdown 难编辑得多。"

这个点很公平。Markdown 随便一个文本编辑器就能改，HTML 要么需要前端技能，要么得再跑一次 Claude Code 来改。

质疑二：HTML 更费 token，谁受益？

ryandsilva 指出 HTML 的 token 消耗比 Markdown 高 2-4 倍，这可能有利于 Anthropic 的生态。Shihipar 反驳说 Opus 4.7 有 100 万 token 窗口，多出来的成本感觉不到。但按 token 付费的用户，这是真金白银的额外支出。

质疑三：你自己这篇文章就很长

planktonne 的讽刺很有趣：论证"超过 100 行 Markdown 没人读"的文章，本身就是一篇超长的 HTML 文档。真正的问题不是格式，是内容太膨胀。

这三个质疑都有道理。Shihipar 自己也给了实用的取舍规则：HTML 给别人看的东西，Markdown 给自己反复编辑的东西。

三个 prompt 马上就能试

不需要装任何 skill，直接在 Claude Code 里用：

场景一：生成多个 UI 方案对比

I haven't decided on the cut for the onboarding screen yet.
Generate 6 markedly different approaches, vary layout, tone
and information density. Show them in a single HTML file
in a grid, so I can compare them side by side.
Label each one with the trade-off it is making.

场景二：PR Review 可视化

Help me review this PR by creating an HTML artifact
that describes it. I am not familiar with the streaming
and backpressure logic: focus the analysis there. Render
the actual diff with inline margin annotations,
color-code findings by severity and add
whatever you need to convey the concept clearly.

场景三：代码理解 explainer

I do not really understand how our rate limiter works.
Read the relevant code and produce an HTML explainer
page: a token-bucket flow diagram, the 3-4 key code
snippets annotated, and a "gotchas" section
at the bottom. Optimize it for a one-time read.

试一次就知道了。开个浏览器看生成的 HTML，对比一下同样的内容如果输出成 Markdown 是什么体验，高下立判。

原文：HTML vs Markdown in Claude Code | 20 个 HTML 示例

作者: itech001
来源: 公众号：AI人工智能时代
主页: https://www.theaiera.cn（每日分享最前沿的AI新闻和技术）

本文首发于 AI人工智能时代，转载请注明出处。

Enjoyed this article? Share it with others!