Claude Code 团队几乎弃用 Markdown 了，改用 HTML 输出

今天早上刷到 Anthropic 官博一篇文章，标题起得挺挑衅，叫「HTML 那不讲道理的有效性」（The unreasonable effectiveness of HTML）。作者是 Claude Code 团队的一个技术成员，Thariq Shihipar。

我端着咖啡点进去，看到他自己写的一句话，愣了一下。

他说，他现在几乎已经把 Markdown 从日常工作流里彻底删掉了。

好家伙。

你得知道 Markdown 是个什么地位。这两年凡是跟 AI 打过交道的人，手里的产物八成都是 .md 文件。让 Claude 写个方案，吐 Markdown。让它做个总结，吐 Markdown。Cursor、Codex、Claude Code，几乎所有 agent 默认跟你交付的就是这一坨带 # 号带星号的纯文本。它简单、能跨平台、随便哪个编辑器都能打开，还带一点点排版能力。Claude 甚至练出了一手用 ASCII 字符在 Markdown 里画框图的绝活，丑是丑了点，但它真画。

Markdown 差不多就是 AI 跟人类对话的普通话。

然后现在，做 Claude Code 的人里头，有人公开说这门普通话他不想讲了。这事儿值得唠唠。原文我放这儿，感兴趣的可以自己读一遍，不长，链接放在这，https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html

坦率讲，我第一反应不是认同，是有点想抬杠。Markdown 怎么了？轻量、干净、git diff 友好、谁都能改，这不挺好的吗。

但他给的理由，我越想越觉得有点东西。

Thariq 说，随着 agent 越来越能干，Markdown 反而变成了一个越来越憋屈的格式。他列了几条很具体的难受。

第一条我直接共鸣了。他说超过一百行的 Markdown 文件，他基本读不下去。

我跟你说，这事儿太真实了。AI 现在动不动给你写一份两百行的实现方案，结构是有的，一二三四五列得明明白白，但你真的会逐行读完吗？反正我经常是扫一眼大标题，看到「方案 A / 方案 B」，再瞄两眼结论，就划过去了。一大坨灰扑扑的纯文本，没有重点的视觉落差，眼睛根本抓不住。更别提你想把这玩意儿甩给同事看，人家更不会读。

第二条，他想要更丰富的东西。配色、图表、真正的可视化。Markdown 给不了，最多让模型拿 ASCII 凑合，或者干脆用 emoji 和 unicode 方块去「估算」颜色。Thariq 说这是他最爱举的反面例子，模型在那儿用一堆彩色小方块努力表示一个渐变，看着又心酸又好笑。

第三条，分享太费劲。Markdown 这东西，浏览器原生不太会渲染，你发给别人，对方打开是一堆 # 号。结果你只能把它当附件塞进邮件，或者复制粘贴到某个支持渲染的地方。麻烦。

这三条都还算常规吐槽。真正让我坐直了的是他后面那个判断。

他说，他现在越来越不亲手编辑这些文件了。

这句话信息量很大。Markdown 当年凭什么打败 Word、打败富文本？很大一部分就是因为它好改啊，纯文本，你随手就能敲两笔。可是 Thariq 的工作方式已经变了，他把这些文件当成给 AI 看的规格说明（spec）和参考资料，自己基本不动手，要改也是回去 prompt 一句让 Claude 改。

你品品。一旦你不再自己用手编辑，Markdown「人手友好」的最大长板，就当场失效了。

这才是关键。不是 Markdown 变差了，是你跟文件的关系变了。从前文件是你写给自己看、自己改的草稿。现在文件是 AI 写给你审、你再让 AI 去改的交付物。读者和作者的角色全换了一遍，那承载它的格式凭什么不换。

我盯着这句话看了挺久。这其实戳到了 AI 协作里一个很底层的变化，只是大多数人还没把它说出来。

好，那换成 HTML 之后，到底好在哪。Thariq 在文里掰开讲了几条，我挑几个我自己觉得最有感觉的说。

先说信息密度。HTML 能装的东西比 Markdown 多太多了。表格用真表格，设计稿用 CSS，插图用 SVG，代码用 script 标签，要交互直接上 JavaScript 加 CSS，要画工作流用 SVG，要表达空间位置用绝对定位和 canvas。Thariq 有句话说得挺狠，他说几乎没有哪种 Claude 能读进去的信息，是你没法用 HTML 高效表达出来的。

这话我信。HTML 本来就是一门为「展示信息」而生的语言，浏览器替你把渲染那一关全包了。模型把信息编码进 HTML，你打开就是一个排好版、有重点、能点能划的页面，而不是一坨等你脑补排版的纯文本。

然后是阅读这件事。前面说了，他读不下去一百行的 Markdown。但 HTML 不一样，Claude 可以把结构在视觉上组织好，加标签页、加插图、加锚点链接导航，甚至给你做成移动端响应式，你在手机上和在电脑上看是两种排版。一份能让人真的读完的文档，和一份理论上信息齐全但没人读的文档，价值差着十万八千里。

Thariq 有句话挺扎心，他说如果你的方案、报告或者 PR 说明是 HTML 格式的，别人真去读它的概率会高得多。

我看到这儿没绷住。这说的不就是我们每天的工作日常吗。你熬夜写的设计文档，组里有几个人点开过？很多时候不是内容不行，是那个灰扑扑的纯文本劝退了所有人。

接下来这个就有点意思了，双向交互。

HTML 不只是给你看的，它还能让你跟它玩。Thariq 举的例子是，你可以让 Claude 在生成的页面里加滑块、加旋钮，你拖一拖就能调整一个设计，或者改算法里的参数，实时看效果。调好了之后，再让它给你个按钮，一键把当前这套参数复制成一段 prompt，你粘回 Claude Code 接着干。他还专门挂了条演示推文，https://x.com/trq212/status/2017024445244924382

这一下我感觉某个卡了很久的环节，突然顺了。以前你跟 AI 沟通一个「我想要这种感觉但说不清」的东西，比如某个动画的缓动曲线、某个颜色、某个布局密度，你得用嘴硬描述，描述得磕磕巴巴，它做得也南辕北辙。现在好了，让它先给你搭个临时的小工具，你在界面上手动调到满意，再把结果导出来。

人和 AI 之间那段最难传递的「手感」，被一个可交互的 HTML 页面接住了。有点子牛逼。

再说一个特别 Claude Code 的点，数据摄取。

为啥是 Claude Code 而不是网页版那种聊天框去干这事？因为 Claude Code 蹲在你电脑里，能读到的上下文多太多了。Thariq 说他写这篇文章里那些配图，就是让 Claude Code 把他整个代码文件夹翻了一遍，找出他过去生成的所有 HTML 文件，分组归类，然后做了一个 HTML 页面用图示把每一类都画出来。文章里那些图，是这么直接长出来的。

除了文件系统，它还能顺着你接的各种 MCP（一种让 AI 连上外部工具和数据的协议，比如连 Slack、连项目管理工具）、你的浏览器、你的 git 历史去捞上下文。料越足，它给你产出的东西就越贴你的真实情况。

讲完为什么，得讲怎么用，不然全是空中楼阁。

Thariq 在文里给了一串具体用例，还配了一个能直接抄的模板库，我先把链接放这儿，比看我复述强。

模板和用例库在这，https://thariqs.github.io/html-effectiveness/

配套的 GitHub 仓库在这，https://github.com/anthropics/html-effectiveness

我按我自己感受到的「越来越上头」的顺序，给你过几个。

最基础的一档，是拿 HTML 做方案探索。以前你让 AI 出个方案，它给你一份 Markdown plan，从头排到尾。Thariq 现在不这么干了，他会让 Claude Code 织一张 HTML 文件的网。比如先让它头脑风暴几个不同方向，每个方向单独探索；再挑一个展开，做几个界面草图；最后满意了再让它写实现计划。等都顺了，开个新会话，把这一摞 HTML 全塞进去让它照着实现。他给的示例 prompt 大概是这味儿，「我拿不准 onboarding 页该往哪做，给我生成 6 个差异明显的方案，布局、调性、密度都拉开，排成网格放进一个 HTML 文件让我并排比，每个标注它在做什么取舍」。

你看，从「一份从上往下读的清单」变成「一张能并排对比的网」，思考的形状都不一样了。

往上一档，是代码审查。代码塞在 Markdown 里是真的难看，但 HTML 能渲染 diff、能加行内批注、能画流程图、能给发现项按严重程度配色。Thariq 的例子是让 Claude 帮他审一个 PR，他说他对里头的 streaming 和背压逻辑不熟，就让 AI 重点讲那块，把真实 diff 渲染出来，在边上做批注。这比你对着一屏黑白 diff 自己硬啃强多了。要给 PR 写说明、要给别人讲清楚你这段代码在干嘛，也是同一招。

再往上，是设计和原型。这里有个我之前没意识到的点，Claude Design 本身就是建在 HTML 上的，因为哪怕你最后要落地的是 React 或者 Swift，HTML 在表达设计这件事上也极其能打。Claude 可以先用 HTML 把设计勾出来，你看顺了，再让它翻译成你要的语言。动画、交互这些最难用文字描述的，全可以先在 HTML 里原型出来手动调。

然后是报告、研究和学习这一档，我觉得对很多非纯开发的朋友也有用。Claude Code 特别擅长跨好几个来源把信息揉到一起，给你产出一份能读的报告。你可以让它搜你的代码库、git 历史、甚至联网，攒成一份长 HTML 文档、一个交互式讲解页，或者一套幻灯片。Thariq 的示例 prompt 我特别喜欢，「我搞不懂我们的限流器到底咋工作的，你读相关代码，给我产出一个 HTML 讲解页，画一张令牌桶流程图，挑 3 到 4 段关键代码加批注，底部留一个『坑』的小节，给只读一次的人优化」。

给只读一次的人优化。这话太懂打工人了。

压轴的这一档，我看完是真的「卧槽还能这么玩」。

定制编辑界面。

Thariq 说，有时候你想要的东西，纯靠在对话框里打字根本说不清。这种时候他会让 Claude 给他造一个用完即弃的编辑器。注意，不是一个产品，也不是什么可复用的工具，就是一个单独的 HTML 文件，为眼前这一份数据量身定做，用完就扔。

诀窍永远在结尾，给这个临时工具加一个导出按钮，「复制为 JSON」或者「复制为 prompt」，把你在界面上鼓捣的一切，变回一段能粘回 Claude Code、或者能提交进文件的东西。

他举了几个例子，我念两个你感受一下。「我要给这 30 个工单重排优先级，给我做个 HTML，每个工单是张能拖的卡片，分到 Now / Next / Later / Cut 四列，你先按最佳猜测预排好，再加个『复制为 Markdown』的按钮，导出最终排序，每个分组配一行理由」。还有一个，「我在调一个 system prompt，给我做个并排编辑器，左边可编辑、变量槽高亮，右边三个样例输入实时渲染填好的模板，加个 token 计数器和复制按钮」。

我盯着这几个 prompt 看了好一会儿。这个玩法的精妙在哪？

在于它把 AI 协作里那个最别扭的环节给解了。很多决策，比如排优先级、调颜色、选缓动曲线、改正则，你心里有数，但用嘴描述给 AI 听特别费劲，来回好几轮还对不齐。现在反过来，AI 临时给你搭一个趁手的小界面，你用人类最擅长的方式，动手，直接操作，调到满意，再把结果一键还给它。

你依然在循环里，但这个循环收得紧了。

棒棒的。这思路比那句「HTML 比 Markdown 好」本身值钱多了。

文章后面有个 FAQ，有个问题我猜你也会问，这么搞不是更费 token 吗？

会的，HTML 确实比 Markdown 啰嗦，同样的信息要更多字符。但 Thariq 的回答挺实在，他说 HTML 多出来的表现力，加上他真的会去读它的那个高得多的概率，算总账是更划算的。而且在 Opus 4.7 那 100 万 token 的上下文窗口（你可以理解成模型一次能记住的内容量）面前，这点多出来的开销，在窗口里根本察觉不到。

这个回答里藏着一个我觉得很多人没反应过来的事。我们过去抠 token、追求格式精简，是因为上下文窗口又小又贵。可窗口一旦大到某个程度，省那点 token 的边际收益就趋近于零了，反而是「人到底会不会去读、读了能不能用」这件事，重新变成了瓶颈。

约束一变，最优解就变了。我们很多关于「该用什么格式」的直觉，其实是几年前小窗口时代留下的肌肉记忆。窗口都 100 万了，有些习惯也该松一松了。

想试的话，文档和上手在这儿，不用配置啥，直接 prompt 一句「做一个 HTML 文件」就行，https://code.claude.com/docs/en/overview

聊到这儿，你可能觉得这就是篇讲格式选择的文章。Markdown 还是 HTML，技术细节嘛。

但 Thariq 在最后说了句话，把整篇的立意一下拔上去了。我读到的时候，下楼买咖啡的脚都顿了一下。

他说，他用 HTML 不用 Markdown 的真正原因，跟信息密度、跟可视化、跟分享，统统没关系。真正的原因是，HTML 让他感觉自己跟 Claude 更「在同一个循环里」（in the loop）。

他说，随着 Claude 接的活儿越来越多，他发现自己读那些方案越来越不仔细了，越来越倾向于直接把活儿一甩了之。他不喜欢这种状态。他想要一种方式，能让自己继续参与到 AI 的每一个选择里，而不是当个甩手掌柜。

HTML 恰好就是那个方式。他说他现在比以往任何时候，都更「在场」。

读到这句，我前面那点想抬杠的劲儿全没了。

因为这戳到的根本不是格式问题。是我们这一代用 AI 的人，迟早都要面对的那个问题。

AI 越强，你就越容易撒手。一份它写的方案，反正它写得挺像样，你扫一眼就过了。一段它生成的代码，反正测试好像绿了，你也懒得逐行看了。一个它做的决定，反正它给的理由听着挺顺，你就点了同意。一次两次没事，时间长了，你会发现自己慢慢从一个掌舵的人，变成了一个只会点「同意」的人。你还在那个位置上，但你已经不在场了。

Thariq 想用 HTML 解决的，是这个。让产出变得好读、能交互、值得你停下来看一眼，说到底就是给自己造一个不得不在场的理由。这是一个程序员在 AI 越来越能干的时候，给自己留的一个锚。

我自己平时让 Claude 写 plan，确实经常是扫两眼大标题就放它去跑了，回头出了岔子才后悔没看仔细。说实话我也不确定换成 HTML 就一定能治好这毛病，习惯这东西很顽固。但我挺认同他那个底层的判断，跟 AI 协作，最该守住的不是效率，是「在场」。

效率这东西，AI 会越来越多地替你拿走，你拦也拦不住，其实也不必拦。但「在场」是你自己的事，是你愿不愿意停下来，多看一眼它给你的东西，多问一句它为什么这么选。这件事没人能替你做，AI 替你做了，那这艘船就真的不是你在开了。

小岛这个名字里本来就有点航海的意思。我一直觉得，用 AI 有点像一个人开船出海。风越来越顺，发动机越来越猛，船自己就能跑得飞快。最危险的时刻，恰恰不是风浪大的时候，而是风平浪静、一切自动、你觉得可以松开舵去船舱里眯一会儿的时候。

手别离舵太远。哪怕只是搭一个能让你多看一眼的 HTML 页面，也是把手重新搭回舵上的一种方式。

这大概就是为什么，一个做 Claude Code 的人，会专门写一篇文章，认认真真跟你聊一个看起来这么小的事。它一点都不小。