AI 写的 PR 太长?用折叠区保留细节
Simon Willison7 天前
问题不一定是写得差,而是读起来太累
Claude Code、Codex 等编程代理可以为拉取请求(PR)生成完整的描述:问题是什么、如何解决、做了哪些验证,通常都能交代清楚。
但完整也可能成为阅读负担。面对多段 AI 生成的说明,即使内容准确、有用,读者也可能下意识地跳过。
这时真正需要的不是更多文字,而是经过人工判断的简短开场:这个 PR 做了什么?为什么值得继续看?
把人工摘要放前面,把详细说明折叠起来
GitHub Markdown 支持 HTML 的 <details> 和 <summary> 标签。可以直接将它们放进 PR 描述或 Issue 评论中,默认只显示一行可点击的标题,展开后才显示详细内容。
一个实用的 PR 描述结构是:
- 开头用尽量短的文字说明核心变化,由人确认哪些信息值得读者首先看到。
- 必要时附上截图,直观展示界面或功能变化。
- 将 AI 生成的完整说明放入折叠区,保留问题背景、实现细节和验证步骤。
- 在折叠标题中标明模型名称,也可以注明推理强度,让读者清楚这部分内容由什么工具生成。
结构示意:
这里放经过人工确认的简短说明,概括本次改动及其目的。
<details>
<summary>模型名称与推理强度</summary>
<h2>实现细节</h2>
<p>这里保留编程代理生成的详细说明。</p>
<h2>验证步骤</h2>
<p>这里保留相关验证信息。</p>
</details>
这样做并不是删除细节,而是将信息分层:读者先了解核心变化,需要深入时再展开阅读。
开场应该写到什么程度?
好的开场不必复述整份技术说明,而应让读者快速理解改动的意义。以下几类表述就很直接:
- 界面调整:表格跨越多页时,现在会明确显示当前页包含哪些行,并在页面顶部和底部提供导航。
- 按需加载:约 220KB 的
edit-tools.js过去会在所有表格、行和数据库页面加载,包括没有编辑权限的用户。改动后,仅在有编辑权限的用户首次与编辑功能交互时加载,包括将鼠标移到编辑链接上。 - 命令行功能:增加管理
extra-openai-models.yaml中记录的命令,让用户可以从命令行保存兼容 OpenAI 的端点,而不必手动编辑 YAML。
界面变化可以配截图,命令行功能可以附上帮助输出。重点是让读者快速理解,而不是把所有细节都塞进第一屏。
人工把关,不等于必须亲手重写
简短开场不一定要由人从零撰写。如果代理已经写出合适的句子,也可以直接选用。
关键在于:开场代表的是人的编辑判断,而不是未经筛选的自动输出。 人需要确认,这确实是读者最值得先看的内容。
如何记住标签顺序?
记住“外层放细节,内层写摘要”即可:
<details>包住整个折叠区。<summary>放在内部,写可点击的标题。- 其余内容放在
</summary>之后、</details>之前。
这套做法保留了完整说明,也为读者提供了一个更简洁的阅读入口。
