Markdown 已经成了 AI 代理与我们沟通的事实标准格式。它简单、可移植、有一定的富文本能力，而且易于编辑。Claude 甚至在用 ASCII 绘图表方面意外地强。
但随着 AI 代理越来越强大，Markdown 开始让人感到局限。超过一百行的 Markdown 文件就读不下去了。我想要更丰富的可视化、颜色、图表，而且要能方便地分享。我也越来越不直接编辑这些文件了——更多是把它们当作规格说明、参考文档、脑暴输出的载体。即使要改，通常也是让 Claude 去改，这就抹掉了 Markdown 最大的好处之一。
所以我开始更倾向用 HTML 替代 Markdown 输出，并且在 Claude Code 团队内部也越来越多人这样做。原因如下。
<!--more-->HTML 能表达的信息远比 Markdown 丰富
HTML 当然能做简单的文档结构——标题、格式——但它还能表示各种其他类型的信息：
- 表格数据：用
<table>呈现结构化数据 - 设计数据：用 CSS 控制视觉
- 插图：用 SVG 绘制
- 代码片段：用
<script>标签嵌入 - 交互：HTML 元素 + JavaScript + CSS 组合出可操作的界面
- 工作流：SVG + HTML 画出流程图
- 空间数据：绝对定位和 Canvas
- 图片：原生
<img>标签
几乎任何 Claude 能读取的信息集，都能相当高效地用 HTML 表示。这让它成为一种极其高效的信息传递介质——模型深度传递信息给你，你review信息的效率也更高。
我发现在无法使用 HTML 时，模型在 Markdown 里只能用更笨的方式表达，比如 ASCII 图表，或者用 Unicode 字符估算颜色——就像这张 Claude Code 的截图那样。
Claude Code 试图在 Markdown 里展示颜色，手段极为有限。
长文档的可读性
Claude 能做越来越复杂的工作，也意味着它输出的规格说明和计划越来越大。实际上我发现超过一百行的 Markdown 我自己都看不完，更别说让团队其他人去读。
但 HTML 文档好读得多。Claude 可以用视觉方式组织结构——标签页、插图、链接等，让导航更高效。它甚至可以是移动端响应的，在不同设备上呈现不同阅读体验。
分享更容易
Markdown 文件很难分享，因为大多数浏览器不能原生渲染它。你通常只能把它作为邮件或消息的附件发送。
而 HTML，只要把文件上传（比如到 S3），就能轻松分享链接，同事们随时随地打开，引用也方便。一份规格说明、报告或 PR 说明的实际被阅读概率，HTML 版本比 Markdown 高得多。
可交互的文档
HTML 允许文档本身具有交互性。例如，你可以让它加上滑块或旋钮来调节设计参数，或调整算法中的不同选项看看会发生什么。它甚至可以包含"把这些变化复制为提示词粘贴回 Claude Code"的功能——实现双向交互。
Claude Code 的独特优势
为什么用 Claude Code 生成 HTML 而非直接用 Claude AI 或 Claude Design？最大的原因在于 Claude Code 能摄入的上下文太多了。比如写这篇文章时，我让 Claude Code 读取了整个代码文件夹，找出所有生成的 HTML 文件，分类整理，生成了一张包含所有图示的 HTML 文件。文中所有的图表就是直接源于此。
除了文件系统，Claude Code 还能通过 MCP（比如 Slack、Linear）、浏览器插件、Git 历史等获取额外上下文。
用 Claude 生成 HTML 文档更有参与感，这让整个创作过程更有趣——光是这一点，就足够了。
不要想复杂了
我有点担心大家读完这篇文章会把它变成一个 /html skill。虽然这可能有价值，但我想强调：你不需要做很多才能让 Claude 生成 HTML。你直接说"生成一个 HTML 文件"或"生成一个 HTML artifact"就行。
诀窍在于知道自己想要这个 artifact 做什么，以及如何使用它。你可以慢慢形成自己的 skill，但眼下我建议直接从零开始提示，慢慢找到不同场景的感觉。
具体用法举例
探索与构思
HTML 是 Claude 深入问题的一片丰富画布。当我开始处理一个问题时，不再只是生成一个简单的 Markdown 计划，而是期望创建一组互相连接的 HTML 文件。比如先让 Claude Code 脑暴并创建若干不同方向的探索，然后选择一个深入扩展，可能做 mockup 或代码片段，最后觉得方向对了再让它写实施计划。满意之后开一个新 session，把这些文件全部传进去让它执行。验证时也让验证 agent 读这些文件，它对整体需求的理解会宽泛得多。
示例提示：
我不确定 on boarding 屏幕该往哪个方向走。生成 6 种截然不同的方案——布局、语气、密度各有差异——以网格形式放在一个 HTML 文件里便于对比。为每种标注它所做的权衡。
在一个 HTML 文件里创建一份详尽的实施计划，包含 mockup、数据流图和重要的代码片段。易于阅读和消化。
适合场景：
- 探索代码实现的其他方案
- 探索多种视觉设计方案
代码理解与 PR Review
代码在 Markdown 里读起来很费劲。但用 HTML 可以渲染 diff、注解、流程图、模块关系图等。用这个方式理解 agent 写的代码、做 code review，或者向别人解释 PR。我发现这往往比 GitHub 默认的 diff 视图更好用，我现在每个 PR 都附上 HTML 代码说明。
示例提示：
帮我 review 这个 PR，生成一个 HTML artifact 来描述它。我对 streaming/backpressure 逻辑不太熟悉，重点关注那部分。用内联边注渲染实际 diff，按严重程度着色标注，并在需要的地方解释概念。
适合场景：
- 创建 PR
- Review PR
- 理解代码中的某个主题
设计原型
Claude Design 基于 HTML，因为 HTML 在表达设计上极为强大——即使你的最终交付不是 HTML。Claude 可以用 HTML 画出设计草图，再用你选择的语言（React、Swift 等）写出代码。你还可以原型化交互效果——比如动画、动作等。让 Claude 加上滑块和旋钮来微调参数，找到满意的选项。
示例提示：
我想原型化一个新版的 checkout 按钮，点击后播放动画然后迅速变成紫色。创建一个 HTML 文件，包含多个滑块和选项来尝试这个动画的不同参数，给我一个复制按钮把效果好的参数复制出来。
适合场景：
- 构建设计系统 artifact
- 调整组件参数
- 可视化组件库
- 原型化交互动画
报告与信息综合
Claude Code 在综合来自多个数据源的信息方面极为擅长。你可以提示它搜索 Slack、代码库、Git 历史、互联网等，生成极为可读的汇报——给自己看、给领导看、给团队看。可以是一份长 HTML 文档，也可以是交互式 explainer，甚至是一组幻灯片。让 Claude 用 SVG 画图表来可视化信息。例如我在写 prompt caching 相关的文章时，就让 Claude 读取了 git 历史，为我准备了一份详尽的 HTML 研究文件。
示例提示：
我不理解我们的限流器到底是怎么工作的。读取相关代码，生成一个单独的 HTML explainer 页面：画出 token-bucket 流程图，标注 3-4 个关键代码片段，底部加一个"避坑提示"部分。优化到让人读一遍就能理解。
适合场景：
- 总结某个功能的工作原理
- 向他人解释某个概念
- 给老板的周报
- 给领导的事故报告
- SVG 插图、流程图、技术图表
定制化编辑器
有时候光靠文字框很难描述清楚你想要什么。这种情况下，我会让 Claude 给我建一个专门处理我正在做的事的临时编辑器。不是产品，也不是可复用工具，而是一个专门为这份数据构建的 HTML 文件。诀窍是最后一定要加导出功能："复制为 JSON"或"复制为 prompt"按钮，把我在 UI 里做的操作变回能粘贴进 Claude Code 的内容。
示例提示：
我需要重新排这 30 个 Linear ticket 的优先级。给我做一个 HTML 文件，每个 ticket 作为可拖拽的卡片分布在 Now / Next / Later / Cut 四个列里。提前按最佳猜测排序。加一个"复制为 Markdown"按钮，导出每个 bucket 的最终顺序，每 bucket 附一句理由。
这是我们的功能开关配置。构建一个表单编辑器，分组展示 flag，显示相互依赖关系，在我启用某个 flag 但其前置条件未打开时发出警告。加一个"复制 diff"按钮，只给出变动的 keys。
我在调这个 system prompt。做一个左右并排的编辑器：左边是可编辑的 prompt，高亮变量槽；右边是三个示例输入，实时渲染填充后的模板。加字符/Token 计数器和复制按钮。
适合场景：
- 对任何事物进行排序、分组、筛选（ticket、测试用例、反馈）
- 编辑有约束的结构化配置（功能开关、环境变量、JSON/YAML）
- 调优提示词、模板或文案并实时预览
- 整理数据集，approve/reject 行，标签示例，导出选择
- 给文档、转录、diff 加注释并导出
- 选择用文字难以表达的值：颜色、缓动曲线、裁剪区域、cron 表达式、正则表达式
常见问题
Q: HTML 不是更耗 token 吗？ Markdown 确实往往用更少 token。但我发现 HTML 表达力的提升加上我真正去读它的概率大大提高，总体收益更好。Opus 4.7 有 100 万 context window，token 增加在这个范围内基本感觉不到。
Q: 现在什么时候还用 Markdown？ 老实说我几乎所有事情都不用 Markdown 了，但我可能属于 HTML 最大化主义者那一端。
Q: 怎么看 HTML 文件？ 我一般直接在浏览器里打开（可以问 Claude 打开它），如果需要分享链接就上传到 S3。
Q: 生成 HTML 不是比 Markdown 慢很多吗？ 确实慢！HTML 生成时间是 Markdown 的 2-4 倍，但我觉得结果值得。
Q: 版本控制怎么办？ 这确实是 HTML 最大的缺点之一——HTML 的 diff 噪声很大，比 Markdown 难 review。
Q: 怎么让 Claude 的审美不翻车？ 前端设计 plugin 能帮助 Claude 生成更好看的 HTML。但要匹配你自己公司的风格，可以创建一个设计系统的 HTML 文件，让 Claude 读取你代码库里已有的设计模式，然后以那个设计系统文件为参考生成其他 HTML 文件。
写在最后
说了这么多，我认为我用 HTML 的真正原因是：它让我感觉和 Claude 的协作更在状态里。
我曾一度担心因为不再深入阅读计划，迟早只能让 Claude 自己去做决定。但我很高兴地说，用了 HTML 之后，我反而感到比以往任何时候都更在循环里。希望你也是。