作为 云栈社区 上的开发者们，我们可能早已习惯了与 Markdown 打交道。但 Claude Code 团队的 Thariq 最近分享了一个反常识的观点：他们正在用 HTML 全面取代 Markdown 作为文档输出格式。为什么这么做？这背后其实藏着对信息密度、视觉交互和协作效率的深层思考。
开头：为什么我换掉了 Markdown
Markdown 已经成了 Agent 跟我们沟通时最主流的文件格式。它简单、便携，有一定的富文本能力，也方便人手编辑。Claude 现在甚至能在 Markdown 里用 ASCII 画出意外不错的图。
但随着 Agent 越来越强，我开始觉得 Markdown 是一种束缚。一个超过 100 行的 Markdown 文件我自己都看不下去。我想要更丰富的可视化、颜色和图表，并且能轻松分享出去。
我也越来越少自己手敲这些文件了，它们被我当作 spec、参考资料、头脑风暴产物在用。要改的时候，我也是让 Claude 来改，这反而抹掉了 Markdown 最大的优势之一。
所以我开始更倾向于用 HTML 而不是 Markdown 作为输出格式，Claude Code 团队里这么干的人也越来越多了，下面讲讲原因。
（想直接看例子的话，看这里：thariqs.github.io/html-effectiveness。但记得回来读完原因。）
为什么是 HTML：信息密度
HTML 能比 Markdown 表达远远更丰富的信息。它当然能搞定标题、格式这些基础文档结构，但还能表达：
用 table 表达表格数据，用 CSS 表达设计数据，用 SVG 画插画，用 script 标签嵌代码片段，用 HTML+JS+CSS 做交互，用 SVG 加 HTML 表达流程，用绝对定位和 canvas 表达空间数据，用 img 嵌图片。
我甚至可以说：几乎不存在一种 Claude 能读懂、却没办法用 HTML 高效表达的信息。这让 HTML 成了模型向你传达深度信息、以及你审阅这些信息的高效方式。
我发现，当模型没法这么干时，它会在 Markdown 里搞一些低效的事，比如画 ASCII 图，或者——我最喜欢的——用 Unicode 字符近似颜色，下面这张 Claude Code 截图就是这种情况。
Claude Code 试图在 Markdown 里展示颜色
为什么是 HTML：视觉清晰度与可读性
随着 Claude 能干越来越复杂的活，它写出来的 spec 和 plan 也越来越大。实际经验告诉我：超过 100 行的 Markdown 文件我基本不会真的看完，更别说让组织里其他人去读。
但 HTML 文档好读得多，Claude 能用更利于浏览的方式来组织视觉结构——加 tab、加插图、加链接等等。它甚至可以做成移动端响应式，这样不同设备上你能用不同方式去读。
为什么是 HTML：易于分享
Markdown 文件挺难分享的，因为多数浏览器都不能很好地原生渲染它。你经常得当附件塞进邮件或消息里。
HTML 不一样，只要你把文件传上去（比如 S3），就能直接发链接出去。同事可以在他们想要的任何地方打开它，引用起来也方便。
你那份 spec、报告或 PR 说明真的被人读到的概率，会因此高出非常多。
为什么是 HTML：双向交互
HTML 可以让你和文档发生交互——比如你可以让它加滑块或旋钮来调一个设计，或者让你调整算法的不同参数看效果。你还可以让它给你一个按钮，把这些改动复制成 prompt 直接粘回 Claude Code。更多关于这种双向交互的例子，看我之前的 playgrounds 那篇。
为什么是 Claude Code，而不是 Claude.ai
为什么用 Claude Code 来做 HTML，而不是 Claude.ai 或者 Claude Design？最大的原因之一是 Claude Code 能吸收的上下文。
比如写这篇文章时，我让 Claude Code 把我代码目录里所有我历史生成的 HTML 文件读一遍、分组归类，然后做一个 HTML 文件，里面用图示代表每一类。你在这篇文章里看到的那些插图就是这么来的。
除了文件系统，Claude Code 还能通过你的 MCP（Slack、Linear 等）、浏览器（Claude in Chrome）、git 历史等等抓到额外的上下文。
它本身就让人愉快
用 Claude 做 HTML 文档就是更有意思，让我对创造过程更投入、更有归属感——光这一点就够了。
怎么开始
我有点担心大家读完这篇就立刻把它做成一个 /html skill。这或许有些价值，但我想强调：你不需要做太多东西，Claude 就能干这事。直接说「做一个 HTML 文件」或者「做一个 HTML artifact」就够了。
关键在于你知道你想让这个 artifact 做什么、你打算怎么用它。或许久了你会沉淀成一个 skill，但目前我建议先从零开始 prompt，先摸清楚不同场景下怎么用它。
作者特意踩刹车，是怕大家走 skill 化的快路径。skill 沉淀得太早，会把还没摸清的边界硬套成模板。
用例一：Spec、规划与探索
HTML 是 Claude 深入一个问题的画布。我开始处理一个问题时，不再做一个简单的 Markdown plan，而是预期会织出一张由 HTML 文件构成的网。
比如，我会先让 Claude Code 头脑风暴几种不同方向，给出几条探索路径；然后选一种让它扩展得更深，可能做点 mockup 或代码片段；最后让它写一份实现计划。当计划满意了，我开个新会话，把这些文件一起塞给它去实现。
验证阶段，我也让验证 agent 读这些文件，它就能拿到对「需要做什么」广得多的上下文。
示例 prompt（直译）：
「我不太确定 onboarding 页该往哪个方向做。生成 6 种明显不同的方案——在布局、语气、信息密度上都拉开差距——把它们以网格形式排进同一个 HTML 文件，让我能并排比较。每一个都标上它在做的取舍。」
「在一个 HTML 文件里写出一份完整的实现计划，记得做一些 mockup、画出数据流、附上我可能想过目的关键代码片段。让它易读、易消化。」
适用于：探索同一段代码的不同实现方式；探索多种视觉设计。
用例二：代码评审与理解
代码在 Markdown 文件里挺难读的。但用 HTML 我们可以渲染 diff、加批注、画流程图、画模块图等等。可以用它来理解 agent 写的代码、做 code review，或者向评审者解释你的 PR。我发现这往往比 GitHub 默认的 diff 视图更好用——现在我每个 PR 都会附一个 HTML 代码解释文件。
示例 prompt（直译）：
「帮我评审这个 PR，做成一个 HTML artifact。我对 streaming/backpressure 那段逻辑不熟，重点放那。把真实的 diff 渲染出来、在边上加批注，按严重等级用颜色标注发现，需要的其他可视化也加上。」
适用于：创建 PR；评审 PR；理解一段代码里的某个主题。
用例三：设计与原型
Claude Design 之所以建立在 HTML 之上，是因为 HTML 在设计表达上极其强，即使你最终落地的不是 HTML。Claude 可以先在 HTML 里画出设计草图，再把它写成你想要的语言——React、Swift 都行。
你也可以原型化交互，比如动画、行为等等。可以让 Claude 加滑块、旋钮，调到正好是你想要的。
示例 prompt（直译）：
「我想给一个新结账按钮做原型，点击后先做一段 play 动画，然后快速变紫。做一个 HTML 文件，配几个滑块和选项让我试不同动画参数，再给我一个复制按钮，把跑得好的参数复制出来。」
适用于：制作设计系统物料；调整组件；可视化组件库；原型化「令人愉悦」的动画。
用例四：报告、研究与学习
Claude Code 在跨数据源综合信息、再把它转成可读报告这件事上做得极好。你可以让 Claude 搜你的 Slack、代码库、git 历史、互联网等等，然后用这些素材生成给你自己、给老板、给团队读的高可读性报告。
你可以把成果做成一篇长 HTML、一个交互式讲解器、甚至一个幻灯片。可以让 Claude 用 SVG 画图来辅助可视化。比如我那几篇关于 prompt caching 的帖子，就是让 Claude 读完所有 prompt caching 相关的 git 历史，然后给我做了一份 HTML 深度研究文档来读。
示例 prompt（直译）：「我搞不清楚我们的 rate limiter 到底怎么工作。读相关代码，产出一个单文件 HTML 讲解：画一张 token-bucket 流程图、附 3-4 段关键代码并加批注、底部加一个『坑点』小节。优化为『读一遍就能懂』。」
适用于：总结一个 feature 的工作原理；给我讲清楚一个概念；给老板写周报；给领导写事故报告；SVG 插画、流程图、技术图。
用例五：定制编辑界面
有时候纯靠文字框很难说清你想要什么。这种情况下，我会让 Claude 给我搭一个临时编辑器，专门为我手头这个东西定制——不是产品、也不是可复用工具，就是一个 HTML 文件，专为这一份数据打造。
关键诀窍永远是结尾要有一个导出键：「copy as JSON」或「copy as prompt」，把你在 UI 里干的事变成可以粘回 Claude Code 的东西。
示例 prompt（直译）：
「我要给这 30 个 Linear 工单重新排优先级。给我做一个 HTML 文件，每张工单是可拖动卡片，分布在 Now / Next / Later / Cut 四列里。先按你最优猜测预排好。加一个『copy as markdown』按钮，把最终顺序连同每个分桶一行的理由一起导出。」
「这是我们的 feature flag 配置。给我做一个基于表单的编辑器，把 flag 按领域分组，显示彼此的依赖；如果我打开了一个 flag 但前置 flag 是关的，就警告我。再加一个『copy diff』按钮，只输出变更过的 key。」
「我在调一段 system prompt。做一个并排编辑器：左边可编辑 prompt，把变量槽位高亮；右边三个示例输入实时渲染填充后的模板。加字符/token 计数器和复制按钮。」
适用于：给任何东西重排序、归类、分桶（工单、测试用例、反馈）；编辑带约束的结构化配置（feature flag、env、JSON/YAML）；调 prompt、模板、文案，带实时预览；整理数据集，逐行通过/拒绝、打标签、导出选中项；在文档/转录/diff 上做批注并导出；那些用文字描述特别痛苦的取值——颜色、缓动曲线、裁剪区域、cron 表达式、正则。
常见问答
不是更费 token 吗？ Markdown 通常 token 用得更少，但我发现 HTML 表达力更强、加上我真的会去读它，最终拿到的输出反而更好。Opus 4.7 上有 1MM 上下文，这点 token 增量在窗口里基本不显眼。
现在还用 Markdown 吗？ 老实说我几乎全面停用 Markdown 了，但我大概是 HTML 极端派。
怎么看 HTML 文件？ 我一般直接在浏览器里打开（可以让 Claude 帮你打开），或者传到 S3 拿一个分享链接。
生成不是更慢吗？ 是更慢！HTML 可能比 Markdown 慢 2-4 倍，但我觉得结果值得。
版本控制怎么办？ 这是 HTML 最大的缺点之一。HTML 的 diff 比 Markdown 嘈杂、难评审。
怎么让 Claude 做出来的 HTML 符合我的口味、不那么丑？ frontend design 插件可以让 Claude 做出更好的 HTML。要匹配你公司的风格，可以让 Claude 把代码库读一遍，产出一份 design system HTML 文件，之后其他 HTML 都拿这份做参考。
保持在循环里
上面那一切其实是想说：我用 HTML 的真实理由是——我感觉自己跟 Claude 一起工作时更在循环里了。
我之前开始担心，因为我已经不再认真读那些 plan，所以我只能任由 Claude 替我做选择。
但我很高兴地发现，恰恰相反——用 HTML 之后我比以前任何时候都更觉得自己在循环里。希望你也一样。
原文：https://x.com/trq212/status/2052809885763747935
作者范例集合：https://thariqs.github.io/html-effectiveness/
发表于 昨天 23:44
|
查看: 5|
回复: 0
