为什么选 HTML？
核心要点
- Markdown 正在成为 Agent 输出的瓶颈：超过百行的 Markdown 难以阅读，更难分享给同事；作者本人也不再亲手编辑这些文件，而是让 Claude 改——这就让 Markdown "易于人类编辑" 的核心优势失效了
- HTML 是表达能力上限更高的输出载体：表格、CSS、SVG、脚本、交互、绝对定位、图片，几乎所有 Claude 能读的信息都能高效用 HTML 表达
- HTML 让"被读到"的概率显著提升：可直接上传 S3 生成可分享链接，可响应式适配手机，可作为 PR 说明附件——同事真去读的概率远高于 Markdown
- 双向交互能力：可加入滑杆/旋钮微调设计参数、给出"复制为 prompt"按钮，把人在 UI 里的操作再喂回 Claude Code
- Claude Code 的独特优势是上下文摄取：能读本地代码库、git 历史、MCP（Slack/Linear）、浏览器，比 Claude.ai/Claude Design 更适合生成富信息 HTML
- 不需要 /html skill：直接说"做一个 HTML 文件"或"做一个 HTML artifact"即可，重点是想清楚这个 artifact 要做什么、怎么用
- 代价：生成时间 2–4 倍于 Markdown、HTML diff 噪声大不利版本控制、token 消耗更高——但作者认为在 Opus 4.7 的 1M 上下文窗口下完全可接受
原文链接 English Original by Thariq (@trq212) · 2026-05-09
Markdown 已经成为 Agent 与我们沟通的主导文件格式。它简单、可移植、具备基本富文本能力，并且便于编辑。Claude 甚至在用 ASCII 在 Markdown 里画图这件事上表现得意外出色。
但随着 Agent 能力越来越强，我感觉 Markdown 已经成了一种束缚。超过一百行的 Markdown 文件我已经很难读下去了。我想要更丰富的可视化、颜色和图表，并且能够便捷地分享出去。
更现实的是，**我越来越少亲手编辑这些文件，而是把它们当作规格说明（spec）、参考文件、头脑风暴产物来使用。**真要改的时候，也是提示 Claude 去改——这就把 Markdown 最大的优势之一（人易于编辑）给抹掉了。
我已经开始倾向于用 HTML 而不是 Markdown 作为输出格式，并且看到 Claude Code 团队的其他人也越来越多地这样做。下面解释为什么。
（如果你想先看一些例子，可以直接看这里：https://thariqs.github.io/html-effectiveness，看完记得回来读完原因部分。）
为什么选 HTML？
信息密度
HTML 能比 Markdown 传达远更丰富的信息。当然它也能做简单的文档结构（标题、格式化），但它还能表达各种各样的信息：
- 表格数据（用 <table>）
- 设计数据（用 CSS）
- 插图（用 SVG）
- 代码片段（用 <script> 标签）
- 交互（用 HTML 元素 + JS + CSS）
- 工作流（用 SVG 和 HTML）
- 空间数据（用绝对定位和 <canvas>）
- 图片（用 <img> 标签）
我甚至可以说：**几乎没有任何 Claude 能读到的信息集，是无法用 HTML 高效表示的。**这让 HTML 成为模型向你传达深度信息、以及你审阅信息的高效方式。
如果不能用 HTML，模型就会在 Markdown 里做一些更低效的事，比如用 ASCII 画图，或者我最喜欢的——用 Unicode 字符来估计颜色，就像下面这张 Claude Code 的截图：
Claude Code 试图在 Markdown 中表示颜色
视觉清晰度与阅读体验
随着 Claude 能做的工作越来越复杂，它写的规格说明和计划也越来越长。实际情况是，我自己也不会真的去读超过 100 行的 Markdown 文件，更别说让我团队里的其他人去读了。
但 HTML 文档就好读得多——Claude 可以把结构组织得视觉上便于导航（用 tab、插图、链接等），甚至可以做成移动端响应式，让你根据设备形态切换阅读方式。
易于分享
Markdown 文件分享起来挺麻烦的，因为大多数浏览器不能原生渲染。你往往得作为邮件或消息的附件发送。
而 HTML 只要你上传到（例如 S3），就能轻松分享链接。你的同事可以在他们想要的地方打开，方便引用。
用 HTML 写规格说明、报告或 PR 说明，被人真正读到的概率会高得多得多。
双向交互
HTML 还允许你与文档交互。例如你可以让它加上滑杆或旋钮来调整某个设计，或者切换算法的不同选项看看会发生什么。你也可以让它提供"把这些更改复制成 prompt"的按钮，再粘贴回 Claude Code。关于这种双向交互的更多例子，可见我的 playgrounds 一文：https://x.com/trq212/status/2017024445244924382
数据摄取（Data Ingestion）
为什么要用 Claude Code 而不是 Claude.ai 或 Claude Design 来生成 HTML？最大的原因之一就是 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，先在不同场景里摸索手感。
使用场景
为了让讨论更具体，我做了很多面向不同场景的 HTML 文件。全部可见：https://thariqs.github.io/html-effectiveness/。下面是几大类的概述。
规格说明、规划与探索
HTML 是 Claude 深入一个问题的丰富画布。**当我开始处理一个问题时，我不再期待一份简单的 Markdown 计划，而是期待生成一张 HTML 文件织成的网。**例如我会先让 Claude Code 头脑风暴，生成对不同选项的探索；然后让它在某一个方向上展开，做模拟图（mockup）或代码片段；最后觉得不错时，让它写一份实施计划。计划满意后，我会开一个新会话，把所有这些文件传进去让它来实现。
验证阶段也一样——我会让验证 Agent 把这些文件读进去，它对所需内容就会有更宽广的上下文。
示例 prompt：
- 我不确定 onboarding 屏应该往哪个方向走。生成 6 个差异显著的方案——在布局、语气和密度上做变化——把它们以网格形式排在一个 HTML 文件里方便我并排对比。每个标注它在做什么权衡。
- 在一个 HTML 文件里写一份完整的实施计划，记得做一些模拟图、展示数据流、加上我可能想看的关键代码片段。要易读易消化。
适用场景：
- 探索代码实现的不同方式
- 探索多种视觉设计方案
代码审查与理解
代码在 Markdown 文件里很难读。但用 HTML 我们可以渲染 diff、注释、流程图、模块图等等。可以用它来理解 Agent 写的代码、做 code review，或者向 review 你 PR 的人解释你的代码。我发现这往往比 GitHub 默认的 diff 视图效果更好——我现在给每个 PR 都附上一个 HTML 代码讲解器。
示例 prompt：
帮我 review 这个 PR，做一个 HTML artifact 来描述它。我不太熟悉 streaming/backpressure 逻辑，所以重点讲那块。把实际 diff 渲染出来，加上行间注释，把发现的问题按严重程度做颜色编码，以及其它任何有助于表达概念的方式。
适用场景：
- 创建 PR
- Review PR
- 理解代码中的某个主题
设计与原型
Claude Design 基于 HTML，因为 HTML 在设计表达上极其强大——即使你的最终输出表面不是 HTML。Claude 可以先用 HTML 把设计勾勒出来，再用你选择的语言（React、Swift 等）写出来。
你也可以原型化交互，比如动画、动作等等。可以让 Claude 做滑杆、旋钮等，把你想要的效果调到精确。
示例 prompt：
我想原型一个新的 checkout 按钮，点击时先播一段动画然后快速变紫。做一个 HTML 文件，给我几个滑杆和选项让我试这个动画的不同参数；再给一个 copy 按钮让我复制那些效果好的参数。
适用于：
- 创建设计系统的产物
- 调整组件
- 可视化组件库
- 原型化让人愉悦的动画
报告、研究与学习
Claude Code 极擅长跨多个数据源综合信息，并把它转成可读性强的报告。你可以提示 Claude 搜你的 Slack、代码库、git 历史、互联网等等，用来给自己、给领导、给团队生成极易读的报告。
你可以把它组装成长 HTML 文档、交互式讲解、甚至幻灯片/demo deck 的形式。让 Claude 用 SVG 画图来辅助可视化。例如我写关于 prompt caching 的文章时，让 Claude 先读 git 历史，再准备一份深度研究的 HTML 文件给我读所有 prompt caching 的变化。
示例 prompt： 我搞不清楚我们的限流器（rate limiter）到底是怎么工作的。读相关代码，做一个单页 HTML 讲解器：包含 token-bucket 流程的图、3–4 个加注释的关键代码片段，底部加一个"陷阱（gotchas）"section。优化它给一次性阅读者看。
适用于：
- 总结某个功能如何工作
- 给我讲解某个概念
- 给老板的周报
- 给领导层的事故报告
- SVG 插图、流程图、技术示意图等
定制编辑界面
有时候很难纯粹用文本框描述你想要什么。这时我会让 Claude 给我搭一个一次性使用的编辑器，专门针对我手头这一块数据。不是产品，不是可复用工具，而是单个 HTML 文件，为这一块数据量身定做。
诀窍始终是以一个导出（export）收尾：一个 "copy as JSON" 或 "copy as prompt" 按钮，把我在 UI 里做的操作再转回我可以粘贴到 Claude Code 的东西。
示例 prompts：
- 我要给这 30 条 Linear 工单重新排序。做一个 HTML 文件，每条工单是一张可拖拽的卡片，跨越 Now / Next / Later / Cut 四列。先按你最好的猜测预排一遍。加一个 "copy as markdown" 按钮，导出最终顺序，每个分组配一句话理由。
- 这是我们的 feature flag 配置。做一个基于表单的编辑器，按区域分组、展示 flag 之间的依赖、如果我开了一个前置开关是关的 flag 给我警告。加一个 "copy diff" 按钮只导出变更过的 key。
- 我在调一个 system prompt。做一个并排编辑器：左边是可编辑的 prompt 并高亮变量槽位，右边是三个示例输入实时渲染填充后的模板。加上字符/token 计数器和复制按钮。
适用于：
- 给任何东西重新排序、分诊、分桶（工单、测试用例、反馈）
- 编辑结构化配置（feature flag、环境变量、带约束的 JSON/YAML）
- 调 prompt、模板或文案，并实时预览
- 整理数据集，逐行批准/拒绝，给样本打标签，导出选定的内容
- 给文档、转录稿或 diff 加注释，并导出注释
- 选那些用文字难以表达的值：颜色、缓动曲线（easing curve）、裁剪区域、cron 表达式、正则表达式
常见问题
我跟很多人讲过我换到 HTML 的事，遇到了几个反复出现的问题。
这不是更费 token 吗？ 虽然 Markdown 通常用更少的 token，但我发现 HTML 多出来的表达力 + 我真去读它的概率大幅提高，整体产出反而更好。在 Opus 4.7 的 1M 上下文窗口下，多出来的 token 用量在上下文里其实并不明显。
那你现在什么时候还用 Markdown？ 说实话我几乎全面停用 Markdown 了，不过我大概在 HTML 极端派那一侧很远。
怎么看 HTML 文件？ 我一般就在本地浏览器里打开（你可以让 Claude 帮你打开），如果想要可分享链接就上传到 S3。
这不是比 Markdown 慢吗？ 是会更慢！HTML 生成可能比 Markdown 慢 2–4 倍，但我觉得结果是值得的。
版本控制怎么办？ 说实话这是 HTML 最大的缺点之一——HTML 的 diff 噪声大，比 Markdown 难审。
怎么让 Claude 符合我的审美/不做得难看？ frontend design 插件能帮 Claude 做出好看的 HTML 文件。要匹配你公司自己的风格，可以让 Claude 把你的代码库扫一遍，生成一个单独的"设计系统" HTML 文件，之后把这个文件作为其它 HTML 文件的参考。
保持在环路里（Stay in the Loop）
上面说的这些归根结底是：**我用 HTML 的真正原因，是我感觉自己比以前更"在环路里"和 Claude 一起工作了。**我曾经开始担心，因为我已经不再深读 plan，我可能只能放手让 Claude 自己做选择。
但很高兴地讲，使用 HTML 反而让我感觉比以往任何时候都更"在环"。希望你也能感受到。
译者笔记
在 VariFlight 场景的可借鉴点
- PRD 与原型一体化：本仓库的 PRD 已经走"Markdown 框架 + 嵌入 HTML 原型 iframe"路径（见全局记忆 ## HTML Prototype Embedding in PRD），可以把更多探索性/对比性的可视化也用 HTML artifact 沉淀到 页面原型/，PRD 用 wikilink + iframe 引用
- PR/代码 review 讲解器：作者每个 PR 都附 HTML 代码讲解器的做法，对 OnlineTicketBookingSystem（Java）和 fticket_app（PHP）的跨语言代码理解、给非技术 stakeholder 解释代码逻辑，可能比 Markdown ASCII 更适合
- "一次性编辑器"模式：对应到飞常准国际机票这种规则多、配置多的产品，未来做"舱位规则编辑器""价格策略 diff 查看器"等内部工具时，可以让 Claude 直接做一个 HTML 单文件而不是 Markdown 表格
- 风险提示：HTML diff 噪声大不利于 git 评审；用于 PRD 等需要长期演进的文档时，建议保留 Markdown 框架，仅在内嵌图示/对比/原型时使用 HTML（与现有 PRD HTML 嵌入约定一致）
Related Documents
- English Original
- 使用 Claude Code：会话管理与百万上下文
- 使用 Claude Code 制作 Playgrounds
- AI 技术博客索引