show-me：让AI把「我懂了」画出来¶
AI 代码代理最令人疲惫的时刻，不是写不出代码，而是它写了四十行通顺的解释，你读完依然不知道入口在哪、状态归谁、哪一步会写库。show-me 是 HumanLayer 发布的一个 agent skill，核心主张：少解释一点，把系统画出来——而且只画眼前这个问题需要的部分。
[!info] 视频信息 - 频道：为什么叫QQ（Why QQ），6,460 订阅 - 发布：2026-08-22，时长 8:31，9,181 次观看 - Skill 仓库：humanlayer/skills（2.3k stars / 63 forks），show-me 最近一次更新 2026-08-13（Dex Horthy）
目录¶
- 一、核心困境：长篇文本的认知负担
- 二、show-me 的核心理念：最小视图
- 三、五种图形与适用场景
- 四、案例拆解：保存配置后旧值覆盖
- 五、防护警讯：漂亮的图也会撒谎
- 六、标准流程：三阶段检查点
- 七、成本与研究证据
- 八、落地建议与行动清单
- 九、验证与勘误记录
一、核心困境：长篇文本的认知负担¶
AI 编程代理（Claude Code、Cursor、Codex）的解释有一个典型症状：每句话都像是对的，但读完还是不知道 Bug 在哪——入口在哪？数据从哪来？哪一步写数据库？哪一次刷新会把新配置覆盖成旧配置？
代理很勤奋：解释背景、列风险、给建议。但你必须把这些线性文字重新拼成一张系统地图，认知负担全在人这边。
关键洞察：在 AI 辅助开发中，真正费时间的不是产出第一版代码，而是确认副作用（side effect）：
| 副作用类型 | 风险问题 |
|---|---|
| 写数据库 | 会不会重复写入？事务边界在哪？ |
| 发消息/事件 | 顺序对不对？会不会丢失？ |
| 调用外部服务 | 失败了怎么办？有没有重试风暴？ |
这些动作一旦重复、漏掉、或顺序不对，线上问题很难只靠一段文字说明排查出来。
瓶颈迁移：
过去：写代码慢 ──────────> 现在：生成代码快了
│ │
v v
瓶颈 = 生成 瓶颈 = 校验生成结果
（人力编码速度） （副作用确认、边界核对、返工）
二、show-me 的核心理念：最小视图¶
show-me 来自 HumanLayer，本质是给代码代理的一张沟通契约，要求：
- 少写前言、少铺背景
- 眼前要判断什么，就展示和这件事有关的结构
- 复杂问题可以组合几种表示，但反对把所有图形一口气塞给用户——否则只是造出一座新的信息垃圾山
「最小视图」翻成大白话：只画眼前这个问题需要的部分。想判断保存顺序，就别先给一张全系统架构图；想找状态归属，也不必把整个页面树摊开。
图的价值不是显得专业，而是逼代理把隐含判断写出来：
- 能确认的 → 标出证据（哪个文件、哪个函数、哪段运行记录）
- 不能确认的 → 留下问号（「待确认」）
- 最危险的情况：把猜测画成结论。没有来源的箭头，看着再顺，也只能算假设
一句话：AI 可能已经想明白了，但没让你看明白。人需要的是一个可以质疑、可以修改、也可以回到源码验证的结构。
三、五种图形与适用场景¶
3.1 总览对比表¶
| 图形 | 适用问题 | 能回答什么 | SKILL.md 原生支持 |
|---|---|---|---|
| 时序图（Sequence Diagram） | 异步顺序、竞态条件（Race Condition） | 先后顺序对不对，四类顺序检查点 | 是（Mermaid sequenceDiagram） |
| 调用树（Call Tree） | 单一请求的函数路径 | 入口在哪、外部调用在哪、副作用在哪 | 是（缩进文本） |
| 组件树（Component Tree） | 前端状态归属 | 谁拥有状态、谁只负责展示 | 是（含模块边界标注） |
| 浅层文件树（File Tree） | 重构范围、目录职责 | 职责有没有混、边界该不该拆 | 是（目录 + 一句注释） |
| 差异视图 + 风险路径（Review Map） | PR 审查 | 新入口、权限、写库、缓存失效、失败分支串成一条线 | 是（diff 格式） |
3.2 SKILL.md 的原始示例（实测抓取自仓库原文）¶
show-me 的 SKILL.md 对每种图形都给了最小示例，风格是「缩进文本优先，重工具其次」：
调用树（call tree）——直接用缩进表示运行时控制流：
submitForm
createSession
persistPrompt
launchAgent
navigateToSession
浅层文件树（shallow file tree）——每个目录只写一句职责，会话逻辑、网络传输和命令解析如果挤在同一文件，问题立刻显形：
src/
├── commands/ # parses user actions
├── sessions/ # owns session state
└── transport/ # sends API requests
伪代码（pseudocode）——讨论算法/逻辑分支时用：
on(save)
if content is unchanged
return cached result
write new content
return fresh result
差异视图（diff）——当重点是「改了什么」且周围结构已存在时，用 diff 匹配主题：文件布局变更用目录 diff，调用链变更在调用树上打 +/-，状态控制变更在伪代码上打 +/-。
[!tip] SKILL.md 里视频没细讲的两个增量 1. HTML artifact：概念太密、Mermaid 装不下时（视觉 UI、布局、状态对比），写一个聚焦的 HTML 文件（图表/信息图/短幻灯），匹配产品配色与真实数据，然后直接打开给用户。 2. guidance 节：每张图放在它支撑的那段短文字旁边；只保留回答当前问题所需的 calls、files、props、states、boundaries；「可能用一种，可能用几种，不太可能全用——用判断力，别淹没用户」。
3.3 选择决策树¶
你要判断什么？
│
├─ 顺序/时序问题（谁先谁后？会不会竞态？）
│ └─> 时序图
│ └─ 顺序结论还要回到代码 + 运行记录确认
│
├─ 一个请求经过哪些函数？入口/副作用在哪？
│ └─> 调用树
│ └─ 调用树负责定位函数，时序图负责核对先后
│
├─ 页面状态归谁？谁展示谁持有？
│ └─> 组件树
│ └─ 注意：安全边界仍须由后端最终授权
│
├─ 重构范围？目录职责？
│ └─> 浅层文件树（每目录一句职责）
│
└─ 审查一次代码改动（PR）
└─> 差异视图 + 一条风险路径
└─ 只需一份产物时，优先要风险路径
图跟着问题走，才不会变成另一份没人看的文档。小任务只要一条调用路径；复杂任务再补状态、边界和风险图。
四、案例拆解：保存配置后旧值覆盖¶
视频的核心范例：用户保存配置后，页面偶尔又恢复成旧值。这种「偶现」描述最耗人，把它整理成时序图后，四个可验证检查点自然浮出。
（SKILL.md 原文用 Mermaid sequenceDiagram 表达；本笔记按 vault 规范用 ASCII 重绘，内容等价）
用户 页面(本地草稿) 服务端 存储 / 事件总线
│ │ │ │
│── 1.点击保存 ───>│ │ │
│ │── 2.更新本地草稿 │ │
│ │── 3.POST 保存 ───> │ │
│ │ │── 4.写入存储 ─────>│
│ │ │── 5.发布更新事件 ─>│
│ │<──── 6.事件通知 ─────────────────────── │
│ │── 7.拉取最新配置 ──────────────────────>│
│ │<──── 8.返回配置 ────────────────────────│
│ │ 9.返回值覆盖本地草稿 ◀── 问题点在这 │
四个检查点（问题没有被解决，但排查范围被急剧缩小）：
- 数据库提交完成了吗？
- 第 7 步拿到的是主库、缓存、还是副本里的旧值？
- 事件发布发生在提交前还是提交后？
- 页面收到结果时，有没有比较配置版本号？
这个案例的选型说明：真正关心的是顺序，所以时序图比调用树合适——调用树负责定位函数，时序图负责核对先后。最终顺序仍要回到代码和系统实际运行记录确认。
使用过程的转变：
之前：代理「帮我解释」——一段关于缓存、异步写入、刷新时机的长文
之后：代理「帮我缩小排查范围」——四个可以马上检查的问题
五、防护警讯：漂亮的图也会撒谎¶
图是导航，不是盖章。它带你去看风险点，但不能替代源码、测试、日志和运行追踪。
5.1 各类图形的系统性盲区¶
| 图形 | 容易遗漏什么 |
|---|---|
| 静态调用树 | 反射（Reflection）、依赖注入（DI）、事件总线（Event Bus）、动态加载 |
| 时序图 | 超时（timeout）、重试（retry）路径 |
| 组件图 | 藏在全局状态（global state）里的写入 |
5.2 最常见的坑：双写一致性¶
图里把「数据库提交」和「消息发布」画成一个原子动作，现实里它们写入两个独立系统。中间任何一点进程崩溃或通信失败，就会留下不一致数据：
DB 提交 ✓ ────── 进程崩溃 / 网络断 ✗ ──────> 消息发布 ✗
（没有 transactional outbox 一类机制时）
结果：库里有新数据，下游永远收不到通知 —— 图上看不出来
防护规则（要求代理绘审查地图时）：
- ✅ 每个高风险节点附带：文件路径、函数名、测试名、或运行记录标识
- ✅ 无法百分之百确认的关联，明确标注「待确认」
- ❌ 不接受没有来源的箭头——看着再顺也只能算假设
- 「待确认」三个字，比一张自信但错误的图可靠得多
六、标准流程：三阶段检查点¶
整套方法压成一句话：先表示，再实现，再验证。
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 检查点 1 │ │ 检查点 2 │ │ 检查点 3 │
│ 动工前 │ │ 编码中 │ │ 完成后 │
│ 变更契约 │──>│ 决策结构 │──>│ 审查地图 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
说清改动范围/接口/ 讨论超 5 分钟立刻 入口→权限→外部调用
失败处理/验证命令 沉淀为可修改的结构图 →写库→消息→缓存→失败分支
信息不够列待办清单 错误在十几行图里露头 审查人先走风险路径
（别自己补设定） （不用等几百行代码） 再看细节
检查点 1 —— 动工前的变更契约：让代理先说清这次会动哪些文件、公共接口怎么变、调用或状态会经过哪些节点、失败时怎么处理、验证命令怎么跑。信息不够就列待确认项，别自己补设定。
检查点 2 —— 编码中的决策结构，按问题类型选图：
| 正在争论的问题 | 立刻要求画的图 |
|---|---|
| 缓存问题 | 状态与失效路径 |
| 并发问题 | 时序图 |
| 模块归属问题 | 文件边界 |
一次讨论超过 5 分钟，就让代理把争论变成一个能改的结构——还没写几百行代码，错误已经可能在十几行图里露出来。
检查点 3 —— 完成后的审查地图：把新增入口、权限判断、外部调用、写库、发消息、缓存失效和失败分支连成一条风险路径。审查人先走这条路径，再看细节。这也是给别人复查的最友好产物：既能帮你定位，也方便他人复核。
七、成本与研究证据¶
7.1 视频引用的三项研究（本笔记已逐条验证，详见第九节）¶
| 研究 | 核心发现 | 对本方法的含义 |
|---|---|---|
| 控制结构图（CSD）早期实验（IEEE TSE 2002） | 在公共图形库的单模块源码理解任务里，CSD 能改善答题表现 | 只证明具体任务上的帮助，推不出所有图形表示都有效 |
| CodeVoyager（ACm 2026） | 结合调用图 + 控制流图 + LLM 的工具，在代码理解与用户信任上表现更好 | 值得继续验证的方向；样本不大（11 人探索 + 16 人受试者内比较）、工具形态具体 |
| 仓库级上下文文件评估（AGENTS.md，arXiv 2602.11988） | 所测设置中任务成功率没有普遍提高，推理成本平均增加超 20% | 额外提示词不免费；任何代理工作流都要用结果证明自己 |
研究给的许可只是「可以试」，没有替任何团队做结论——团队自己的代码库、协作方式和工具链，还得自己验证。
7.2 成本意识¶
show-me 式的结构化提示词与 AGENTS.md 式上下文文件虽不是同一物，但同属「给代理加额外指令」：
- 额外指令 → 更长的上下文 → 推理成本上升（研究实测 20%+）
- 成功率不保证提升（LLM 生成的上下文文件甚至平均降低约 3% 成功率）
- 结论：这不是「加上就赢」的开关，是要用返工率证明自己的流程
八、落地建议与行动清单¶
团队试点方案：
- 挑一个中等复杂度任务（不是最难的，也不是 hello world）
- 试运行两周
- 复盘两个问题：哪些图真减少了返工？哪些图只是多了一次展示？
- 把有用的留下，把流于形式的删掉
个人行动清单（下次让代理改复杂功能前）：
- 建立事前契约：多文件/架构调整前，指令先限定为「展示调用路径、受影响文件与失败分支」，确认无误后再发编码指令
- 优先索取风险路径：只让代理交付一份产物时，要「入口 → 权限 → 写库 → 缓存/消息 → 失败处理」串联的风险图
- 强制代码凭据：图节点必须标注源码路径与函数名；不确定的关联标「待确认」，杜绝幻觉与过度自信
组织收益：以后争论时，大家能指着同一张图说话——产品问操作会不会重复，工程师回到状态图；审查人说风险高，大家先看调用路径。讨论有了共同落点，也更容易留下记录。
展望：未来的代码代理会更少用长篇文字展示「我理解了」，而是先给一张任务相关的图，再根据反馈继续读仓库。图的一部分来自模型，一部分来自代码分析（类型检查、依赖关系、真实运行记录）；代理负责组织材料，人负责追问：这张图漏了什么？它的证据在哪？这个决定真的能进代码吗？
九、验证与勘误记录¶
| 视频声称 | 验证结果 | 来源 |
|---|---|---|
| show-me 来自 HumanLayer，是一个 agent skill | ✅ humanlayer/skills（2.3k stars / 63 forks），plugins/show-me/skills/show-me/SKILL.md，维护者 dexhorthy（Dex Horthy，HumanLayer 创始人），最近 commit 2026-08-13「add some guidance」 | GitHub 仓库页 + raw SKILL.md |
| 五种图形（时序/调用/组件/文件树/diff 审查） | ✅ SKILL.md 原文证实；且 SKILL.md 还有视频未细讲的：伪代码、Mermaid 组件交互图、HTML artifact、guidance 节（图贴着文字放、别塞全部图形）——此为笔记增量 | raw SKILL.md 全文 |
| 早期 CSD 研究：两组学生实验，公共图形库单模块任务有效 | ✅ 对应 IEEE TSE 28(5) 2002, 463-477（Hansen 等），论文自述为「系列计划实验中的前两组」，与「两组学生实验」吻合 | arXiv 2206.11102 引文 + dl.acm.org 条目 |
| CodeVoyager：11 人探索性研究 + 16 人受试者内比较，调用图+控制流图+LLM 在理解与信任上更好 | ⚠️ 部分验证：论文真实存在（ACM 2026，Y Kim，DOI 10.1145/3742413.3789057），摘要确认「LLM + call graph + control flow graph 辅助代码理解」方向；样本数（11+16）来自视频口述，ACM 全文反爬未能核实 | dl.acm.org 摘要 + ResearchGate 条目 |
| 上下文文件研究：成功率未普遍提高，推理成本平均增加超 20% | ✅ arXiv 2602.11988（Gloaguen 等）：「context files tend to reduce task success rates … increasing inference cost by over 20%」，HN/InfoQ/Reddit 多源一致；InfoQ 补充 LLM 生成文件平均降成功率约 3% | arXiv + InfoQ + Hacker News 47034087 |
| 双写风险需要「事务发件箱」类机制 | 术语确认：transactional outbox 模式是分布式系统标准解法；此为视频作者的工程延伸，SKILL.md 本身无此内容 | — |
| 频道名「为什么叫QQ」 | ✅ webReader/webExtract 元数据均为 Why QQ，6,460 订阅 | YouTube 页面元数据 |
[!note] 素材获取说明 该频道系统性无字幕（Tier 0 不可用）。本次 Tier 2 路线：web_extract 对 YouTube URL 直接返回完整口播字幕（该频道 2026-09-07 起确认的稳定模式），配合用户提供的 Content Insights 大纲交叉比对，无内容缺口。
参考资料¶
- 视频：不能错过的 Skill！/show-me：让AI把「我懂了」画出来（为什么叫QQ）
- humanlayer/skills — show-me SKILL.md 原文
- Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?（arXiv 2602.11988）
- CodeVoyager: Integrating Interactive Visual Aids with LLMs（ACM 2026）
- The effectiveness of control structure diagrams in source code comprehension activities（IEEE TSE 2002，经 40 Years of Designing Code Comprehension Experiments 引证）
- InfoQ: New Research Reassesses the Value of AGENTS.md Files
相关笔记¶
- HN热帖-AI时代程序员的意义危机（同频道：为什么叫QQ，HN 热帖解读）
- 可塑软件-80底座与20定制代码（同频道：可塑软件方法论，AI 时代的代码库结构观）
- Claude-Code-NotebookLM联动完整指南（Claude Code 工作流实践）