Claude Code 与 HTML Artifacts 的不合理有效性

Markdown 赢得了 agent 协作的第一阶段，因为它足够简单。

它容易生成、容易 diff、容易粘贴到 pull request 里，也足够胜任大多数笔记。因此它自然成了 coding agents 的默认输出格式：计划、总结、规格说明、评审笔记、事故复盘和实现清单，最后都变成了 Markdown。

Anthropic 最新的 Claude Code 文章指出，这个默认选择开始显露边界。

重点不是 Markdown 不好，而是 Claude Code 现在能做的事已经不只是写一篇很长的文本文件。HTML 给模型提供了更好的工作表面：更高的信息密度、更清晰的视觉结构、更容易分享的 artifacts，以及轻量级交互。

对开发者来说，这是一个很实际的变化。它改变了我们应该让 Claude Code 产出什么。

核心观点

在官方文章中，Claude Code 团队的 Thariq Shihipar 解释了为什么他开始在许多 Claude Code 输出中更偏好 HTML 文件，而不是 Markdown。

原因很直接：随着 Claude Code 承担更大的任务，输出本身也会变得更大。

30 行的 Markdown checklist 没问题。300 行的实现计划、研究报告、代码评审、架构解释或 UI 探索，即使技术上能渲染，也不代表它适合阅读。

HTML 给 Claude Code 更多空间来组织同样的信息：

• 用表格做高密度对比
• 用 CSS 建立视觉层级
• 用 SVG 画图
• 用图片展示引用
• 用 JavaScript 做本地交互
• 用标签页和章节做导航
• 用按钮复制生成的 prompts、JSON、diff 或设置

这让 HTML 不再只是文档格式，而更像一次性的工作台。

对 agent 工作流来说，这个区别很重要。

为什么这对 Claude Code 用户重要

Claude Code 和普通聊天界面不同，因为它能读取本地项目、检查 git 历史、操作文件、使用 MCP servers，并且能在真实工程 workspace 里生成 artifacts。

这让它非常适合基于真实上下文创建有用的 HTML artifacts。

例如，与其问：

Write a plan for refactoring the billing module.

你可以问：

Create an HTML artifact that explains the billing refactor.
Include a module map, the key file changes, risks by severity,
a staged migration plan, and a copyable implementation prompt.

这两个 prompts 背后的请求可能相同，但第二个请求的是一种更容易检查、更容易分享，也更容易在后续 Claude Code 会话中作为参考使用的格式。

这才是真正的优势：HTML 可以变成持久的项目上下文，而不只是一次性的回答。

HTML 胜过 Markdown 的四类场景

1. 规格说明与计划

规划是 Markdown 最先开始吃力的地方。

长实现计划通常会混合架构、代码片段、依赖关系、图表、权衡、截图和开放问题。Markdown 可以承载这些内容，但它并不会帮助读者导航。

HTML 可以让 Claude Code 把计划拆成更易审查的界面：

• 顶部概览
• 系统流程图
• 按文件列出的变更地图
• 风险表
• 分阶段 rollout 计划
• 未解答问题
• 可复制的后续 prompts

当一个计划需要跨 session 保留下来时，这尤其有用。未来的 agent 可以把 HTML 文件作为上下文读取，人类也能快速扫描，而不用读一整面文字墙。

2. 代码评审与理解

代码评审不只是文本，它本质上是结构。

好的评审通常需要 diff、严重级别、受影响模块、调用路径、数据流，以及对问题重要性的简短解释。Markdown 可以近似表达这些内容，但 HTML 可以直接渲染出来。

对 Claude Code 来说，这意味着一个更好的工作流：

Review this PR by creating an HTML artifact.
Show the diff with inline annotations, group findings by severity,
and include a small diagram of the streaming/backpressure path.

这样评审输出就更接近一个交互式 review packet。它仍然可以是临时产物，但更容易交给另一个工程师阅读。

3. 设计与原型

当输出带有视觉或交互组件时，HTML 是 Claude Code 的天然目标格式。

即使生产应用是 React、Swift、Kotlin 或其他技术栈，HTML 仍然是一种快速草拟布局、比较方向、测试动效和调参的方式。

原文提到 sliders、knobs 和 copy buttons 这些有用的 primitives，这个心智模型是对的。Claude Code 可以生成一次性界面，帮助选择那些很难用文字描述的值：

• 色板
• easing curves
• 组件密度
• 裁剪区域
• prompt 变体
• feature flag 组合
• ticket 优先级

关键是导出。好的 HTML artifact 最后应该产出有用的东西：复制为 JSON、复制为 Markdown、复制为 prompt，或复制 diff。

如果 artifact 不能把输出送回工程工作流，它就只是 demo。

4. 报告、研究与学习

Claude Code 可以综合代码库、git 历史、文档、通过 MCP 接入的 Slack、通过 MCP 接入的 Linear，以及网页资料。Markdown 可以总结这些上下文，但 HTML 可以让它更可读。

对内部说明、事故复盘、周报、依赖审计和 onboarding guide 来说，HTML 给模型足够的视觉空间来展示关系，而不只是描述关系。

这就是 HTML 作为学习格式的价值：

• 带注释的代码片段
• 系统图
• 术语解释块
• 时间线视图
• 风险矩阵
• 决策表

结果不需要成为精致产品。它只需要足够可读，让人愿意真的使用它。

隐含重点：HTML 让人继续留在循环里

Anthropic 文章最强的部分不是格式论证，而是工作流论证。

随着 Claude Code 处理更大的任务，开发者可能会越来越少阅读 agent 产出的内容。很长的 Markdown 计划很容易被草草批准，而没有被仔细审查。这很危险，因为计划里可能包含薄弱假设、遗漏边界情况，或者开发者本不会接受的变更。

HTML 可以降低这种失败模式，因为它给人更好的抓手：

• 扫描 overview
• 检查图表
• 并排比较选项
• 跳到风险区
• 调整 slider
• 把选中的输出复制回 Claude Code

这不会消除审查的必要性，但会让审查更有可能发生。

对严肃的 agent 工作流来说，这不是装饰，而是控制的一部分。

什么时候 Markdown 仍然更合适

HTML 不应该替代所有 Markdown。

当 artifact 需要满足这些条件时，Markdown 仍然更好：

• 体积小
• 适合 diff
• 经常手动编辑
• 嵌入 README
• 粘贴到 issue 或 PR 描述里
• 被期望 Markdown 的工具消费

实用规则很简单：

当输出主要是文本，并且会由人类编辑时，用 Markdown。

当输出需要布局、图表、高密度对比、交互，或更好的阅读体验时，用 HTML。

这样 HTML 就不会变成另一个被滥用的默认格式。

一个简单的 prompt 模式

如果你想在 Claude Code 里尝试，可以从一个直接的 prompt 开始：

Create a single HTML artifact for this task.
It should be readable in a browser, self-contained, and optimized for review.
Use tables, diagrams, and sections where useful.
Add copy buttons for any output I may want to paste back into Claude Code.
Keep all source references visible.

然后把用途说具体：

For this refactor, include:
- a dependency map
- the proposed file changes
- migration steps
- risks by severity
- test plan
- open questions

随着时间推移，重复出现的模式应该变成 skills 或 templates。但第一步不需要基础设施，只需要养成让 Claude Code 产出更好 artifact 的习惯。

团队下一步该做什么

短期机会不是把所有内部文档系统都重建成 HTML。

更实用的动作要窄得多：

1. 找出团队里那些大家其实不会认真读的 Claude Code 输出。
2. 把其中一个输出改成 HTML artifact。
3. 要求 artifact 能把有用内容导出回工作流。
4. 当它能帮助后续 session 时，把 artifact 留在 repo 里。
5. 如果它只服务于一次决策，就删掉它。

最后一点很重要。许多 HTML artifacts 都应该是一次性的。它们的价值在于帮助人现在做出更好的决定。

最后结论

HTML 的不合理有效性，不在于它是比 Markdown 更好的标记语言。

而在于 HTML 给 Claude Code 提供了更丰富的协作界面。

对小型笔记来说，Markdown 仍然是正确工具。但对于规格说明、代码评审、架构解释、设计探索、研究报告和自定义编辑界面，HTML 可以让 agent 输出更可读、更易分享、更可执行。

随着 Claude Code 能承担更大的工作块，输出格式本身就会变成工作流设计的一部分。把 artifacts 当作一等审查界面的团队，会比继续批准 Markdown 文字墙的团队更能保持控制。

来源

• Claude blog: Using Claude Code: The unreasonable effectiveness of HTML
  https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html