原文：Using Claude Code: The unreasonable effectiveness of HTML · Thariq Shihipar · Anthropic Blog · 2026-05-20
一句话导读：当 Agent 已经能自动把活干完，工程师不再需要"输出更聪明的文字"，而需要"输出能站进去的画布"。HTML 是 Anthropic 内部找到的、几乎唯一能同时承载多源摄入 / 视觉决策 / 双向回灌的 Agent 输出格式。
引言：跑得越快的 Agent，越需要一块能"站进去"的画布
如果你最近用过 Claude Code、Cursor 或者任何一个把"自主"开到比较大的 Coding Agent，会有一个不算愉快的感受：
Agent 跑得越快，你越不知道它在干什么。
PR 描述秒生成、5 个文件同时改、测试自己跑、自己回滚、自己重写——你打开 IDE 时面对的不是"未完成的代码"，而是"已经被悄悄完成的一整个分支"。然后你照例往下翻 plan.md，翻到一半就放弃了，因为：
- 这是一份线性的、扁平的、没人会读完的 Markdown。
- 它把"6 种入职界面方案"压成 6 段文字。
- 它把数据流图压成一句"前端 → 后端 → 队列"。
- 它把 30 张需要你重排优先级的 ticket 压成一个有序列表。
Thariq Shihipar 在 Anthropic 5 月 20 日发的这篇《The unreasonable effectiveness of HTML》给出了一个看起来"很美式工程师"的回答：几乎完全停用 Markdown，所有产物一律走 HTML 单页文件。
他自称"HTML 极端主义者"。读完原文你会发现，这不是审美偏好——是一种保住人类参与感的工程选择。当 Agent 自主性继续上升时，“在循环里"和"被踢出循环"之间，差的可能就是一种愿意承载交互的输出格式。
「我使用 HTML 而非 Markdown 的真正原因，是它让我感觉与 Claude 的协作过程更加’同步在线’（in the loop）。」
—— Thariq Shihipar
本仓库 2026-05-13《HTML 对 Agent 的不合理有效》 已经基于 Thariq 的 demo 合集解释了"为什么 Markdown 把空间信息压扁了”。这一篇换一个角度——不谈 demo 集合，谈作者本人在 Anthropic 内部实际怎么用 HTML 重构日常工作流——并把它的工程含义推到三条不那么舒服的判断上。
一、五大能力维度：HTML 相对 Markdown 多做了什么
原文给出 HTML 的五个优势：信息密度、视觉清晰度、易于分享、双向交互、数据摄入。这五条不是并列的——它们是层层递进的：
- 信息密度让 HTML 能装下 Markdown 装不下的东西；
- 视觉清晰让它真的会被读完；
- 易于分享让它走出 IDE；
- 双向交互让它回头影响决策；
- 数据摄入让 Agent 承接得了多源输入。
把这五条铺开看，就能解释为什么"换一种格式"在工程上是个有杠杆的动作：
1. 信息密度：先解决"装不下"的问题
Markdown 有一个非常粗暴的失败模式——一旦遇到表格 / 设计 / SVG / 代码片段同时存在的场景，它会触发"低维兜底"。原文有一句话很尖刻：
「如果做不到这点，模型可能会在 Markdown 中做一些低效的事情，比如 ASCII 图示，或者我最’喜欢’的——用 Unicode 字符来估算颜色。」
我猜大多数人都见过：让 Claude 画一张系统架构图，结果给你一堆 ┌──┐ ──> ┌──┐ 的 box drawing；让它出一组配色，结果出来一串 ■ #3b82f6（蓝色） 的 emoji 块。这不是模型笨，是格式本身把它逼到了"哑词"上。
HTML 一旦上场，模型立刻有了真画板：表格、SVG、<canvas>、<input>、<style>、绝对定位——表达力维度完全不在一个量级。
2. 视觉清晰：100 行 Markdown 没人读完
这一点不是审美问题，是生理问题。
任何超过 80~100 行的 Markdown 文件，用户都会从读变成扫，从扫变成关掉。HTML 可以做 Tab、可以做侧栏、可以做折叠、可以分块——这些都不是炫技，这些是让你愿意读完它的最后防线。
Markdown 是流，HTML 是版面。流里面藏不住结构。
3. 易于分享：让产物走出 IDE
Markdown 出了 IDE 就开始变形：终端里 emoji 错位、Slack 里表格炸裂、复制到飞书表格丢失。Claude 给你写的"评审报告"，真正传到下游评审者眼里时，已经不是它当初的样子。
HTML 解决得很粗暴：上传 → 链接 → 浏览器原生打开。Thariq 用了一句很工程师的话：
「你的规格说明、报告或 PR 文档被真正阅读的概率会高得多。」
注意是"概率"——这是一个被低估的指标。一份没被读的 PR 描述等于零，一份被读完的 PR 描述顶得上半场会议。
4. 双向交互：让画布能"写回去"
到这里 HTML 才真正甩开 Markdown 一个量级——<input>、<button>、onclick、navigator.clipboard.writeText 这些原生能力让产物可以承担决策：
- 拖动滑块预览动画曲线 → 复制参数；
- 拖拽 ticket 重排优先级 → 复制 Markdown；
- 在 prompt 上左右分栏调样本 → 复制最终模板。
Markdown 的世界里，这一步只能"再写一段 prompt 让 Claude 帮我做 X"——交互在嘴里，决策在脑子里，循环始终断在键盘和屏幕之间。
5. 数据摄入：输入的丰度需要等量丰度的输出
最后一条最容易被略读，但其实是这五条里最有杠杆的一条：
Claude Code 的输入端正在快速变厚——文件系统、MCP（Slack / Linear / Jira）、浏览器（Claude in Chrome）、Git 历史。
输入侧拓宽了多少，输出侧就要被迫拓宽多少。否则 Agent 会把"我从五个数据源汇总出来的洞察"压缩成一段 Markdown 摘要——带宽差就在这里被卡死。HTML 是目前唯一能匹配输入丰度的标准输出格式。
二、五类工作流 × 五大能力：场景矩阵
光知道 HTML 能力强还不够，要知道每一类任务该撬动哪几条能力——这决定了 prompt 怎么写。
把原文给的五类工作流（规划探索 / 代码评审 / 设计原型 / 报告学习 / 一次性编辑器）和上面五大能力交叉，得到一张矩阵：
读这张矩阵的方法是纵看 vs 横看：
- 纵看——同一种能力在不同任务里值多少。比如"双向交互"在"一次性编辑器"里是核心能力，但在"报告学习"里完全可以没有；
- 横看——为这一类任务该写哪些 HTML 元素。这能直接翻译成 prompt 模板。
下面用最值得展开的两类聊一下，剩下三类写在小节末。
A. 规划 / 探索：从单计划到文件网络
原文这段最反直觉的一句：
「我不再用单一计划，而是为计划的不同阶段/部分维护多个 HTML 文件。」
这是一种对 plan.md 信仰的公开决裂——在过去两年的 Agent 工程实践里，“维护一份 plan.md，agent 边读边干"几乎是默认范式。Thariq 直接把它换掉了：
为什么？因为单文件 Markdown 在第三章往后就开始失真——UI 探索、数据流、设计 token 这些天然多维的内容，被强行压成线性段落，越往下越糊。
HTML 文件网络的解法是承认计划的不同部分需要不同维度：UI 探索需要二维并排，数据流需要 SVG，设计 token 需要色块，风险盘点需要勾选框。各自一个 HTML 文件，互相链接，下次新 session 一起喂给新 agent。
这种做法的代价是文件数变多——但好处是每一份都能被读完、被点开、被改动。
E. 一次性编辑器：最反工程直觉的一类
这一类是原文最让我停下来想了 5 分钟的部分：
「构建’一次性编辑器’——不是产品，不是可复用工具，而是为某一份数据专门打造的单个 HTML 文件。」
注意"不是产品，不是可复用工具"这句。
每个有点工程素养的人听到这话都会本能不适：那不是浪费吗？写完用一次扔了？后面同事再排优先级又得让 Claude 重写一遍？
但这正是 HTML × Agent 的杠杆所在——当 Agent 写代码的边际成本接近零时，“必须复用"这条工程直觉就开始崩。Thariq 给了七个值得你做一次性编辑器的场景：
| 场景 | 一次性编辑器的形态 |
|---|---|
| 重排 / 分诊 / 归类 | 30 张可拖拽 ticket × 4 列（Now/Next/Later/Cut） |
| 编辑结构化配置 | 按区域分组的 feature flag 表单，依赖关系警告 |
| 调优 prompt / 模板 | 左右分栏：可编辑模板 + 实时填充的样本输出 |
| 数据集策展 | 批准 / 拒绝 / 打标签按钮 + 选择导出 |
| 标注文档 / diff | 边距批注 + 严重度颜色 + 导出标注 |
| 选择难以文字化的值 | 颜色 / 缓动曲线 / 裁剪区域 / cron / 正则 |
| feature 配置审查 | 全表预览 + “复制 diff"按钮 |
每一类都满足一个共同特征：这件事需要的是空间感、不是文字——而 Markdown 偏偏只能给文字。
B / C / D 三类的关键 prompt 词
再补充其他三类，每类附作者原文的关键 prompt 句式（粘贴可用）：
- B. 代码评审：“帮我审查这个 PR，创建一个描述性的 HTML 制品，渲染实际 diff 并加边距注释，按严重度颜色编码。”
- C. 设计原型：“为新的结账按钮做原型——创建一个带多个滑块和选项的 HTML 文件供我尝试不同动画参数，并提供一个’复制参数’按钮。”
- D. 报告 / 学习：“阅读限流器代码并生成单页 HTML 讲解：令牌桶流程图、3-4 个关键代码片段（附注释）、底部加’陷阱’小节。优化为’读一次就懂’的体验。”
最后一句"读一次就懂"是关键约束词——它直接告诉模型不要把内容铺开成一万字 Markdown。
三、把"反馈循环"画清楚：一次性编辑器为什么是关键
上面第 E 类（一次性编辑器）单独拎出来讲，是因为它把这套工作流的真正引擎暴露了：
四步循环里，最容易被忽略的是 ③ 导出。原文有一条非常硬的规则：
「总是以导出结束——‘复制为 JSON’或’复制为 prompt’按钮，让 UI 中的操作能粘贴回 Claude Code。」
为什么这一句这么硬？因为如果没有导出按钮，前两步再漂亮，循环也会断在第三步。工程师在 HTML 上做了一堆决策——拖了 30 张卡片、勾了 12 个 flag、调了 8 个滑块——然后呢？
- 没有导出按钮：他得用嘴把这些决策再描述一遍给 Claude。决策密度被 Markdown 重新压扁，前面所有工作白做。
- 有导出按钮：一键拷贝，粘贴回 Claude Code，Claude 拿到的是和工程师在画布上看到的同一份结构化结果。
这是整套思路里最值钱的一句设计原则，没有之一。它让"在 HTML 里点鼠标"和"写 prompt"这两件事本质上等价，循环就此闭合。
四、三条不那么舒服的判断
读到这里，把作者的工作流总结成"用 HTML 替代 Markdown"是不够的。这套实践背后有三条不那么舒服、但工程含义更深的判断，值得各自说清。
判断 1：「一次性编辑器」打破了"软件必须复用"的工程直觉
过去十年的工程哲学是"DRY、抽象、复用”。它假设写代码很贵——所以同样的事不能做两次。
LLM 把这个前提改了。当 Claude 能在 30 秒里给你写一个针对这 30 张特定 ticket 的拖拽编辑器时，“这次用一次扔了” 第一次成为比"做成可复用工具"更划算的选项。
这件事的难处不在技术，在心理：你需要允许自己接受"写完就扔"是合法的工程产物。它和过去十年所有工程价值观背道而驰，但在 Agent 时代，它是对的。
类似地，你也会发现"模板沉淀"这种事变得没那么重要——因为生成成本低于维护成本。这对工具链团队是个值得警惕的信号。
判断 2：「总是以导出结束」是反馈循环收紧的关键
第三章已经说过了，这里加一句负向论证：
如果你给 LLM 写过任何"看起来很 fancy 但用过一次就不再用"的产物，回头去看，几乎都是因为它没有清晰的导出路径。
- 一个让你滑动调整的设计 demo，调完了没有"复制 token"按钮 → 调了等于白调；
- 一个让你勾选的 feature flag 配置面板，勾完了没有"复制 diff"按钮 → 勾了等于白勾；
- 一个让你打分的数据策展 UI，打完分没有"导出选择"按钮 → 等于在玩一个浪费生命的小游戏。
所以下次写 prompt 让 Claude 做交互式产物时，默认在最后追加一句"附’复制为 X’按钮”——把它当成铁律，不当成可选项。
判断 3：token 不是 HTML 的成本，注意力才是
最容易被反驳的点：HTML 比 Markdown 多很多 token，难道不是更贵？
原文给的回答是从模型经济学角度切的：Opus 4.7 已经是 1M token 上下文，HTML 多出来的 token 占比小到可以忽略。
但更深的回答是：真正稀缺的不是 token，是注意力。
- 100 行扁平 Markdown 的 token 比一份结构化 HTML 少，但读它要花的注意力是 10x 起步；
- 一份没人读完的 PR 描述，不论它多少 token，信息传递效率为零；
- 而一份被实际打开、被读完、被点击的 HTML 工件，效率从零变成正数。
注意力是数量级稀缺资源，token 不是——这一点在 1M context 时代更成立。所以"HTML 太啰嗦"这种 2024 年的反驳，在 2026 年已经不太成立。
五、落地路线：从一份 mockup 到组织级工件库
三条判断说完，接下来是工程上怎么走。下面这张三阶段路线图，把"个人尝试 → 团队约定 → 组织沉淀"分开看，避免一上来就规划"内部 HTML 工件平台”——那是反模式：
阶段 1（第 1 周）· 个人
最低成本的起步只有一个动作——在你日常给 Claude 的 prompt 末尾加一句：
“把它做成一个单页 HTML 文件，本地浏览器打开就能用。”
先在三类任务里试：
- 下次需要规划方案时，让它做一份"6 种方案并排"的 HTML，而不是 plan.md；
- 下次评审 PR 时，让它生成一份带边距注释的 review.html；
- 下次想搞懂一段陌生代码时，让它做一份"读一次就懂"的 explainer.html。
这三件事跑顺之前，不要急着进阶段 2。
阶段 2（第 2~6 周）· 小组
当组里有 2~3 个人都开始用 HTML 工件后，先约定一件事：
每一份产物末尾都必须有一个"复制为 ___“按钮。
把这条写进 CLAUDE.md 或者团队 prompt 模板里。这一条就够了——它把"反馈循环收紧"从个人习惯变成团队共识。
阶段 3（3 个月+）· 组织
到这一步才适合谈模板 / 设计 token / Skill：
- 沉淀一份"评审报告 HTML 模板”、一份"PR Review 模板"、一份"原型设计模板"；
- 在 CLAUDE.md 或 Skills 里收口"什么任务用什么 HTML 工件结构"；
- 让组织里 N 个人写出来的 HTML 工件长得一致，方便互相 review。
反模式（重要）
不要从"搭一个内部 HTML 工件平台"起步。
那等于把"一次性编辑器"变成"必须复用的产品"。沉没成本会逼着你向后兼容、修 bug、做版本管理，反而失去 HTML 在 Agent 协作里最值钱的那点东西——便宜、可丢弃、随用随生成。
结语：循环没有断，循环更紧了
回到 Thariq 那句最值得抄走的金句：
You stay in the loop, but the loop gets much tighter.
「你保持在循环中，但循环变得更紧密。」
过去两年关于 Agent 的讨论一直围绕"自主性 vs 控制感"这个伪二元——好像 Agent 越自主，人就越被踢出循环。
而 HTML 这件事说明的是另一件事：循环没有断的必然性，循环可以同时变紧 & 变自动。Agent 跑得多快、做得多自主，并不直接决定人是否在循环里——输出格式才是。
如果你正在搭一套 Agent 工作流（不论是 Claude Code、CodeBuddy 还是自研的 Coding Agent 平台），值得问的不是"我们的 Agent 自主性能不能再高一档"，而是：
- 它的输出能让我点开吗？
- 它的输出能让我改吗？
- 它的输出能让我把改动一键回灌成下一轮 prompt 吗？
三个问题里少一个，循环就会断在那一个环节。三个都有，HTML 就成了那块"能让你站进去的画布"。
延伸阅读：
- HTML 对 Agent 的不合理有效：从文字墙到可操作工件的输出格式革命 · 本仓库 2026-05-13 · 基于 Thariq 的 demo 合集，给出 Agent 输出格式选型决策树
- 百万行 monorepo 里的 Claude Code：Anthropic 官方拆解的 7 个扩展点与 3 大部署模式 · 本仓库 2026-05-17 · CLAUDE.md / Hooks / Skills / Plugins 这一整套 harness 的扩展点解读
- The unreasonable effectiveness of HTML — examples · Thariq 的原始 9 大类 × 20 个 demo 集合
- GitHub: anthropics/html-effectiveness · 官方示例库
「真诚赞赏，手留余香」
爱折腾的工程师
真诚赞赏，手留余香
使用微信扫描二维码完成支付
