AI 写的 PR 太长?用折叠区保留细节

Simon Willison7 天前

问题不一定是写得差,而是读起来太累

Claude Code、Codex 等编程代理可以为拉取请求(PR)生成完整的描述:问题是什么、如何解决、做了哪些验证,通常都能交代清楚。

但完整也可能成为阅读负担。面对多段 AI 生成的说明,即使内容准确、有用,读者也可能下意识地跳过。

这时真正需要的不是更多文字,而是经过人工判断的简短开场:这个 PR 做了什么?为什么值得继续看?

把人工摘要放前面,把详细说明折叠起来

GitHub Markdown 支持 HTML 的 <details> 和 <summary> 标签。可以直接将它们放进 PR 描述或 Issue 评论中,默认只显示一行可点击的标题,展开后才显示详细内容。

一个实用的 PR 描述结构是:

  1. 开头用尽量短的文字说明核心变化,由人确认哪些信息值得读者首先看到。
  2. 必要时附上截图,直观展示界面或功能变化。
  3. 将 AI 生成的完整说明放入折叠区,保留问题背景、实现细节和验证步骤。
  4. 在折叠标题中标明模型名称,也可以注明推理强度,让读者清楚这部分内容由什么工具生成。

结构示意:

这里放经过人工确认的简短说明,概括本次改动及其目的。

<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> 之前。

这套做法保留了完整说明,也为读者提供了一个更简洁的阅读入口。

评论

请登录后发表观点

暂无数据