别写 Markdown 了，用 HTML【译】

TRANSLATION

本文作者 Thariq 是 Anthropic Claude Code 团队的工程师，原文标题 Using Claude Code: The Unreasonable Effectiveness of HTML

本文中，他建议把输出从 Markdown 换成了 HTML，以及怎么用

Thariq Shihipar

Claude Code 工程师 · Anthropic Technical Staff · @trq212

Anthropic Claude Code 团队的核心工程师，Claude Code 几乎所有重大功能更新都由他在 X 上首发。之前是 YC W20 创始人（游戏公司，融了 1700 万美元），MIT Media Lab 出身。

用 Claude 写 HTML，效果很好

Markdown 一直是 Agent 跟我们沟通时最常用的文件格式。简单，跨平台，有一定的富文本能力，而且方便你手动编辑。Claude 甚至学会了在 Markdown 里用 ASCII 画图，画得还挺像样

但随着 Agent 变得越来越强，我越来越觉得 Markdown 是一种限制。超过一百行的 Markdown 文件我基本读不下去。我想要更丰富的可视化，想要颜色和图表，想要方便地分享给别人

而且我越来越不自己编辑这些文件了。我更多是把它们当 spec、参考资料、头脑风暴的产出物来用。真要改的时候，也是让 Claude 来改，这让 Markdown 最大的优势「人好编辑」基本失效了

我已经开始用 HTML 取代 Markdown 作为输出格式，Claude Code 团队里越来越多人也在这么做。下面说说为什么

（如果你想先看一些示例，可以去 thariqs.github.io/html-effectiveness 看，但记得回来读完为什么这么做）

为什么是 HTML 信息密度

HTML 能承载的信息比 Markdown 丰富得多。除了基本的文档结构（标题、格式化），它还能表达各种其他类型的信息：

●表格数据（用 table）

●设计数据（用 CSS）

●插图（用 SVG）

●代码片段（用 script 标签）

●交互元素（用 HTML + JavaScript + CSS）

●工作流程图（用 SVG 和 HTML）

●空间数据（用绝对定位和 canvas）

●图片（用 img 标签）

我甚至会说，几乎没有什么信息是 Claude 能读懂但 HTML 表达不了的。这让 HTML 成为一种极其高效的方式，让模型把深度信息传达给你，也让你能高效地审阅

我发现如果不让模型用 HTML，它就会在 Markdown 里做一些很勉强的事，比如画 ASCII 图。我最喜欢的一个例子是，它试图用 Unicode 字符来「估算」颜色，就像下面这张 Claude Code 的截图

Claude Code 在 Markdown 里试图表达颜色

视觉清晰度和可读性

随着 Claude 能做的事情越来越复杂，它写出来的 spec 和方案也越来越长。实际使用中，超过 100 行的 Markdown 文件我基本不会真的去读，更别说让团队里其他人读了

但 HTML 文档好读得多。Claude 可以用 tab 分组、用插图辅助、加链接导航，把结构组织得更容易浏览。它甚至可以做成响应式的，让你在不同设备上以不同的方式阅读

方便分享

Markdown 文件很难分享，因为大部分浏览器不能原生渲染它。你通常得把它作为附件加到邮件或消息里

用 HTML 的话，只要你把文件上传到某个地方（比如 S3），就可以轻松分享链接。同事在哪都能打开，随时引用

一个 spec、报告或 PR 说明真正被人读到的概率，HTML 比 Markdown 高得多

双向交互

HTML 可以让你跟文档互动。比如你可以让它加滑块或旋钮来调整设计参数，或者让你调整算法的不同选项来看效果。你还可以让它加一个按钮，把你的调整复制成 prompt，粘贴回 Claude Code

更多关于双向交互的例子，可以看我之前关于 playground 的帖子：x.com/trq212/status/2017024445244924382

数据摄入能力

为什么要用 Claude Code 来生成 HTML，而不用 Claude.ai 或 Claude Design？最大的原因是 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 文件。你可以在这里看到所有的：thariqs.github.io/html-effectiveness，下面是分类概述

Spec、规划和探索

HTML 是一块很好的画布，让 Claude 深入探索一个问题。我现在开始做一个问题的时候，不再写一份简单的 Markdown 方案，而是会生成一组 HTML 文件。比如我可能先让 Claude Code 做头脑风暴，对不同选项做几个探索。然后让它深入展开其中一个，做 mockup 或代码片段。满意了再让它写实施方案。方案确定后，我开一个新 session，把所有这些文件传进去让它实施

做验证的时候，我也会让验证 Agent 读入这些文件，这样它对需求的上下文理解会宽广得多

示例 Prompt：

I'm not sure what direction to take the onboarding screen. Generate 6 distinctly different approaches — vary layout, tone, and density — and lay them out as a single HTML file in a grid so I can compare them side by side. Label each with the tradeoff it's making.

Create a thorough implementation plan in a HTML file, be sure to make some mockups, show data flow and add important code snippets I might want to review. Make it easy to read and digest.

适用场景：

●探索代码的不同实现方式

●探索多种视觉设计方案

代码审查和理解

代码在 Markdown 文件里很难读。但用 HTML 我们可以渲染 diff、加注释标注、画流程图、展示模块关系。用这个来理解 Agent 写的代码、做代码审查、或者给审查你代码的人做解释。我发现这通常比 GitHub 默认的 diff 视图好用，我现在每个 PR 都会附一个 HTML 代码解释文件

示例 Prompt：

Help me review this PR by creating an HTML artifact that describes it. I'm not very familiar with the streaming/backpressure logic so focus on that. Render the actual diff with inline margin annotations, color-code findings by severity and whatever else might be needed to convey the concept well.

适用场景：

●创建 PR

●审查 PR

●理解代码中的某个主题

设计和原型

Claude Design 就是基于 HTML 的，因为 HTML 在设计表达上极其强大，即使你最终的目标平台不是 HTML。Claude 可以先用 HTML 画出设计稿，然后再转写成你要的语言，React、Swift 都行

你还可以做交互原型，比如动画、操作等。考虑让 Claude 做滑块、旋钮之类的控件，让你精确调出你想要的效果

示例 Prompt：

I want to prototype a new checkout button, when clicked it does a play animation and then turns purple quickly. Create a HTML file with several sliders and options for me to try different options on this animation, give me a copy button to copy the parameters that worked well.

适用场景：

●创建设计系统产物

●调整组件

●可视化组件库

●制作原型动画

报告、研究和学习

Claude Code 非常擅长从多个数据源综合信息，转化成可读性很高的报告。你可以让 Claude 搜你的 Slack、代码库、Git 历史、互联网等，然后生成极其易读的报告，给自己看、给领导看、给团队看

形式可以是一个长 HTML 文档、一个交互式解释器，甚至是一个幻灯片。让 Claude 用 SVG 画图来辅助可视化

比如我写 prompt caching 那几篇帖子的时候，我让 Claude 先读了 Git 历史中所有跟 prompt caching 相关的改动，然后为我准备了一份深度研究的 HTML 文件来阅读

示例 Prompt：

I don't understand how our rate limiter actually works. Read the relevant code and produce a single HTML explainer page: a diagram of the token-bucket flow, the 3-4 key code snippets annotated, and a "gotchas" section at the bottom. Optimize it for someone reading it once.

适用场景：

●总结一个功能是怎么工作的

●给我解释一个概念

●给老板写周报

●给领导写事故报告

●SVG 插图、流程图、技术图表等

一次性编辑器

有些事情纯用文本框很难描述清楚。这种时候我会让 Claude 给我做一个一次性的编辑器，专门为我当前在做的这件事而设计。不是产品，不是可复用的工具，就是一个 HTML 文件，专门为这一份数据而做

关键是结尾永远要有一个导出：一个「复制为 JSON」或「复制为 prompt」的按钮，把你在 UI 上做的事情变回可以粘贴进 Claude Code 的文本

示例 Prompt：

I need to reprioritize these 30 Linear tickets. Make me an HTML file with each ticket as a draggable card across Now / Next / Later / Cut columns. Pre-sort them by your best guess. Add a "copy as markdown" button that exports the final ordering with a one-line rationale per bucket.

Here's our feature flag config. Build a form-based editor for it, group flags by area, show dependencies between them, warn me if I enable a flag whose prerequisite is off. Add a "copy diff" button that gives me just the changed keys.

I'm tuning this system prompt. Make a side-by-side editor: editable prompt on the left with the variable slots highlighted, three sample inputs on the right that re-render the filled template live. Add a character/token counter and a copy button.

适用场景：

●重新排序、分类、分桶任何东西（工单、测试用例、用户反馈）

●编辑结构化配置（feature flag、环境变量、有约束的 JSON/YAML）

●调 prompt、模板或文案，带实时预览

●整理数据集，逐行批准/拒绝，打标签，导出选择结果

●标注文档、转录稿或 diff，导出标注

●选择那些用文字很难表达的值：颜色、缓动曲线、裁剪区域、cron 表达式、正则

常见问题

我跟很多人聊过我换 HTML 的事，看到了几个反复出现的问题

HTML 不是更费 token 吗？确实 Markdown 通常用的 token 更少，但 HTML 表达能力更强，而且我真的会去读，所以整体产出质量更好。Opus 4.7 的 100 万 token 上下文窗口下，多出来的 token 消耗几乎感知不到

Markdown 现在还用吗？说实话我几乎已经完全停用 Markdown 了，但我大概是属于 HTML 极端派那边的

怎么查看 HTML 文件？我一般就在本地浏览器打开（你可以让 Claude 帮你打开），如果要分享就传到 S3 上

生成不是更慢吗？确实更慢。HTML 的生成时间大概是 Markdown 的 2-4 倍，但我觉得结果值得

版本控制怎么办？说实话这是 HTML 最大的短板。HTML 的 diff 噪音很大，review 起来比 Markdown 难很多

怎么让 Claude 符合我的审美 / 别做得太丑？frontend design 插件能帮 Claude 做出好看的 HTML 文件。如果要匹配你公司的风格，可以让 Claude 读你的代码库，生成一个设计系统 HTML 文件，然后用那个文件作为其他 HTML 输出的样式参考

保持在 Loop 里

以上所有这些，归根到底，我觉得我用 HTML 的真正原因是：我重新感觉到自己在 loop 里了

之前我开始担心，因为我不再深入阅读方案了，我只能放手让 Claude 自己做决策

但我很高兴地说，用了 HTML 之后，我感觉自己比以前任何时候都更在 loop 里。希望你也一样

原文链接：x.com/trq212/article/2052809885763747935

示例集合：thariqs.github.io/html-effectiveness