把 AI 生成的冗长 PR 描述藏进 `<details><summary>` 后面

我这些天对自己项目做的大部分改动，都是 Claude Code 或 Codex 替我开 PR 的形式。PR 是我的工作单元——我用它把提交打包在一起，反复迭代直到功能完成，记录决策，然后合并最终结果。今天的编程智能体非常擅长写 PR 描述。

它们太擅长描述工作了#

问题就在于它们太擅长了。智能体写的 PR 描述准确而全面。它会描述问题、详细的解决方案，以及验证所采取的步骤。要吸收的信息太多了。

它未必是垃圾（slop），但读起来像垃圾！

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

我想要人类编辑的判断。我想有人为这个 PR 稍微多想一会儿，给我一段经人类认可的引言，帮我在高层次上理解这个 PR 是干什么的，以及它是否值得我投入更多注意力。

我觉得我找到了一个省力又感觉对路的办法。

把大部分内容藏进 details/summary#

HTML 的 <details><summary> 元素会渲染成一个可折叠的标题（summary），展开后可以看到更长的文本。代码长这样：

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

渲染出来是这样：

关键在于，GitHub Markdown 支持 <details><summary>。你可以把这些标签直接放进 issue 评论或 PR 描述里，GitHub 会把详情隐藏起来，只显示摘要和一个展开箭头。

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

我的 PR 开头段落会被精心挑选，充当对整个改动的高层解释——这是人类读者为了快速进入状态所能读到的最短文字。

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

随后，完整的智能体长文放在 <details><summary> 里。我用模型名、通常还有推理强度作为 summary，让人一眼看清是什么情况——比如“Claude Opus 5.5 Medium”。

现在我的 PR 感觉没那么草率了！信息仍然全都在，但读者扫一眼就能得到顶部由人筛选过的信息，而不会被智能体写的多段细节搞得眼花。

开头也不总是我自己写的——有时候智能体已经把我需要的东西写好了，只是埋在其他文字的大量内容里。我对读者的承诺是：这段简短的开头代表我作为人类的判断，即哪些内容确实值得他们花时间。

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

• datasette PR #3052：把行页面重新设计为字段的垂直列表——“行页面把它的单行显示成一张单行表格。对于宽表格，比如 46 列的 GitHub 仓库表格，这会一路向右滚动，页面大部分都是空白。”（然后是截图）
• 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 兼容端点可以从命令行保存，而不必手工编辑 YAML。”——然后附上复制的 --help 输出。

助记法#

我以前总记不住标签的顺序——是 <details><summary> 还是 <summary><details>？

有两个技巧帮到了我。

首先，最明显的是：summary 显然就是概述 details 的那部分。它是你那段可点击展开的文字对应的标签——而 <details> 元素必须包住其他所有内容。

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

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

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

（我还是希望 GitHub 能在他们的 Markdown 编辑器里加一个按钮——一部分是为了让我不必在手机键盘上费力打字，一部分也是为了向更多 GitHub 用户宣传这个功能的存在。）