给AI生成的PR说明加一层人工摘要

AI 写的 PR 描述可能准确、完整，却让人懒得读。Simon Willison 给出的办法很简单：开头只留一段经过人工筛选的说明，把模型生成的长篇细节收进 <details><summary> 折叠区。

这个调整值得程序员看几分钟，因为它处理的是 AI 编程里越来越常见的问题：生成说明很容易，审阅者的注意力却有限。作者想保留完整记录，同时让读者快速判断，这个改动是否需要继续看。

为什么描述越完整，反而越难读

作者现在的大部分项目改动，都来自 Claude Code 或 Codex 创建的 PR。他把 PR 当作工作单元：归拢提交，持续迭代到功能完成，记录决策，最后合并。

在这套流程里，代理很擅长写说明。问题是什么、方案如何实现、做过哪些验证，它都能交代清楚。但这些内容一起铺开，读者首先感受到的往往是阅读负担。

作者甚至会对自己驱动代理生成的描述产生抵触：读完这些文字，可能比发起者生成它们花的时间还长。

所以，标题里的「slop」不能简单理解为内容有错。作者也承认，这些描述未必低质，只是读起来很像流水线产物。

完整记录解决了信息留存，人工筛选才解决读者先看什么。

他希望 PR 开头能体现人的判断：这个改动做了什么，为什么需要它，是否值得进一步投入注意力。这段话可以由人写，也可以从代理生成的内容里挑出来；关键在于有人确认，它确实值得读。

折叠区怎么放，才能让信息各就各位

作者使用的结构只有两层：开头放最短的、足以帮助读者理解改动的说明，必要时配截图；后面再放完整的代理描述，并默认折叠。

下面这段代码负责把详细说明收起来，只露出可点击的模型名称：

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

要看的是 <summary> 所在的位置：它嵌在 <details> 里面，提供展开入口，其余内容都由外层 <details> 包住。

GitHub Markdown 支持这两个 HTML 元素，可以直接放进 PR 描述或 issue 评论。渲染后的效果如下：

作者会用模型名称，有时再加推理投入级别作为折叠标题，例如 Claude Opus 5.5 Medium，让读者知道这部分文字由什么模型生成。

这里的模型名是原文示例，并不是文章对模型能力的评测。

记标签顺序也很直观：summary 是对详细内容的概括，因此必须放在 details 内部。作者还建议把组合固定念作「details-summary」，用语序帮助记忆。他希望 GitHub 编辑器增加对应按钮，方便在手机上输入，也让更多人知道这个功能。

一段好开头，应该交代到什么程度

原文里最有参考价值的，是作者实际采用的几条 PR 导语。它们没有统一套模板，但都让读者迅速理解改动的用途。

datasette PR #3052 把行详情页改成字段纵向列表。导语先解释旧界面的具体问题：单条记录被放进只有一行的表格，遇到包含 46 列的 GitHub 仓库表时，内容向右延伸很远，页面大部分区域却空着。再接截图，改动的理由就很清楚。

datasette PR #3043 调整分页栏，开头只交代用户能感知的变化：现在可以看出当前展示哪些行，而且页面顶部和底部都能翻页。

datasette PR #3042 则保留了判断性能收益所需的细节：edit-tools.js 约为 220KB，之前在每个表、行和数据库页面加载，即使用户没有编辑权限。改动后，只有具备编辑权限的用户首次与编辑功能交互时才加载，包括鼠标悬停在编辑链接上。

另外两条导语直接点明扩展入口和操作方式。datasette-agent PR #51 通过 register_agent_reference_types(datasette)，让插件为聊天输入框的 # 标记增加条目类型；llm PR #1838 增加 llm openai endpoint add/list/remove/path 命令，用于管理 extra-openai-models.yaml 中的记录，省去手工编辑 YAML，后面附上 --help 输出。

这些例子的共同点是：先回答改动为什么有用，再让实现和验证细节等待需要它们的读者。

我的判断

我赞成人工筛选开头、完整保留细节的做法。相比要求 AI 一律少写，它能兼顾快速浏览和后续追溯；相比直接贴上长篇说明，它也明确了提交者应该承担的编辑责任。

但作者给出的证据是自己的使用体验和几个 PR 实例。他没有提供阅读耗时、审阅效率或缺陷发现率的对照数据。「感觉没那么潦草了」可以作为个人反馈，不能直接推导成团队效率提升。

另一个前提是，开头真的有人把关。如果只是让代理再自动生成一句摘要，人工判断这一环仍然缺席。折叠也只是展示方式，权限变化、兼容性影响等会左右合并决策的信息，应该出现在读者容易看到的位置。

折叠可以降低浏览负担，不能替代审阅。

对已有严格 PR 模板的团队，这个方案适合用来收纳补充说明。是否采用，仍要看团队需要审阅者默认看到哪些内容。

能拿来做什么

• 给 Claude Code 或 Codex 创建的 PR 增加一次人工编辑：开头用一段话说明具体问题和改动后的行为，再把完整说明放进折叠区。
• 前端界面改动可以参考作者的做法，在开头说明旧页面的问题并配截图，让读者先理解视觉和交互变化。
• 遇到资源按需加载一类改动，导语保留文件大小、加载对象和触发条件。原文的 220KB、编辑权限和首次交互，比笼统写「优化性能」更有判断价值。
• 给 CLI 或插件扩展写 PR 时，开头保留真实命令、API 和配置文件名；需要展示用法时，再附 --help 输出，方便读者继续核对。