使用 Claude 代码：HTML 的非凡效能
Markdown 已成为智能体与我们沟通时所采用的主流文件格式。它简洁、可移植，具备一定的富文本能力，并且便于用户自行编辑。Claude 甚至出人意料地擅长在 Markdown 文件中利用 ASCII 字符绘制图表。
然而，随着智能体的能力日益增强，我愈发感到 Markdown 已成为一种限制性格式。我发现，超过百行的 Markdown 文件便难以阅读。我渴望更丰富的可视化效果——色彩、图表，并希望轻松分享这些内容。
此外，我越来越少亲自编辑这些文件，而是将其用作规范文档、参考资料、头脑风暴产出等。即便需要修改，我也通常通过提示 Claude 来完成编辑，这实际上削弱了 Markdown 最大的优势之一。
因此，我开始倾向于使用 HTML 作为输出格式，而非 Markdown。我注意到 Claude Code 团队中的其他人也越来越多地采用这种方式。原因如下：
（若想先看一些示例，可访问：https://thariqs.github.io/html-effectiveness，但请务必返回继续阅读背后的原因。）
为何选择 HTML？
信息密度
与 Markdown 相比，HTML 能够传达丰富得多的信息。它不仅能实现标题、格式等基础文档结构，还能呈现各类其他信息，例如：
- 使用表格呈现表格数据
- 利用 CSS 表达设计数据
- 借助 SVG 绘制插图
- 通过 script 标签嵌入代码片段
- 结合 JavaScript 与 CSS 实现交互式 HTML 元素
- 运用 SVG 与 HTML 描述工作流程
- 通过绝对定位和 canvas 展示空间数据
- 使用 image 标签嵌入图片
我甚至可以说，Claude 能够读取的几乎所有信息，几乎都能以相当高效的方式用 HTML 表达出来。这使得 HTML 成为模型向你传递深度信息、以及你进行审阅的高效媒介。
当无法使用 HTML 时，模型在 Markdown 中往往会采取效率较低的方式，比如 ASCII 图表，或者我最喜欢的一种方式——用 Unicode 字符估算颜色，正如这张来自 Claude Code 的截图所示。
Claude Code 尝试在 Markdown 中展示颜色
视觉清晰度与易读性
随着 Claude 能够处理愈发复杂的工作，其生成的规范与计划文档也越来越大。实践中，我发现自己的阅读耐心通常不超过百行的 Markdown 文件，更不用说让组织中的其他人去阅读了。
而 HTML 文档则要容易阅读得多。Claude 可以通过标签、插图、链接等方式对文档结构进行视觉优化，使其更易于浏览。HTML 甚至可以做到响应式设计，让你根据不同的设备形态获得最佳阅读体验。
便捷分享
Markdown 文件其实相当难以分享，因为大多数浏览器并不能很好地原生渲染它们。你通常不得不将 Markdown 文件作为邮件或消息的附件发送。
而使用 HTML，只要将文件上传（例如上传到 S3），就可以轻松分享链接。你的同事可以在任何地方打开它，并方便地引用内容。
如果你的规范文档、报告或 PR 说明是以 HTML 形式呈现，他人真正去阅读它的可能性会大大提升。
双向交互
HTML 还能让你与文档进行互动。例如，你可以要求在页面中加入滑块或旋钮，用以调整设计方案；或者允许你微调算法中的不同参数，实时观察效果变化。你甚至可以要求它提供一个功能，将这些修改后的配置一键复制为提示词，再粘贴回 Claude Code 中继续使用。
关于这种双向交互的更多示例，请参阅我的“Playgrounds”帖子：https://x.com/trq212/status/2017024445244924382
数据摄入能力
为什么选择用 Claude Code 生成 HTML 文件，而不是用 ClaudeAI 或 Claude Design？其中一个最重要的原因，是 Claude Code 能够摄入大量上下文信息。
举个例子，在撰写本文时，我让 Claude Code 扫描了我的代码目录，找出所有我生成过的 HTML 文件，对它们进行分组和分类，然后创建一个新的 HTML 文件，其中包含代表每种类别的图表。你在本文中看到的那些图表，正是这一过程的直接成果。
除了文件系统，Claude Code 还能通过你的 MCP（如 Slack、Linear 等）、浏览器（配合 Chrome 中的 Claude 插件）、Git 历史记录等渠道获取额外上下文。
这令人愉悦
用 Claude 制作 HTML 文档就是更有趣，让我在创作过程中感到更深的参与感和投入感——仅凭这一点，就已足够。
如何开始？
我有点担心读者看完这篇文章后，会把它变成某种固定的 “/html 技能” 模板。虽然这么做或许有些价值，但我必须强调：你其实不需要做太多，就能让 Claude 为你生成 HTML。你只需简单地说：“生成一个 HTML 文件” 或 “创建一个 HTML 成果物（artifact）” 即可。
关键在于，你要清楚自己希望这个成果物实现什么功能、如何使用它。随着时间推移，你可能会发展出一套专属技能，但目前我建议你从零开始直接写提示词，逐步掌握在不同场景下如何有效运用它。
应用案例
为了更具体地说明，我已针对多种用途创建了大量不同的 HTML 文件。你可以在 https://thariqs.github.io/html-effectiveness/ 浏览全部示例，以下是一个概览：
规范制定、规划与探索
HTML 为 Claude 提供了一个丰富的画布，使其能深入探究问题。当我着手解决某个问题时，我不再满足于一份简单的 Markdown 计划，而是期望构建一个由多个 HTML 文件组成的网络。例如，我可能会先让 Claude Code 进行头脑风暴，生成若干种不同方案的探索性原型；接着，我会让它对其中一种方案深入展开，制作界面草图或代码片段；最后，当我对方向感到满意时，我会要求它撰写一份完整的实施方案。一旦我对方案认可，就会开启一个新会话，并将所有这些 HTML 文件一并传入，让 Claude 执行具体实现。
在验证阶段，我也会让验证智能体读取这些文件，从而获得更全面的上下文，准确理解所需实现的内容。
示例提示词：
- “我不确定引导页该采用什么方向。请生成 6 种截然不同的方案——在布局、语气和信息密度上有所差异——并将它们以网格形式呈现在单个 HTML 文件中，以便我并排比较。每个方案请标注其所做出的权衡。”
- “请在一个 HTML 文件中制定一份详尽的实施方案，务必包含界面草图、数据流图，以及我可能需要审阅的关键代码片段。确保内容易于阅读和消化。”
典型应用场景包括：
- 探索代码实现的其他可能方式
- 探索多种视觉设计方案
代码审查与理解
在 Markdown 文件中阅读代码往往颇为困难。而借助 HTML，我们可以渲染代码差异（diffs）、添加注解、绘制流程图、展示模块结构等。你可以利用这些能力来理解智能体所编写的代码、进行代码审查，或向他人解释你的 PR 内容。我发现这种方式通常比 GitHub 默认的 diff 视图效果更好——如今，我提交的每个 PR 都会附带一个 HTML 格式的代码解析文档。
示例提示词：
“请帮我审查这个 PR，创建一个 HTML 成果物来描述它。我对流式处理（streaming）和背压（backpressure）逻辑不太熟悉，请重点聚焦这部分。请渲染实际的代码差异，并在行间边距处添加注解；按严重程度对问题进行颜色编码；并采用其他任何有助于清晰传达概念的方式。”
典型应用场景：
- 创建 PR
- 审查 PR
- 理解代码中的特定主题
设计与原型
Claude Design 之所以基于 HTML，正是因为 HTML 在表达设计方面具有非凡的表现力——即便你最终的交付界面并非 HTML。Claude 可以先用 HTML 快速勾勒出设计方案，再将其转换为你指定的技术栈，无论是 React、Swift 还是其他语言。
你还可以用 HTML 原型化交互效果，例如动画、用户操作反馈等。不妨尝试让 Claude 添加滑块、旋钮等控件，让你精确调校出理想的效果。
示例提示词：
“我想为一个新的结算按钮制作原型：点击时播放一段动画，随后迅速变为紫色。请创建一个 HTML 文件，其中包含多个滑块和选项，让我可以尝试不同的动画参数，并提供一个‘复制’按钮，方便我复制效果最佳的参数配置。”
适用场景包括：
- 创建设计系统成果物
- 调整 UI 组件
- 可视化组件库
- 原型化富有愉悦感的动画效果
报告、研究与学习
Claude Code 在跨多个数据源整合信息并将其转化为高可读性报告方面表现极为出色。你可以提示 Claude 搜索你的 Slack 消息、代码库、Git 历史、互联网内容等，生成面向你自己、团队或管理层的清晰易读的报告。
你可以将这类成果组织成长篇 HTML 文档、交互式讲解页面，甚至幻灯片（slideshow/deck）。不妨要求 Claude 使用 SVG 绘制图表，以更直观地呈现复杂概念。
例如，在撰写关于“提示缓存”（prompt caching）的系列文章时，我让 Claude 读取我们的 Git 提交历史，然后为我生成了一份详尽的 HTML 研究文档，汇总了所有与提示缓存相关的变更。
示例提示词：
“我不太理解我们当前的限流器（rate limiter）究竟是如何工作的。请阅读相关代码，并生成一个单独的 HTML 解析页面：包含令牌桶（token-bucket）流程图、3–4 段关键代码片段（附带注解），以及底部的‘常见陷阱’（gotchas）部分。请针对‘只读一次’的读者进行优化。”
适用场景包括：
- 总结某项功能的工作原理
- 向自己解释某个技术概念
- 向上级提交每周工作进展报告
- 向管理层提交事故复盘报告
- 制作 SVG 插图、流程图、技术示意图等
自定义编辑界面
有时，仅靠文本框很难准确描述你想要的效果。在这种情况下，我会让 Claude 为我正在处理的具体任务临时构建一个“一次性”编辑器——不是产品，也不是可复用的工具，而是一个专为此数据量身定制的单 HTML 文件。
关键技巧始终是：在界面末尾提供导出功能，例如“复制为 JSON”或“复制为提示词”按钮，将我在 UI 中所做的操作重新转换成可粘贴回 Claude Code 的文本格式。
示例提示词：
- “我需要重新排定这 30 个 Linear 工单的优先级。请创建一个 HTML 文件，每个工单显示为一张可拖拽卡片，分布在 ‘Now / Next / Later / Cut’ 四列中。请先按你的最佳判断预排序，并添加一个‘复制为 Markdown’按钮，导出最终排序结果，并为每个分组附上一行简要理由。”
- “这是我们的功能开关（feature flag）配置。请为其构建一个表单式编辑器：按模块对开关分组，显示它们之间的依赖关系；如果我启用了某个前置条件未开启的开关，请发出警告。再加一个‘复制差异’（copy diff）按钮，仅输出被修改的键。”
- “我正在调整这个系统提示词。请做一个左右分栏编辑器：左侧是可编辑的提示词，其中变量占位符高亮显示；右侧展示三个示例输入，并实时渲染填充后的模板。同时加上字符/Token 计数器和复制按钮。”
适用场景包括：
- 对任何内容进行重排序、优先级划分或分组（如工单、测试用例、用户反馈）
- 编辑结构化配置（如功能开关、环境变量、带约束的 JSON/YAML）
- 调优提示词、模板或文案，并支持实时预览
- 整理数据集：批准/拒绝行、标注示例、导出所选内容
- 对文档、转录稿或代码差异进行标注，并导出注释
- 选取那些用纯文本难以表达的值：颜色、缓动曲线（easing curves）、裁剪区域、Cron 表达式、正则表达式等
常见问题解答（FAQ）
我已向许多人分享过自己转向 HTML 的做法，也反复听到一些相似的问题：
HTML 不是更耗费 token 吗？
虽然 Markdown 通常使用的 token 更少，但我发现 HTML 带来的表达力提升，以及我实际阅读它的概率大幅提高，使得整体产出质量更优。在 Opus 4.7 拥有 100 万 token 上下文窗口的情况下，HTML 所增加的 token 消耗在上下文中几乎可以忽略不计。
你现在还在什么情况下使用 Markdown？
老实说，我几乎已经完全不再使用 Markdown 了——不过我可能确实站在了“HTML 极端主义”的一端。
如何查看 HTML 文件？
我通常直接在本地浏览器中打开（你也可以让 Claude 帮你打开），或者上传到 S3 以获取可分享的链接。
生成 HTML 不是比 Markdown 花更长时间吗？
确实如此！HTML 的生成时间通常是 Markdown 的 2 到 4 倍，但我认为其成果完全值得这份等待。
那版本控制怎么办？
这确实是 HTML 最大的缺点之一：与 Markdown 相比，HTML 的 diff 噪音大、难以审查。
怎样让 Claude 生成符合我审美的 HTML，而不是做出难看的设计？
前端设计插件（frontend design plugin）能帮助 Claude 生成更美观的 HTML 文件。若要匹配你所在公司的设计风格，你可以让 Claude 扫描你的代码库，生成一份专属的“设计系统 HTML 文件”。之后，你就可以将该文件作为参考模板，用于指导其他 HTML 成果物的样式。
保持同步（Stay in the Loop）
以上种种归结为一点：我认为我之所以使用 HTML，真正原因在于——它让我感觉自己与 Claude 的协作更加紧密、更加“在环”（in the loop）。我曾一度担心，由于我不再深入阅读那些冗长的计划文档，最终只能放手让 Claude 自行做决定。
但令我欣喜的是，如今使用 HTML 反而让我比以往任何时候都更深度地参与其中。希望你也能有同样的体验。
