Using Claude¶
📊 Level ⭐⭐⭐ | 18.4KB
Using Claude Code: The unreasonable effectiveness of HTML¶
来源：原文存档
概述¶
HTML Artifacts 是 Claude Code 中一种强大的输出形式，它使 Agent 能够生成富交互式的 HTML 文档，显著超越传统 Markdown 的表达能力。
为什么选择 HTML 而非 Markdown¶
传统的 Markdown 在处理复杂信息时存在明显局限——它只能表达简单的文档结构（标题、列表、代码块），而无法承载更丰富的信息形态。相比之下，HTML 可以：
- 使用
<table>表达结构化数据 - 使用 CSS 描述设计规范
- 使用 SVG 绘制插图和图表
- 使用
<script>嵌入代码片段 - 结合 JavaScript + CSS 实现交互组件
- 使用 SVG + HTML 描述工作流
- 使用绝对定位和 Canvas 处理空间数据
- 使用
<img>标签嵌入图像
这种信息密度使 Claude 能够高效地向用户传达深度信息。在无法使用 HTML 的场景下，模型往往被迫采用低效的 Markdown 变通方案，如 ASCII 图表或使用 Unicode 字符估算颜色。
核心优势¶
信息密度¶
HTML 的表达能力几乎涵盖了 Claude 能够读取的所有信息类型，这使其成为模型与用户之间高效沟通的媒介。
视觉清晰度与可读性¶
随着 Claude Code 处理的任务复杂度提升，它生成的规格文档和计划也越来越大。研究表明，审阅者通常不会仔细阅读超过 100 行的 Markdown 文件。
HTML 文档则不同——Claude 可以通过以下方式优化视觉组织：
- 使用 Tabs 组织结构化内容
- 嵌入 SVG 插图辅助理解
- 添加内部链接便于导航
- 实现移动端响应式布局
易于分享¶
Markdown 文件在浏览器中通常无法原生渲染，需要作为附件发送。而 HTML 文件可以直接上传分享，同事可以在任何环境下轻松打开和引用。这大大提升了技术文档、PR 描述和报告的实际阅读率。
双向交互¶
HTML 文档支持用户与 Claude 创建的内容进行交互。例如，可以要求 Claude 添加滑块或旋钮来调整设计参数，或允许用户调整算法选项并实时预览效果。
这种交互能力使用户能够：
- 创建针对特定问题的编辑环境
- 通过 UI 调整参数并复制回 prompt
- 实现比纯文本更精确的需求表达
数据摄取¶
Claude Code 相比 Claude.ai 或 Claude Design 的最大优势之一是其强大的上下文摄取能力。在撰写本文时，作者让 Claude Code 扫描整个代码目录，查找所有生成的 HTML 文件，按类型分组，然后生成包含每种类型图表的 HTML 文件。
此外，Claude Code 还可以通过 MCP（如 Slack、Linear 等）、浏览器插件和 Git 历史来获取额外上下文。
快速上手¶
使用 Claude Code 生成 HTML Artifacts 非常简单——只需提示它"创建一个 HTML 文件"或"创建一个 HTML Artifact"。关键在于明确 Artifact 的用途和预期使用方式。
典型使用场景¶
规格文档、规划与探索¶
HTML 为 Claude 提供了一个丰富的画布来处理复杂问题。对于一个问题的处理流程，作者倾向于创建一个由多个 HTML 文件组成的网络，而非简单的 Markdown 计划。典型工作流包括：
- 让 Claude Code 头脑风暴并创建不同选项的探索文件
- 选择一个方向扩展，生成 Mockup 或接口示例
- 编写详细的实现计划
- 开启新会话时传入所有文件供实现使用
验证阶段同样可以让 Agent 读取这些文件，获得更全面的上下文。
适用场景：
- 代码实现的多种方式探索
- 多视觉设计方案的并行比较
代码审查与理解¶
在 Markdown 中代码难以阅读，但 HTML 可以渲染 Diff、注释注释、流程图和模块图。这使得：
- Agent 编写的代码更容易审查
- PR 的评审流程更高效
- 复杂的代码逻辑更容易解释给他人
设计与原型¶
Claude Design 基于 HTML 构建，因为 HTML 在设计表达上极为强大——即使最终输出不是 HTML。Claude 可以先用 HTML 草绘设计，然后用 React、Swift 等语言实现。
还可以原型化交互效果（如动画、动作），并通过滑块、旋钮等控件进行调优。
适用场景：
- 创建设计系统 Artifact
- 调整 UI 组件参数
- 可视化组件库
- 原型化动画效果
报告、研究与学习¶
Claude Code 善于跨多个数据源综合信息并转换为可读报告。可以指示 Claude 搜索 Slack、代码库、Git 历史或互联网，生成易读的 HTML 文档、交互式解释器或幻灯片。
适用场景：
- 编写功能摘要
- 生成技术解释文档
- 起草周报
- 编写事故报告
- 生成 SVG 插图、流程图和技术图表
自定义编辑界面¶
当难以用纯文本框描述需求时，可以要求 Claude 为当前工作构建一个专用的单次性编辑器——不是产品或可重用工具，而是一个为特定数据构建的单 HTML 文件。
关键技巧是最后添加导出功能——"复制为 JSON"或"复制为 Prompt"按钮，将 UI 中的操作转换回可粘贴到 Claude Code 的内容。
适用场景：
- 对任何事物进行排序、分类或分组（工单、测试用例、反馈）
- 编辑有约束条件的结构化配置（Feature Flags、环境变量、JSON/YAML）
- 调优 Prompt、模板或文案并实时预览
- 策划数据集——批准/拒绝行、标记示例、导出选择
- 标注文档、转录或 Diff 并导出注释
- 选择文本难以表达的值：颜色、缓动曲线、裁剪区域、Cron 表达式、正则表达式
常见问题¶
HTML 是否效率更低？¶
虽然 HTML 确实使用更多 Token，但 HTML 增强的表达能力和文档被阅读的可能性大幅提升整体产出质量。考虑到 Opus 4.7 拥有 100 万 Token 的上下文窗口，额外 Token 消耗几乎可以忽略不计。
何时仍使用 Markdown？¶
作者坦言自己已几乎完全停止使用 Markdown，但坦承自己可能属于"HTML 最大化主义者"。
HTML 是否替代了规划？¶
作者发现，相比单一计划，他更倾向于为项目的不同部分/阶段维护多个 HTML 文件。例如，可能有一个 HTML 实现计划，另一个用于 UI 探索，最后一个列出所有设计的 HTML 组件。这些文件既是未来的参考，也在验证阶段发挥作用。
核心价值：保持参与感¶
作者使用 HTML 而非 Markdown 的根本原因在于，它帮助他保持与 Claude 决策过程的参与感。随着 Claude 承担更多任务，作者发现自己越来越少仔细阅读计划——他希望有一种方式让自己持续参与 Claude 的选择，而非简单地将任务交接。HTML 正是这样的工具。
"I feel more in the loop now than I ever did before."
→ 原文存档
相关概念¶
- Claude Code 最佳实践 — 相关实践指南
- 原文存档 — 原始来源
深度分析¶
这篇文章揭示了 AI Agent 交互范式中的一个深刻转变：从「文档输出」到「交互界面」的概念跃迁。作者的核心论点「HTML 比 Markdown 更高效」并非关于格式偏好的主观选择，而是对 AI 与人类协作中「信息密度」问题的精准回应。当 Claude 能够生成的内容远超人类愿意阅读的范围时，如何让人类重新回到决策循环中——这才是 HTML 作为 Artifact 媒介的真正价值所在。它不是炫技，而是解决「Agent 能力越强、人类越被边缘化」这个结构性问题的有效路径。理解这一点，才能理解为什么作者说「感觉自己比以往任何时候都更在循环中」。
Markdown 在 AI 输出场景中的根本局限在于它是「被动消费」型媒介——它能承载信息，但无法创造反馈回路。当一个 PRD 文档、一份技术方案、或一份代码审查报告以 Markdown 交付时，人类的角色在「阅读」这个动作完成后就结束了。而 HTML 的交互能力——滑块、旋钮、可编辑字段、实时预览——将人类从纯阅读者转变为可调节参数的参与者。这意味着需求澄清不再发生在「你写的我不明白，请重写」的多轮低效对话中，而是发生在「你构建了一个可操作的界面，我在上面调参数并即时看到结果」的一次性高效交互中。数据摄取场景下让 Claude 扫描代码库后生成 HTML 这个例子很好地说明了这一点——一次性生成图表，比多轮文字描述高效得多。
「Token 效率 vs. 阅读率」的权衡是一个被大多数技术读者低估的决策变量。Markdown 倡导者通常以 Token 节约为由反对 HTML，但这个逻辑忽略了「写出没人读的内容 = 零产出」这个基本现实。作者的核心论点是：HTML 消耗更多 Token，但文档被实际阅读和使用的概率大幅提升，在 100 万 Token 上下文的背景下，这个 Trade-off 对 HTML 有利。这对于所有需要用 AI 辅助生成正式文档的知识工作者都是一个重要提醒——你的目标不是最小化 Token 消耗，而是最大化文档的最终价值产出。
多文件 HTML 网络而非单一 Markdown 计划的用法，揭示了一种新兴的 AI 辅助工作的架构思维。传统的「一个计划文档」模型假设信息是静态的、一次性传递的、后续不依赖的。但复杂项目的现实是：不同阶段需要不同类型的信息（技术约束、设计审美、进度节点），而且这些信息之间存在引用和验证关系。作者维护多个 HTML 文件（实现计划、UI 探索、设计组件清单）并在验证阶段让 Agent 读取所有文件，正是利用了 Claude Code 的强上下文能力来构建「持久化的工作记忆」。这比每次新会话都从头构建上下文、或依赖文字描述来传递复杂关系要高效得多。
从更宏观的视角看，HTML Artifacts 的兴起预示着「Agent as Co-Worker」时代的工作流重构方向。当 AI 能够生成任意复杂度的交互界面时，人类与 AI 之间的协作不再遵循传统的「人写文档 → AI 执行」的单向模式，而是演变为「AI 构建工作台 → 人在工作台上调整参数 → 人给 AI 新任务 → AI 更新工作台」的持续互动循环。这种模式对于需要持续迭代的创造性工作（产品设计、架构探索、代码审查）特别有意义——它让 AI 的规划能力与人类的设计直觉在同一个可视化空间中协同作用，而不是在抽象的文字描述中各自为战。
实践启示¶
当需求表达在纯文本中变得低效时——比如涉及空间布局、颜色调优、参数组合对比、或复杂结构化配置——应该立即转向要求 HTML Artifact 而非继续在 Markdown 中艰难沟通。 判断标准很简单：如果在纯文本描述中你需要写「请看第三段的表格中第三行那个蓝色的按钮」这样的定位描述，说明你已经遇到了 HTML 可以自然解决的表达瓶颈。主动切换到 HTML 能节省大量来回澄清的低效对话时间。
在代码审查场景中，要求 Claude 生成带渲染 Diff 和注释的 HTML 而非纯文字 Diff。 传统 Diff 在 Markdown 中的呈现方式（+/- 行、难以定位上下文）使评审者难以快速建立对变更的整体认知。HTML 可以实现行内注释、颜色编码严重程度、模块依赖图等增强阅读体验的呈现，让代码评审从「努力读完」变成「高效理解」。这在评审他人代码或解释自己的设计决策时尤其有价值。
利用「可调参数 + 导出按钮」的组合来构建 Prompt 调优工作流。 当你需要反复调整 System Prompt 或模板的措辞时，让 Claude 生成一个左右分屏的 HTML 编辑器：左侧是可编辑的模板（高亮变量槽），右侧是多个样本输入的实时渲染，加上 Token 计数和「复制为 Prompt」按钮。这个工作流比在 Chat 界面中反复粘贴修改要高效得多，特别适合需要精细调优 Prompt 的生产场景。
将 Claude Code 的多会话协作视为「构建持久化知识库」而非「一次性任务执行」。 作者的多 HTML 文件工作流（实现计划、UI 探索、设计组件清单）实际上构建了一个可被后续会话重用的结构化知识库。每次开启新会话时，将这些文件作为上下文传入，Claude 就能获得比任何文字描述更完整准确的项目状态认知。建议对重要项目建立这种「HTML 知识文件」而非每次从零描述项目背景。
对于数据标注、排序分类等结构化操作类任务，HTML 的批量操作能力远超文字描述效率。 比如需要从 50 个工单中筛选优先级、或者从代码片段集合中标记可复用组件，手动复制粘贴加文字描述远比用 HTML 构建一个可交互的拖拽式看板低效。这类任务中「导出」环节是关键——「复制为 Markdown」或「复制为 JSON」按钮将 UI 中的操作结果转换回 Claude Code 可处理的格式，形成完整的「人在回路中」的数据处理管道。
新增洞察：Artifact 循环作为人机协作界面（2026-05-23 ifanr）¶
新增内容（ifanr，Anthropic Claude Code blog 解读）：
- Artifact 循环工作流：读取上下文 → 生成单文件 HTML artifact → 人在 artifact 内审阅/调参/选方案 → 导出成 Markdown/JSON/Prompt/diff → 交给下一轮 Agent 实现或验证
- Claude Code 上下文优势：Claude Code 能读文件系统、git history、MCP 工具（Slack/Linear）、浏览器上下文——生成的不是普通网页，而是项目工作台
- Output styles 产品化信号：Anthropic 在把"输出形态"产品化——不只是
generate an HTML file，而是 stable format 的工作成果（always diagrams first、always reviewer artifact、always implementation report） - 适用场景扩展：PR review、多方案技术选型、陌生模块理解、设计稿对比、事故复盘时间线、prompt 调参、Linear ticket 优先级整理、研究报告和竞品分析
- Prompt 模板：
请读取当前项目上下文，生成一个单文件 HTML artifact，用来帮助我审阅这个任务。要求：第一屏给 TL;DR 和风险点；用横向对比展示方案差异；用 SVG 展示模块关系；关键代码加注释；结尾提供 copy as Markdown 按钮；不依赖外部资源 合并判断： 现有 entity 基于 Anthropic 官方 blog（feature 清单式），本篇补充更深层的分析视角——Artifact 作为人机协作界面的工作流价值、Claude Code 的上下文优势、Output styles 的产品化信号。merge 后从"功能清单"升级为"工作流方法论"。 → 原文存档
第 3 来源 — Claude Code 工程师 @Thariq：为何选择 HTML 替代 Markdown¶
- Thariq (Claude Code 工程师) 从开发者体验角度论证 HTML 优于 Markdown 作为 AI 文档载体
- 互补角度:
- 信息密度: HTML 可承载表格、CSS、SVG、JavaScript、交互组件，Markdown 难以自然表达
- 视觉清晰度: 长文档（>100行 Markdown）可读性差，HTML 支持标签页、插图、响应式布局
- 分享便利: Markdown 在浏览器中渲染不佳，HTML 可上传至 S3 直接分享链接
- 双向交互: HTML 文档可含滑块/旋钮调整设计参数，修改可反向生成 prompt 粘回 Claude Code
- Claude Code 摄取: 通过文件系统和 MCP 获取大量上下文（Slack、Linear、git 历史等），生成结构化 HTML
- 趣味性: 与 Claude 共同创作 HTML 文档更有参与感
来源：原文存档