Simon Willison 建议用 details 标签折叠 AI 生成的冗长 PR 描述

我最近对项目所做的大部分改动，都是以 Claude Code 或 Codex 为我创建的 PR 形式出现的。PR 是我的工作单元——我用它把提交打包在一起，反复迭代直到功能完成，记录决策，最后合并成果。如今的 coding agent 写 PR 描述很在行。

它们把工作描述得太好了

问题就在于它们太擅长了。agent 写的 PR 描述准确又全面，会说明问题、详细的解决方案，以及验证步骤。信息量太大，让人难以消化。

这未必是垃圾内容，但读起来就像垃圾内容！

AI 写的 PR 很容易辨认，和其他形式的 AI 写作一样，我的第一反应可以概括为：“我才不会把这一整篇都读完。”不管信息多准确、多有用，我一想到读它花的时间比写它的作者还长，就立刻没了兴趣……哪怕那个作者就是我自己！

我想要人类编辑的判断。我希望有人为这个 PR 稍微多想一会儿，给我一段经人认可的引言，帮我在高层次上理解这个 PR 是做什么的，值不值得我多花点注意力。

我想我找到了一个省力又合适的办法。

把大部分内容藏进 details/summary

这些 HTML 元素会渲染成一个折叠的标题（即 summary），点击可以展开查看正文。代码如下：

details>
  summary>Claude Opus 5.5summary>
  h2>The hookh2>
  Plugins implement code>register_agent_reference_types(datasette)code>...
details>

渲染出来是这样的：

关键在于，GitHub Markdown 支持这些标签。你可以把它们直接放进 issue 评论或 PR 描述里，GitHub 会隐藏 details 部分，只显示 summary 和展开箭头。

我已经开始在 AI 生成的 pull request 里用这个办法了。

我的 PR 开头段落会经过精心挑选，作为对整体情况的高层次说明——也就是人类读者了解状况所需的最短文字。

有时我还会放一张截图，因为图片往往是快速展示新功能的最佳方式。

完整的 agent 写的小作文则放在后面的 details 里。summary 我用模型名，通常还加上 effort 等级，让读者一眼就明白怎么回事——比如“Claude Opus 5.5 Medium”。

现在我的 PR 感觉没那么敷衍了！信息全都还在，但读者扫一眼就能看到顶部经人筛选的信息，而不会被 agent 写的好几段细节搞得眼花。

开头不一定都是我自己写的——有时 agent 已经给出了我需要的内容，只是埋在海量文字里。我对读者的承诺是：这段简短的开头代表我作为人的判断，即哪些内容确实值得他们花时间。

以下是我最近用这个模式的一些例子，包括我用的开头：

• datasette PR #3052：将行页面重新设计为字段的垂直列表——“行页面原本把单行显示为只有一行的表格。对于宽表格，比如有 46 列的 GitHub repos 表，这会导致内容向右滚得很远，页面大部分区域留白。”（然后附截图）
• datasette PR #3043：分页栏显示当前页包含哪些行——“跨多页的表格页面现在能清楚显示你所在的位置，并在页面顶部和底部都提供导航。”（附截图）
• datasette PR #3042：通过小型加载器按需加载 edit-tools.js——“edit-tools.js（约 220KB）原本会在每个表格、行和数据库页面加载，即使对无权编辑的用户也是如此。现在只对有权编辑的用户加载，并且是在他们首次与编辑功能交互时（包括鼠标悬停在编辑链接上）才加载。”
• datasette-agent PR #51：register_agent_reference_types 插件钩子——“让插件可以通过新的 register_agent_reference_types(datasette) 插件钩子，在聊天编辑器的 # 标记中添加自己的条目类型。”——见上图。
• llm PR #1838：添加 llm openai endpoint add/list/remove/path 命令——“添加了管理 extra-openai-models.yaml 中记录的命令，这样 OpenAI 兼容的 endpoint 可以从命令行保存，而不必手动编辑 YAML。”——然后附上 --help 输出。

记忆口诀

我以前总记不住这两个标签的顺序——到底是 details 在前还是 summary 在前？

有两个技巧帮到了我。

第一，也最明显：summary 显然就是概括 details 内容的那部分。它是可点击展开的那行文字的标签——这个元素必须包住其他所有内容。

更好的技巧是，永远把这两个标签称作“details-summary”。

“details-summary”是两个音节加三个音节，念起来比“summary-details”的三二组合顺口多了。

把“details-summary”大声念几遍，你就再也不会记错标签顺序了。

（我还是希望 GitHub 能在 Markdown 编辑器里加个按钮——一来省得我在手机键盘上费劲打字，二来也帮更多人知道 GitHub 有这个功能。）

标签：github, html, markdown, ai, generative-ai, llms, ai-assisted-programming, coding-agents