Markdown 已成 Agent 与人沟通的主流文件格式：简单、可移植、有一点富文本能力、也好改。Claude 甚至已经能在 Markdown 里用 ASCII 画图，而且画得出奇地好。
但随着 Agent 越来越强，我发现 Markdown 越来越束手束脚。具体来说：超过一百行的 Markdown 我很难读下去；我想让 Claude 生成更丰富的可视化、颜色和图表；也想更容易分享这些产出。
我自己也越来越少亲手改这些文件，而是把它们当规格和引用。真要改时，通常是提示 Claude 去改——Markdown「好改」这一大优势也就没了。
于是我开始更偏向用 HTML 当输出格式，也越来越多看到 Claude Code 团队其他人这么做。本文分享我们为何、以及如何用 HTML 做出更丰富、更易读的 Claude Code 产出。若想跟着试，常见场景可用这些 HTML 文件模板。
为什么用 HTML？
相对 Markdown，HTML 更适合我现在用 Claude Code 做的一类工作，包括需要或涉及：
信息密度
HTML 能传达远比 Markdown 丰富的信息。当然能做标题、格式这类简单文档结构，也能表示：
- 用表格表示表格数据
- 用 CSS 表示设计数据
- 用 SVG 做插图
- 用 script 标签放代码片段
- 用 HTML 元素 + JavaScript + CSS 做交互
- 用 SVG 和 HTML 表示工作流
- 用绝对定位和 canvas 表示空间数据
- 用 image 标签放图片
在我看来，几乎没有 Claude 能读、却不能用 HTML 高效表示的信息集。这让模型能高效把深度信息传给你，也方便你审阅。
若做不到这点，模型往往会在 Markdown 里用更低效的办法，比如 ASCII 图，或我最爱的：用 unicode 字符估颜色。
只能用 Markdown 时，调色板长什么样。
视觉清晰与易读性
Claude 能啃更复杂的工作，写的规格和计划也越来越大。我发现自己通常读不完超过 100 行的 Markdown，更别指望组织里别人会读。
但 HTML 文档好读得多：Claude 可用标签页、插图和链接把结构排成适合浏览的样子，甚至做移动端响应，按你的设备形态换读法。
易分享
Markdown 不太好分享——多数浏览器原生渲染一般，往往只能当邮件或消息附件。
只要把 HTML 上传，就可以 轻松分享链接。同事随便打开、随时引用。
规格、报告或 PR 说明写成 HTML，被人真正读完的概率高很多。
双向交互
HTML 还能让你 与文档交互；例如让它加滑块或旋钮调设计，或改算法里不同选项看效果。也可以让它把这些改动复制成提示词，贴回 Claude Code。
有用时，可以为手头具体问题做出专用编辑环境。
数据摄入
用 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 文件」或「做个 HTML artifact」即可。关键是清楚 artifact 要做什么、你会怎么用。长期可为重复模式 做成 Skill；一开始从零提示，是感受不同场景的好办法。
使用场景
为更具体，下面是一些我认为 HTML 比 Markdown 更合适的 示例场景。也可对照 GitHub 上的用例画廊：这里。
规格、规划与探索
HTML 是 Claude 深入问题的丰富画布。开工时，我不再指望一份简单 Markdown 计划，而是做出一网 HTML 文件。例如先让 Claude Code 头脑风暴、探索不同选项；再让它展开其中之一，也许做 mockup 或接口示例；感觉不错后再写实现计划。计划满意后开新会话，把这些文件一并交给它实现。
验证时也会让 verification Agent 读入这些文件，从而拿到更广的上下文。
探索：同一页并排几种做法与权衡。
示例提示词：
- 入门屏方向还没定。生成 6 种明显不同的方案——布局、语气、密度都要拉开——做成单个 HTML 网格，方便并排比较。每种标上它在做的权衡。
- 用 HTML 文件写一份详尽实现计划，务必做一些 mockup，展示数据流，并加上我可能想审的关键代码片段。要易读、易消化。
适用于：
- 探索代码里其他实现方式
- 一次试验多种视觉设计
代码审查与理解
Markdown 里读代码费劲；HTML 可以渲染 diff、批注、流程图和模块。用 HTML 理解 Agent 写的代码、做代码审查，或向审你代码的人解释 PR。
代码审查：diff 配上按严重程度标记的边注。
示例提示词：
帮我审查这个 PR，做一份描述它的 HTML artifact。我对 streaming/backpressure 逻辑不太熟，重点放这里。渲染真实 diff，行内边注，按严重程度给发现上色，以及任何能把概念讲清楚的东西。
适用于：
- 写 PR
- 审 PR
- 理解代码里某个主题
设计与原型
Claude Design 基于 HTML，因为 HTML 对设计极有表达力——即便最终界面不是 HTML。Claude 可先用 HTML 草绘，再写成你选的语言，如 React、Swift 等。
也可原型化交互动画、动作等。可让 Claude 做滑块、旋钮等，精确调到你要的效果。
设计：token 与组件按真实样子渲染。
示例提示词：
想原型化一个新结账按钮：点击后播放动画，再迅速变紫。做个带若干滑块和选项的 HTML，让我试不同动画参数，并给一个复制按钮，复制效果好的参数。
适用于：
- 做设计系统 artifact
- 调整组件
- 可视化组件库
- 原型动画
报告、研究与学习
Claude Code 很擅长跨多数据源综合信息，并转成易读报告。可提示它搜 Slack、代码库、git 历史或互联网，生成易读报告。
可以是长 HTML 文档、交互式讲解，甚至幻灯片/deck。可让 Claude 用 SVG 画图帮助可视化。
报告：带导航、可折叠步骤和标签页片段的讲解页。
示例提示词：
我不懂我们的速率限制器到底怎么工作。读相关代码，做一页 HTML 讲解：token-bucket 流程的图、3–4 段带批注的关键代码片段，底部一个「坑」小节。为只读一遍的人优化。
适用于：
- 写功能摘要
- 生成讲解
- 起草周报
- 做事故报告
- 产出 SVG 插图、流程图、技术图示
定制编辑界面
有时纯文本框很难说清你要什么。这时我常让 Claude 为手头这件事做一个一次性编辑器：不是产品，也不是可复用工具，而是为这一份数据特制的单个 HTML 文件。
诀窍是结尾一定要有导出：「复制为 JSON」或「复制为提示词」按钮，把我在 UI 里做的事变回可贴进 Claude Code 或提交进文件的东西。你仍在环里，但环紧得多。
示例提示词：
- 要把这 30 个 Linear ticket 重新排优先级。做个 HTML，每个 ticket 是可拖卡片，跨 Now / Next / Later / Cut 列。先按你的最佳猜测预排。加「复制为 Markdown」按钮，导出最终排序，每桶一行理由。
- 这是我们的 feature flag 配置。做个表单编辑器，按领域分组，显示依赖，若启用某 flag 而前置未开则警告。加「复制 diff」按钮，只给我改过的键。
- 在调这个系统提示词。做并排编辑器：左边可编辑提示词并高亮变量槽，右边三个样例输入，实时渲染填好的模板。加字符/token 计数和复制按钮。
适用于：
- 重排、分流或分桶任何东西（ticket、测试用例、反馈）
- 编辑结构化配置（feature flag、环境变量、带约束的 JSON/YAML）
- 带着实时预览调提示词、模板或文案
- 策展数据集——批准/拒绝行、打标签、导出选集
- 批注文档、transcript 或 diff，并导出批注
- 选文本里难表达的值：颜色、缓动曲线、裁剪区域、cron、正则
常见问题
下面是关于用 Claude Code 写 HTML 我被问得最多的，配上日常落地的习惯：
不是更低效吗？
Markdown 往往用更少 token，但 HTML 的表达力，加上我真去读的概率高得多，总体产出更好。有了 Opus 4.7 的 1MM 上下文窗口，多出来的 token 在窗口里几乎感觉不到。
现在什么时候还用 Markdown？
老实说几乎一切都不用 Markdown 了，但我大概站在 HTML 极端派那一头。
这就是你替代规划的方式吗？
我发现不再是一份单一计划，而是计划不同部分/阶段各有几份 HTML。例如实现计划一份，UI 探索另一份，最后再做一个列出每种设计的 HTML 组件。这些文件我会留着当日后引用，也用于验证。
与 Claude 保持在环
以上归根结底：我用 HTML 而不是 Markdown，是因为它让我更觉得和 Claude 在环。Claude 承担得越多，我越发现自己审计划不那么仔细了，想找一种方式继续参与它的选择，而不是一交了之。HTML 正好是那个方式。我现在比以前更在环。
开始使用 Claude Code。
本文作者 Thariq Shihipar，Anthropic Member of Technical Staff；文中观点与对 Claude Code 使用 HTML 的偏好均为个人意见。