跳转到内容
主站 新闻 控制台

用 `<details><summary>` 把你的垃圾 PR 描述折叠起来

· Simon Willison
技巧LLM

最近,我对项目所做的大部分修改,都是以 Claude Code 或 Codex 为我创建的 PR(Pull Request,拉取请求)形式呈现的。PR 是我的工作单元——我用它们将多个 commit 打包在一起,不断迭代直至功能开发完毕,记录各项决策,最后合并完成的成果。如今的代码智能体(coding agent)非常擅长撰写 PR 描述。

它们太擅长描述工作了

问题在于它们过于擅长了。智能体生成的 PR 描述既准确又详尽。它会描述问题本身、详细的解决方案以及为验证该方案所采取的步骤。这需要吸收的信息量太大了。

它倒不一定是劣质内容(slop),但读起来却很像!

你一眼就能认出哪些 PR 是 AI 写的。和其他形式的 AI 写作一样,我的第一反应通常可以概括为“太长不看”(I’m not reading all of that)。不管这些信息有多准确或多有用,一想到我阅读它所花的时间可能比作者写它花的时间还要长,我立刻就没了兴趣……即便那个主导作者就是我自己!

我想要的是人工的编辑判断力。我希望有人能对这个 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 PR 截图。文本“Claude Opus 5.5”旁边有一个黑色小箭头。点击该文本可在 PR 正文中展开完整描述。

最关键的是,GitHub Markdown 原生支持 <details><summary>。你可以直接把这些标签写入 Issue 评论或 PR 描述中,GitHub 就会自动隐藏详细内容,只显示摘要行和一个展开箭头。

我已经开始在自己生成的 AI PR 中使用这种方法了。

我 PR 的开篇第一段会经过精心挑选,作为对整体变动的宏观解释——用人类读者能在最短时间内读完的文本,帮助他们快速了解概况。

有时我还会附上一张截图,因为图片往往是快速说明新功能的最佳方式。

随后,由智能体撰写的完整“长篇大论”会被包裹在 <details><summary> 中。我通常会将模型名称(往往还附带思考程度/努力级别)作为 summary 的内容,从而清晰明了地交代背景——例如“Claude Opus 5.5 Medium”。

现在我的 PR 读起来完全没有那种 AI 劣质感了!所有信息依然完好保留,但读者只需扫一眼就能获取最核心的、经由人工筛选的关键信息,而不必面对智能体写出的数段详述而感到眼花缭乱。

我并不总是亲自撰写简介——有时智能体已经给出了我想要的内容,只是被淹没在了大量文本之中。我对读者的承诺是:这段简短的开篇代表了我作为人类的判断力,明确告知什么内容才真正值得他们花时间看。

以下是我最近使用这种模式的几个例子,附带了我所使用的开篇导言:

记忆技巧

我以前老是记不清这两个标签的先后顺序——到底是 <details><summary> 还是 <summary><details>?

有两个小技巧帮到了我。

首先,也是最明显的一点,<summary> 显然是用来概括(summarize)详细内容的部分。这是那行可以点击展开的文本对应的标签——因此,<details> 元素必然要包裹其余的所有内容。

另一个更好的技巧是,始终把这两个标签念作“details-summary”。

“details-summary”是两个音节后面跟着三个音节。比起“summary-details”这种三加二的组合,读起来顺口得多。

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

(我依然希望 GitHub 能在其 Markdown 编辑器中为此加个按钮——一方面能省去我在手机键盘上费力敲代码的麻烦,另一方面也能让更多 GitHub 用户知道这个功能的存在。)