HTML作为Agent输出格式（The Unreasonable Effectiveness of HTML）

本文档基于 2026 年 5 月 8 日 Anthropic Claude Code 团队成员 Thariq Shihipar 发表的长文《Using Claude Code: The Unreasonable Effectiveness of HTML》整理而成。其核心主张是，当 AI Agent 需要向人类传达复杂信息时，HTML 应取代 Markdown 成为首选输出格式。文章指出 Markdown 存在信息密度不足、可读性差、分享困难、无法交互、编辑范式转移以及人与 Agent 的 Loop 断裂等六大痛点。HTML 则凭借其高表达力、视觉可读性、零摩擦分享、双向交互、数据摄取优势及情感连接等特性，成为更优的 Agent 输出格式。该方法论强调自包含的 HTML 文件、导出闭环以及让人类重新参与 Agent 决策过程。文章还对比了 HTML 与 Markdown、Claude.ai Artifacts 及 Notion/飞书文档的差异，并提供了九大输出场景、Prompt 模板、工程落地技巧及优缺点分析。

本文档基于 2026 年 5 月 8 日 Anthropic Claude Code 团队成员 Thariq Shihipar 发表的长文《Using Claude Code: The Unreasonable Effectiveness of HTML》整理而成。其核心主张是，当 AI Agent（尤其是 Claude Code）需要向人类传达复杂信息时，HTML 应取代 Markdown 成为首选输出格式。

文章系统梳理了 Markdown 作为 Agent 输出格式的六大核心痛点：

• 信息密度不足：Markdown 只能表达标题、列表、粗体、代码块等有限结构，面对复杂表格、设计系统、架构图、空间关系时，不得不退化为 ASCII 艺术或冗长文字描述。
• 可读性断崖式下降：当 Agent 写出超过 100 行的 Markdown 文件时，作者坦言自己实际上不会去读，更不可能让组织里的其他人去读。
• 分享困难：Markdown 文件在浏览器中无法原生渲染，接收方需要专门工具才能阅读，降低了 Spec、报告、PR 说明的实际传播效果。
• 无法交互：Markdown 是纯静态文本，不能添加滑块调整参数、不能拖拽排序、不能实时预览模板渲染。
• 编辑范式转移：用户越来越不自己编辑 Markdown 文件，而是让 Claude 来编辑，削弱了 Markdown「易于编辑」的最大优势。
• 人与 Agent 的 Loop 断裂：当用户不再深入阅读 Agent 的输出时，就失去了对决策过程的参与，等于放弃了人类在 AI 工作流中的监督角色。

该方法论的核心实现方式是让 Agent 生成自包含的 HTML 文件，而非 Markdown 文件。具体机制包括：

• 自包含 HTML 文件：每个 HTML 文件完全自包含，CSS 内联、JS 内联、SVG 内联，无需构建步骤、无需外部依赖，双击即可在浏览器中打开，上传 S3 或 GitHub Pages 即可分享。
• 导出闭环：每个交互式 HTML 都以「导出按钮」结尾（Copy as JSON / Copy as Markdown / Copy as Prompt），形成 Prompt → HTML → 操作 → 导出 → 粘贴回 Prompt 的完整闭环。
• Claude Code 的数据摄取优势：Claude Code 能读取文件系统、MCP 工具（Slack/Linear/GitHub 等）、浏览器集成、Git 历史及代码上下文，远超 Claude.ai 的上下文能力。
• 标准工作流：用户发出 Prompt → Claude Code 读取上下文 → 理解并规划 HTML 结构 → 生成自包含 HTML 文件 → 用户在浏览器中打开 → 导出反馈（可选）→ 循环迭代。
• 无需额外工具：不需要 Skill、不需要配置、不需要任何安装，直接在 Claude Code 中对 Agent 说「生成一个 HTML 文件来展示...」即可。

• 表达力极高：几乎任何信息都能用 HTML 高效表示
• 可读性强：视觉化让复杂信息的理解成本大幅降低
• 交互能力：滑块、拖拽、实时预览，Markdown 完全不具备
• 分享零摩擦：浏览器原生支持，上传即分享
• 自包含：单文件、无依赖、离线可用
• 导出闭环：操作结果可导出回 Prompt，形成完整 Loop
• Claude Code 独有优势：文件系统/MCP/Git/浏览器的丰富上下文
• 适用场景广：Spec/Review/Design/Report/Editor/Deck 全覆盖
• 学习成本为零：用户不需要写 HTML，Agent 生成
• 重新进入 Loop：让人类重新参与 Agent 的决策过程

• AI 整理 · 本地测试，未经人工复核；依据历史报告节选，不代表当前产品状态。

• 该方法论并非适用于所有场景，文章明确指出了其局限性和不建议使用的场景：

• 生成耗时：HTML 生成耗时是 Markdown 的 2-4 倍，不适合快速迭代场景。

• 版本控制差：HTML diff 比 Markdown diff 噪音大得多，不适合 git 频繁追踪的文件。

• Token 消耗大：文件体积比 Markdown 大数倍，但在 Opus 4.7 的 1M 上下文窗口下，额外开销基本可以忽略。

• 不支持协作编辑：不像 Notion/飞书支持多人实时编辑。

• 依赖 Agent 能力：需要 Agent 本身擅长生成高质量 HTML。

• 不适合 Agent 输入：机器消费场景 Markdown 仍然更优（Token 效率）。

• 不适合频繁变更：每次变更都需要重新生成整个文件。

• 不适合正式文档系统：企业知识库/wiki 等场景需要专门平台。

• 不适合无浏览器场景：终端/CLI 环境无法直接查看。

• 不建议用于：Agent 间通信、简短笔记/TODO（低于 100 行的简单文档）、Git 频繁追踪的配置文件、需要多人协作的文档、纯 API/数据交换（用 JSON/YAML）。

文章强调，HTML 不会取代 Markdown，正确的理解是双轨制：Markdown 用于 Agent → Agent，HTML 用于 Agent → Human。