HTML as Agent Output
创建时间： 2026-05-12
来源： [[sources/Using Claude Code The Unreasonable Effectiveness of HTML.md]]
相关： Thariq-Shihipar，Vibe-Coding-to-Agentic-Engineering，Agent-Native-Infrastructure，Software-Fundamentals-in-AI-Coding，Harness-Engineering
Thariq Shihipar 在《Using Claude Code: The Unreasonable Effectiveness of HTML》中提出一个介质判断：随着 agent 能力增强，Markdown 不再总是最好的 AI 输出格式；在很多场景里，HTML 更适合作为 agent 与人沟通的产物层。
这不是单纯的“HTML 更漂亮”。底层变化是：人类越来越少直接编辑 agent 产出的文件，更多把它们用作 spec、参考文档、方案探索、研究报告和交互界面。既然主要动作从“手改文本”转向“阅读、比较、调参、反馈”，Markdown 的核心优势就变弱了，而 HTML 的视觉、交互和分享能力开始变成优势。
核心命题
Markdown 成为 AI agent 默认格式，是因为它简单、可读、token 效率高，也方便人类手动编辑。但当 Claude Code 这类工具能够生成更长、更复杂的计划和说明后，Markdown 会暴露三个问题：
- 长文档难读：超过一百行的 Markdown plan 很容易被人跳过。
- 表达维度不足：图表、颜色、空间关系、交互状态只能用 ASCII 或粗糙文本模拟。
- 分享成本高：浏览器不能很好地原生渲染 Markdown，经常需要作为附件传递。
HTML 的优势在于它是浏览器原生运行时，可以在一个自包含文件里同时承载文本、CSS、SVG、表格、图像、脚本、交互控件和页面内导航。对 agent 来说，HTML 是“可生成的界面”；对人来说，HTML 是“可直接阅读和操作的文档”。
HTML 解锁的能力
信息密度
HTML 可以把同一份信息编码为多种视觉结构：
- 表格呈现结构化数据；
- CSS 呈现设计 token、颜色、排版和状态；
- SVG 呈现流程图、架构图、技术插画；
- JavaScript 和表单控件承载交互；
- Canvas 和绝对定位表达空间信息；
- 图片和代码片段并置形成更完整的解释。
因此，HTML 不只是文本格式，而是一种信息投影方式：它允许 agent 把复杂信息重新组织成更适合人类视觉系统读取的形态。
可读性与视觉清晰度
当 AI 生成的 spec、plan、PR writeup 变长，人的瓶颈不再是“有没有内容”，而是“有没有真的读进去”。HTML 可以用 tabs、卡片、锚点、插图、颜色层级和响应式布局降低阅读摩擦，让团队更可能真正消费这份文档。
这与 Vibe-Coding-to-Agentic-Engineering 的“理解不能外包”相连：HTML 的价值不是让人更少理解，而是让人更容易保持在理解回路里。
分享与协作
Markdown 文件通常需要作为附件、仓库文件或渲染后的页面分享。HTML 则可以直接上传到 S3、GitHub Pages 或任意静态托管环境，用一个链接交付。对 PR 说明、事故报告、周报、研究摘要这类“希望别人真的读”的材料，分享阻力本身会影响内容是否被消费。
双向交互
HTML 还可以成为一次性编辑器，而不只是展示文档。Thariq 的关键建议是：当输入框难以描述需求时，让 Claude 生成一个专门的临时 HTML 工具，例如拖拽排序、feature flag 编辑器、prompt tuner、颜色选择器、缓动曲线调参器。最后再提供“copy as JSON / copy as prompt / copy diff”按钮，把人的操作重新导出给 agent。
这使人机循环变成：
- Agent 生成界面；
- 人在界面中选择、调参、排序、标注；
- 界面导出结构化结果；
- Agent 继续执行。
Claude Code 的特殊性
Thariq 强调，使用 Claude Code 生成 HTML 的原因不只是模型会写 HTML，而是 Claude Code 可以摄入更多上下文：文件系统、代码库、git 历史、MCP 工具、Slack、Linear、浏览器上下文等。HTML 产物可以把这些分散上下文综合成一个可读、可交互的页面。
这使 HTML 成为 Harness-Engineering 中一种重要的交接工件：它既能承载 agent 的分析结果，也能成为下一轮 agent 工作的上下文入口。
典型用例
规划与探索
当方向不确定时，HTML 可以把多个方案并排展示：不同布局、不同实现路径、不同权衡、模拟图、数据流和时间线。相比线性 Markdown，HTML 更适合“横向比较”。
代码审查与理解
代码 diff、调用图、模块边界和风险等级天然带有空间关系。HTML 可以把 diff 与边注、严重程度标签、跳转链接、模块图结合起来。Thariq 甚至提到自己会给每个 PR 附一个 HTML code explainer。
设计与原型
HTML 可以快速表达设计系统、组件状态、动画曲线和点击流程。即使最终产品不是 Web，HTML 也可以作为交互草图和设计讨论介质。
报告、研究与学习
Claude Code 可以从代码库、Slack、git 历史和互联网汇总信息，生成面向个人、团队或管理层的 HTML 报告。适用场景包括功能解释、概念学习、周报、事故复盘、技术图解等。
临时编辑界面
当任务需要人类进行选择、排序、标注、参数调整，而纯文本 prompt 难以表达时，HTML 可以变成一次性编辑器。关键是始终提供导出按钮，让人的操作重新回到 agent 可读的文本或结构化数据中。
代价与边界
HTML 不是无条件替代 Markdown：
- 生成更慢：Thariq 估计 HTML 可能比 Markdown 慢 2-4 倍。
- 版本控制困难：HTML diff 噪音大，不如 Markdown 易审查。
- token 成本更高：虽然长上下文削弱了这个问题，但仍然存在。
- 审美依赖强：如果没有设计系统参考，模型容易生成难看的页面。
- 不适合所有中间件：机器间结构化交换仍应优先使用 JSON、YAML、协议或测试结果等明确格式。
因此更准确的判断是：Markdown 仍适合短文本、可审查说明、轻量文档；HTML 更适合长解释、视觉化、交互式、需要被认真阅读或操作的 agent 输出。
更深的意义：Stay in the Loop
这篇文章最后落在一个很重要的人机关系问题上：当 agent 越来越能干，人类可能因为不再认真阅读计划而逐渐退出决策回路。HTML 的真正价值，是让人更愿意读、更容易理解、更能参与调整，从而重新留在循环中。
这与 Software-Fundamentals-in-AI-Coding 的判断一致：AI 可以承担大量战术执行，但人不能撤出设计责任。HTML artifact 是一种让人保持战略理解的界面。