AllWorkin / Articles / 2026.05.11

Claude Code 别再输出 Markdown 了——9 类 HTML 玩法(附 Prompt 模板)

Anthropic Claude Code 工程主管 Thariq 公开了一套范式:让 Agent 输出 HTML 而不是 Markdown,能解锁信息密度、长文档可读性、双向交互。本文拆出 9 类立即能用的玩法+可复制 Prompt 模板+5 条单文件守则,以及什么时候不要用 HTML。

2026.05.11约 10 分钟#Claude#Prompt#Agent#设计

资料来源:Thariq Shihipar(Anthropic Claude Code 工程主管)发布在 X 上的长推《Using Claude Code: The Unreasonable Effectiveness of HTML》+ 配套示例站 thariqs.github.io/html-effectiveness(文末附链接)


我最近被一条 X 上的长推文按在地上摩擦。

发的人是 Thariq Shihipar,Anthropic Claude Code 团队的工程主管——不是外部布道者,是给 Claude Code 写代码的那个人。他的观点一句话讲完:

别再让 Claude 给你输出 Markdown 了,换成 HTML,整个工作流会上一个台阶。

这条推文在 X 上播放破百万、收藏过万,HN 顶到一千多分。我一开始也觉得是哗众取宠——Markdown 用得好好的,凭什么换?

把他的 20 个示例 demo 全点开看了一遍之后,我服了。这玩意儿不是审美问题,是工程问题:你用 Claude Code 干的活越复杂、协作的人越多,Markdown 越是兜不住。

下面我把他这套范式拆开讲清楚,包括:

  • 为什么 HTML 真的比 Markdown 更适合 Agent 输出
  • 9 类立即能用的玩法(每类配一个可复制的 Prompt 模板)
  • 5 条单文件守则(防止生成的东西半年后烂掉)
  • 什么时候不要用 HTML(避免无脑套用)

1)Markdown 的隐藏天花板:为什么 Agent 时代它不够用了

Markdown 当年能赢,是因为它简单、好读、Token 便宜。GPT-4 时代上下文窗口只有 8K,每一个 Token 都得抠着用,Markdown 是当时的最优解。

但今天的 Claude Code 已经在 1M 上下文里跑。它能一口气读完一个仓库,从 git 历史、MCP 服务器(比如 Slack、Linear)、文件系统、浏览器多个地方拼出上下文,最后甩给你一份输出。

问题是这份输出的天花板,被 Markdown 卡死了。

Thariq 总结了 5+1 个理由,我用大白话翻译给你:

① 信息密度:HTML 一个文件能装表格、SVG、CSS、JS、图片、交互;Markdown 只能装段落、列表、链接、代码块、简陋表格。让 Claude 用 Markdown “表示颜色”,它只能用 Unicode 字符瞎凑。

② 100 行就是 Markdown 的边界:超过 100 行的 Markdown 文件,没人真的会读完。包括 Thariq 自己。但 Claude Code 给你的实现计划动不动就几百行。HTML 可以加标签页、目录、折叠区,长文档依然能逛。

③ 分享方便:一个 .md 文件甩到群里,对方还得装个编辑器或者转一下;HTML 文件丢到 S3 或者公司 CDN,发链接就行,谁点开都能看。别人愿意点开看的概率,比 Markdown 高几倍。

④ 双向交互:HTML 不只是“输出”,还能是“输入”。加几行 JS 就能在文档里嵌滑块、按钮、调参面板,甚至加个“导出当前状态到 Prompt”的按钮,回头接着喂给 Agent。Markdown 没这能力。

⑤ 读起来开心:一份排版好的 HTML 和一坨方括号星号下划线的 Markdown,阅读体验差一个量级。

⑥(加分项)适配 Agent 的输入广度:Claude Code 现在能从 filesystem / MCP / 浏览器 / git 多个源吸收上下文。这些异构信息揉在一起,用 HTML 表达比 Markdown 几乎总是更有表现力。

讲到这里你可能还是无感。直接看 9 类玩法你就懂了。


2)9 类立即能用的 HTML 玩法(每类配 Prompt 模板)

Thariq 配了一个示例站 thariqs.github.io/html-effectiveness,20 个 demo 全部是 Claude Code 真实生成的单文件 HTML,分成 9 类。

我按“日常用得到”的优先级重新排了序。每一类后面给一个可以直接复制粘贴到 Claude Code 的 Prompt 模板。

玩法 1:探索与规划(Exploration & Planning)

用场景:你还没想好方案,让 Agent 把几条路并排画给你看,比让它写三段文字描述高效十倍。

示例:三套代码方案的横向对比表 / 四种 UI 视觉方向并列展示 / 完整的实现计划(带时间线 + 数据流图 + 风险表)

Prompt 模板:

我还没想清楚 [某个功能] 应该怎么做。
请生成 4-6 种明显不同的方案,从布局、信息密度、技术取舍上分开。
把它们放在同一个 HTML 文件里以网格排列,让我可以并排对比。
每一个都标注它在做什么取舍。

玩法 2:Code Review 与代码理解

用场景:让 Claude 把 PR 渲染成带标注的 diff,按严重程度上色,再画个模块关系图。比在 GitHub 上滚 diff 友好太多。

Thariq 本人说他现在每个 PR 都附一份 HTML 说明文件,给 reviewer 当导览。

示例:带边栏标注的 PR 评审页 / PR 作者写给 reviewer 的导览页 / 不熟悉的模块画成盒子箭头图

Prompt 模板(译自 Thariq 原文里给出的示例):

帮我 review 这个 PR,做成一个 HTML 文件来描述它。
我对 streaming / backpressure 那块逻辑不熟,重点分析那里。
渲染真实的 diff,加上边栏批注,
按严重程度对发现的问题配色,
其他能帮我快速理解的东西也都加上。

玩法 3:设计系统(Design System)

用场景:HTML 本来就是设计系统的最终交付物,让 Claude 直接吐成单文件设计系统再合理不过。色板可以点击复制,组件状态一字排开。这份文件可以反喂给下一次 Prompt 当样式参考,保证多次生成的视觉一致性。

示例:从仓库里抽出 Token 渲染成可复制色板 / 一个组件的所有 size × state × intent 并排展示

Prompt 模板:

读一下这个仓库的样式定义,
生成一个单文件 HTML 设计系统:
颜色、字体、间距 token 全部渲染成可点击复制的色板;
列出 [组件名] 的所有变体(每个 size、state、intent 都画一遍)。
后续我会把这个文件作为视觉参考喂给你。

玩法 4:原型(Prototyping)

用场景:动效和交互没法用语言描述,必须摸一下才知道对不对。让 Agent 做个一次性的 throwaway 页面(用完即扔)跑给你看,五秒钟就能判断“是不是这个味”。

示例:单独把动效拎出来,配 duration / easing 滑块当 sandbox / 四个页面串成一个可点击 flow

Prompt 模板:

单独把 [这个动效/这个交互] 做成一个 HTML 原型。
带几个滑块可以调 duration 和 easing,
把不同参数下的效果放一起,让我能直接感受。

玩法 5:SVG 插图与流程图

用场景:把 inline SVG 当成“画笔”用。让 Claude 给一篇博客画几张配图,或者画一张可点击的部署流水线,比 Mermaid 灵活,比外部画图工具省事。

示例:博客配图整张表(每张可单独复制出来)/ 部署流水线流程图(点每一步看运行内容、耗时、失败路径)

Prompt 模板:

为我下面这篇文章生成 N 张 SVG 配图,
全部放在一个 HTML 文件里,
每张图带一个"复制 SVG"按钮,让我能单独抠出来用。
风格:[简洁/手绘/科技感]。

玩法 6:研究与学习

用场景:让 Claude 解释一个新概念时,让它给你做一份带 TL;DR、可折叠章节、Tab 切换代码片段、悬停术语表的解释页。和直接看一坨段落的体验,差的是阅读路径有没有被设计过。

示例:解释这个仓库的限流是怎么工作的(带请求路径折叠步骤 + 配置 tab + FAQ)/ 一致性哈希实时可视化(拖节点观察 ring 变化)

Prompt 模板:

我没太搞明白我们这套 [限流/缓存/X 模块] 怎么工作的。
读相关代码,生成一份 HTML 解释页:
- 顶部 TL;DR
- 一张关键流程图
- 3-4 段关键代码带行内注解
- 末尾一段"踩坑提醒"
按"读一次就够"的标准去优化它。

玩法 7:报告(Status / 复盘)

用场景:周报、事故复盘、季度回顾这种重复出现的文档,用 HTML 做一次模板,以后每周改数据就行。一张小图 + 一段彩色时间线,能从“扫两眼就关了”变成“愿意从头看完”。

示例:周报(含 ship / slip / 一张小图)/ 事故复盘(带分钟级时间线、日志片段、跟进清单)

Prompt 模板:

基于这份 [周报数据/事故记录],
生成一份 HTML 报告:
- 顶部一张关键指标小图
- 中间彩色时间线
- 底部跟进事项清单(带责任人、截止日期)
排版要适合周一早上扫读。

玩法 8:幻灯片(Decks)

用场景:内部技术分享别再开 Keynote 了,直接让 Claude 把一个 Slack 长讨论或一份设计文档转成单文件 HTML 幻灯片,左右方向键翻页,发链接就能开会。

示例:左右键翻页的 HTML deck,一个文件搞定,无 build 步骤

Prompt 模板:

把下面这份 [设计文档/讨论内容] 转成一份 HTML 幻灯片。
单文件,左右方向键翻页,无外部依赖。
风格简洁。重点突出 [关键结论]。

玩法 9:一次性自定义编辑器(Custom Editing Interfaces)

这一类是我看完最惊艳的——让 Claude 给你做个一次性的小工具。

用场景:有些事情用文本框描述太累,让 Claude 直接做一个针对这个任务的临时编辑器,干完就扔。重点是最后必须有一个“导出”按钮,把你在 UI 里做的操作转回 Prompt 或 Markdown,喂回 Agent 继续干。这样你始终在循环里,但循环变紧了。

示例:30 条 ticket 拖进 Now / Next / Later / Cut 四个泳道,最后一键导成 Markdown / Feature flag 编辑器(带依赖检查、一键复制 diff)/ Prompt 调参器(左边模板、右边三组样例实时渲染)

Prompt 模板:

我需要把这 [N] 条 [ticket / flag / prompt] 重新排序整理。
做一个一次性的 HTML 编辑器,让我可以 [拖拽/勾选/编辑],
最后给我一个"导出"按钮,
把结果转成 Markdown / JSON / 新的 Prompt 让我贴回 Claude。

3)5 条单文件守则:防止你今天生成的东西半年后烂掉

直接让 Claude 给你输出 HTML,大概率会写出依赖 CDN、引外部字体、调远程 API 的东西。今天能用,半年后 CDN 一断、库一升级,文件就废了。

社区在用了几个月之后,已经收敛出一份很硬的规矩,写一次 html-rules.md 放进 CLAUDE.md 里就行:

  1. CSS 内联或放在 <style> 标签里,不引外部样式表、不引 CDN
  2. JS 全部内联写在 <script> 里,不从 unpkg / jsDelivr 引包
  3. 图片用 Base64 内嵌到 src,或者直接 inline SVG,不引外链图
  4. 字体只用系统字体(system-ui / sans-serif / monospace),不引 Google Fonts
  5. 运行时零网络请求,文件断网状态下也要能完整打开

这五条说穿了,就一句话:让 HTML 像 PDF 一样自洽。十年后你打开还能看,就靠这个。


4)三个可以今天就试的 Prompt(开箱即用)

懒得自己想 Prompt 的话,直接抄这三个。都是从 Thariq 的示例里改写过来的、最容易出效果的:

① 让 Claude 给方案做横向对比:

我要做 [某个功能] 但还没定方案。
请生成 6 种明显不同的方案,从布局/信息密度/技术取舍上区分。
单个 HTML 文件、网格排列、并排对比。
每个标注它的取舍。

② 让 Claude 给 PR 做带标注的 Review:

帮我 review 这个 PR,做成一个 HTML 文件。
我对 [streaming/backpressure/任何不熟悉的部分] 不熟,重点看那块。
渲染真实 diff、加边栏批注、按严重程度配色,
该补什么补什么,让我快速看明白。

③ 让 Claude 解释代码:

我没搞明白我们这个 [限流器 / 缓存 / 某模块] 怎么工作的。
读相关代码,输出一个 HTML 解释页:
- token bucket 流程图
- 3-4 段关键代码加注解
- 一段"踩坑提醒"
按"一次性读懂"的标准优化。

5)什么时候不要用 HTML(别无脑套用)

把这一节放在最后,是因为太多人看完一篇好文章就 all in,结果踩进新坑。

下面这些场景,继续用 Markdown:

  • 仓库 README:GitHub / GitLab 原生渲染 Markdown,搜索索引只认 MD,团队也方便人人编辑
  • Slack / Discord 里的代码片段:Markdown 的代码栅格是通用的,HTML 贴进去就是一坨原码
  • 要被其他 LLM 消费的文档:模型对 Markdown 的训练数据多得多,RAG 工具对 Markdown 的分段也更准
  • 要长期 Git 跟踪、做 blame 的文件:HTML diff 又脏又长,根本没法 review
  • 写给自己看的备忘录:你要的是快速记下来,没必要为了排版多花十分钟
  • 邮件简讯 / RSS:邮件客户端对内联 CSS 的支持参差不齐,渲染常常翻车

一条简单的判断标准:

HTML 给“别人读但不改”的场景,Markdown 给“自己改或机器读”的场景。


6)我的判断:HTML 输出会成为 Agent 时代的默认形态

写 README 我还会继续用 Markdown。但任何一份要给别人看的工程产出——PR 说明、实现计划、复盘报告、技术分享、设计探索——我已经全部换成让 Claude Code 出 HTML 了。

体感上最大的变化跟“美观”没关系,是别人愿意看的概率明显高了一截。

以前发一个 .md 到群里,大概率没人点开;现在发一个 HTML 链接,团队成员会真的扫一眼,然后回我一句“第 3 节那个方案我倾向 B”。输出格式直接决定了协作密度。

Thariq 这条推文的真正价值,是他用 Anthropic 内部团队的真实做法证明:用 Claude Code 不只是让它“写代码”,而是让它做“一次性工具”——一份带交互的报告、一个用完即弃的编辑器、一份能拖来拖去的看板。

工具便宜到一次性能用了,这件事本身才是 Agent 真正改变了什么。

AI工具实战派

觉得有用?每周的新笔记先发公众号。

每周的实战笔记先发在这里。扫码关注,新文章第一时间推给你。

关注 / 加入社群 →