Simon Willison:用 details/summary 折叠 AI 生成的 PR 描述,把人工判断放在最前面
来源Simon Willison查看原文
速览
- AI 写的 PR 描述准确全面,但篇幅过长反而让人不想读
- 用 details/summary 折叠长文,开头只留人工筛选的简短说明
- summary 标注模型名与 effort 级别,让读者知道内容来源
- GitHub Markdown 原生支持这组标签,可直接用在 PR 和评论里
- 作者强调开头短文代表他的人工判断,即哪些内容值得读者花时间
- 记忆口诀:念作 details-summary,两音节加三音节更顺口
- 他希望 GitHub 加一个编辑器按钮来插入这组标签
Simon Willison 在个人博客中讲述了他处理 AI 生成 PR 描述的一个做法。他现在的项目改动大多由 Claude Code 或 Codex 以 PR 形式提交,这些 agent 写的 PR 描述准确、全面,涵盖问题、解决方案和验证步骤,但正因为信息量太大,读起来像「slop」,他的第一反应是「我不会全读」。他的解决办法是:在 PR 开头写一段经过人工筛选的高层说明,有时配一张截图,然后把 agent 写的完整长文放进 GitHub Markdown 支持的 <details><summary> 折叠块里,summary 处标注模型名和 effort 级别,例如「Claude Opus 5.5 Medium」。他给出了 datasette、datasette-agent、llm 等项目的多个实际 PR 例子,并分享了一个记忆标签顺序的口诀:把这两个标签念作「details-summary」,两音节加三音节更顺口。他还希望 GitHub 在 Markdown 编辑器里加一个按钮来插入这组标签。
关键事实
- Willison 表示他近期的项目改动大多以 Claude Code 或 Codex 提交的 PR 形式出现,PR 是他的工作单元
- 他认为 agent 写的 PR 描述准确且全面,但信息量过大,读起来像 slop,他的本能反应是「我不会全读」
- 在 GitHub Markdown 中受支持,可直接写进 issue 评论或 PR 描述,渲染为可折叠的标题
- 他的做法是开头写一段人工筛选的高层说明,有时配截图,完整 agent 长文折叠在 details 块内
- summary 处标注模型名和 effort 级别,例如「Claude Opus 5.5 Medium」
- 他举的例子包括 datasette PR #3052、#3043、#3042,datasette-agent PR #51,llm PR #1838
本站视角
这件事的影响面比它看起来大。直接受影响的是所有在 GitHub 上用编码 agent 提 PR 的开发者,尤其是同时维护多个开源项目、每天要审大量 AI 生成 PR 的维护者。当 agent 把写描述的成本降到接近零,PR 描述的平均长度会迅速膨胀,审阅者的阅读负担反而上升,这是一种典型的成本转移:写的人省了时间,读的人多花了时间。Willison 的方案之所以值得跟进,是因为它没有试图让 agent 少写,而是用折叠把「摘要层」和「细节层」分开,并把摘要层明确标为人工判断的产物,这实际上是在 AI 生成内容里重新引入编辑责任。我们认为这个模式可以推广到 code review 评论、issue 模板、甚至内部文档,凡是 agent 大量产出文本的地方都需要类似的「人工摘要 + 折叠全文」结构。需要观察的是,这种做法依赖作者自律:如果开头那段也交给 agent 写,折叠就只是把 slop 藏起来,读者点开前仍无法判断值不值得读。另外,原文只是个人经验分享,没有数据支撑「折叠后审阅效率提升」这类结论,读者不宜把它当成经过验证的最佳实践。
背景与影响
随着 Claude Code、Codex 等编码 agent 普及,开发者让 agent 直接开 PR 已成常见工作流。agent 擅长写结构化、面面俱到的说明,但这类文本与人类手写 PR 描述在阅读体验上差异明显:信息密度高、篇幅长,读者容易产生「AI 味」的排斥感。Willison 的做法本质上是在 agent 产出与人类阅读之间加一层编辑筛选,把「值不值得读」的判断交回给人,同时不丢失 agent 记录的细节。这对使用 GitHub 协作、且已大量引入编码 agent 的团队有直接参考价值:PR 描述的可读性正在成为新的协作成本,而 HTML 折叠标签是一个零成本的缓解手段。
本文由 AI 辅助整理自公开信源,事实部分以原文为准;「本站视角」一节为编辑部判断,欢迎指正。版权归原作者所有,如有异议请联系我们。