问题不一定是写得差，而是写得太多
Claude Code、Codex 等编程智能体可以为拉取请求（PR）生成完整描述：要解决什么问题、方案如何实现、做过哪些验证，都能交代清楚。
但详尽不等于易读。即使信息准确、有用，连续多段说明也可能让读者产生“太长，先不看”的反应。
对于在写好标智库交流 AI 编程实践的开发者，这也是一个值得关注的问题：生成说明很容易，替读者筛选重点仍需要人工判断。
读者首先需要知道的通常是：这个 PR 改了什么，为什么要改，是否需要进一步查看细节？一个低成本的处理方式是：保留完整描述，但不要让它占据第一屏。
用折叠区把描述分成两层
GitHub 支持在 Markdown 中使用 HTML 的 <details> 和 <summary> 标签。在 PR 描述或 Issue 评论中，可以用它们创建可点击展开的折叠区。
PR 描述可以分成两层：
- 开头放人工确认的概览：简短交代用途和关键变化，必要时附上截图。
- 后面折叠完整的 AI 说明：保留问题背景、实现细节和验证步骤，供需要的人展开阅读。
下面的模板可以直接复制，再按实际改动填写：
这里放经过人工确认的简短说明，交代这个 PR 的用途和关键变化。 <details> <summary>AI 生成的完整说明（填写模型名称及推理强度）</summary> ### 问题 这里放详细的问题描述。 ### 实现方案 这里放具体改动与设计说明。 ### 验证 这里放已完成的验证步骤。 </details> 折叠时，这一区域只显示 <summary> 中的文字和展开控件；点击后，才会显示内部的完整说明。摘要行也可以注明实际使用的模型名称及推理强度，交代这些文字的生成方式。
注意保留 <summary> 后、正文前的空行，以及正文与 </details> 之间的空行，方便 GitHub 正确渲染内部的 Markdown。
重点不是删除细节，而是让读者决定何时查看细节。
开场概览应该写什么？
不必复述全部实现过程。优先写用户能感知的变化，或者直接交代问题与解决方式。
下面几项 Datasette 改动，展示了哪些信息适合放在开头。
界面调整：先解释旧界面哪里不好用
一项行详情页改动，将单行表格改成纵向字段列表。
适合放在概览中的信息是：旧页面把一条记录显示为只有一行的表格；当记录来自包含 46 列的 GitHub repos 表时，内容会向右延伸很远，同时留下大量空白。
读者先理解旧界面的问题，再看新布局，就更容易判断改动的意义。这类变化也适合配合截图说明。
导航改进：直接说明使用体验的变化
一项分页栏改动可以概括为：对于跨越多页的表格，现在能更清楚地看到当前所在位置，而且页面顶部和底部都提供导航。
这段话不需要解释分页组件如何实现，就已经交代了用户会遇到什么变化。
加载优化：说清对象、条件和触发时机
一项脚本按需加载改动的关键信息是：约 220 KB 的 edit-tools.js 此前会在每个表格页、行详情页和数据库页加载，即使用户没有编辑权限。
调整后，只有具备编辑权限的用户首次与编辑功能交互时才会加载，包括鼠标悬停在编辑链接上的情况。
这里值得优先展示的，是加载对象、权限条件和触发时机，而不是整个实现过程。
人工把关，不等于必须亲手重写
开场概览也可以从智能体已经生成的文字中挑选，不一定要从头写一遍。
关键是：有人确认过，这几句话确实值得读者优先阅读。 同样，放进折叠区也不意味着完整说明可以免于核对；尤其是验证部分，应如实填写已经完成的检查。
人工判断负责确定重点，折叠区负责保留完整信息。两者解决的是不同问题。
记住标签顺序
-
<details>是外层，包住整个可折叠区域。 -
<summary>放在里面，提供可点击的摘要文字。
记住“外层是详情，内层有摘要”，就不容易写反。
下次提交 AI 辅助生成的 PR 时，可以先做一个小调整：第一屏只留下人工确认的重点，把其余说明放进折叠区。概览负责让人看懂变化，细节负责支持进一步审阅。
