Claude Code 与 HTML 的惊人有效性

当 coding agent 开始写长计划、PR 解释、研究报告时，Markdown 的便携性优势会被可读性与分享性压过。HTML 不是更花哨，而是更像“给人看的工作界面”。

作者观察到几条很硬的现实：

1. 超过约 100 行的 Markdown，自己都不太读完，更别说拉同事读。
2. 这些文件越来越少被人手改，更多是 spec / 参考 / 脑暴输出；Markdown “好编辑”的优势在削弱。
3. 模型会用 ASCII 图、Unicode 伪色块等低效手段硬塞可视化，因为 Markdown 表达力不够。

于是 Claude Code 团队内部越来越多人直接让 agent 产出 HTML。

1. 信息密度

同一份上下文里，HTML 可以同时承载：

• 表格与结构化数据
• CSS 设计稿
• SVG 图示
• 可运行代码片段
• 滑块 / 选项等交互
• 空间布局与 canvas
• 图片与流程图

对 evidence blog 或调查报告来说，这意味着“证据、注解、结论”可以同屏，而不是拆成一串附件。

2. 视觉清晰

Agent 可以把长计划做成：

• 分 tab 导航
• 图文对照
• 移动端可读布局
• 关键 diff / 关键路径高亮

结果不是“更炫”，而是你愿意打开并读完。

3. 分享成本低

Markdown 常要当附件发；HTML 上传后就是链接。规范、报告、PR writeup 被读到的概率会明显上升。

4. 双向交互

你可以要求：

• 调参滑块
• Now / Next / Later 看板
• 并排 prompt 模板编辑器
• “Copy as Markdown / JSON / Prompt” 导出

交互的终点最好是可粘贴回 agent 的结构化文本，否则只是一次性玩具。

5. 它更有趣

作者承认：HTML 生成更慢（约 2–4×），但自己更愿意参与、更愿意复核。对 agent 工作流而言，人还在环里比 token 极限压缩更重要。

不是因为只有它会写 HTML，而是因为它能吞下大量上下文：

• 本地文件系统
• git history
• MCP（Slack / Linear 等）
• 浏览器 / 仓库状态

HTML 只是“高带宽输出面”；输入面仍依赖 tool use 与 harness 上下文。

| 场景 | 让 agent 产出什么 | | --- | --- | | 规划 / 探索 | 多方向并排 mock、数据流图、关键代码片段 | | 代码审查 | 带边注的 diff、backpressure / 流控重点解释 | | 设计原型 | 可点 HTML + 滑块调动画参数 | | 研究报告 | 单页 explainer：图 + 注解 + 来源 | | 临时编辑器 | 拖拽优先级、prompt 变量高亮，最后一键导出 |

示例意图（不是完整 prompt 库）：

• “给 onboarding 做 6 个风格差异明显的方案，排成一页 grid 对比。”
• “把这个 PR 的 streaming / backpressure 逻辑做成 HTML 审查页，内嵌 diff 边注。”
• “做个一次性看板，把 30 张票拖进 Now / Next / Later / Cut，并提供 Copy as Markdown。”

• Token 更贵？ 是，但“你真的会读”带来的有效产出往往更高。
• 什么时候还用 Markdown？ 作者几乎停用了；务实做法是：短 checklist 用 MD，长交付用 HTML。
• 版本控制？ HTML diff 更吵，这是真短板；可把“结论摘要”另存短 MD。
• 会不会丑？ 给一份公司 / 个人设计系统 HTML 当参考，比空喊“好看一点”有效。
• 要不要立刻做成 /html skill？ 作者反而提醒：先手写 prompt 摸清用法，再固化 skill，避免过早教条化。

如果你已经在用 agent skills 做报告 / PPT / 原型：

1. 把“单文件 HTML + 可选第二版（图内嵌 base64）”当作默认交付。
2. 长研究优先 evidence 结构：主张 → 证据 → 反证 → 下一步。
3. 需要设计哲学与防 AI 腔时，看 华数设计 Skill 导读。

1. 计划阶段强制要 HTML 结构，而不是 200 行 Markdown 清单。
2. 审查阶段用 HTML 解释 diff，而不是只贴 PR 链接。
3. 分享阶段优先链接，不发难打开的附件。

源文与示例：

• 推文入口
• 示例合集