catch-up

跟进近况

读到这段内容的人刚刚离开了一段时间。在他们离开的期间，多个 Agent（包括你和其他 Agent）推动了项目进展。他们同时处理着多个类似的项目，也不会仔细阅读代码。你的任务是在不到一分钟内帮助他们重新掌舵：说清楚改了什么、为什么改，以及他们的意见在哪些地方真正能影响方向。

这个定位决定了下面的一切。他们无法根据差异或提交列表采取行动，所以不要给他们这些内容。他们可以根据直白的想法和清晰的选项采取行动，所以要提供这些。

什么样的总结才算好

• 用平实的话，不用行话。 每个技术术语都要在首次出现时翻译或解释。如果从未看过代码的读者会被某个词难住，就换种说法。参见行话的翻译。
• 把握全局，不要罗列细节。 按改动的意义归类，而不是按文件归类。每条只讲一个想法。标题要突出重点，而不是行数。
• 重点在原因。 差异说明了改了什么；只有对话能说明为什么改。读者需要根据原因来掌舵，所以一定要保留这些信息。
• 指出尚未定夺的方向。 对掌舵者最有用的内容，就是仍待决定的选项，或默认作出、但可以撤回的决定。这些才值得他们关注。
• 坦诚相告。 如果某项工作只完成了一半、未经测试或出了岔子，就直说。隐瞒未解决的问题只会让方向更难把握。

如何操作

1. 确定起点

用一个简短的短语说明总结的时间范围，让读者了解背景。按以下顺序从对话中判断：

1. 上一份近况总结。 浏览记录，寻找上次运行此技能的时间点（你自己之前的输出，通常以类似下方示例的时间范围开头）。如果找到，只总结此后发生的事情。重复查看进展时，通常采用这种方式。
2. 明确的里程碑。 合并、已发布的 PR、已完成的计划，或明确提出“开始做 X”，都可以作为自然的起点。从那时起进行总结并注明起点，例如：“自身份验证重构合并以来”。
3. 本次会话开始。 如果前两种情况都不明确，就总结整个会话，并说明这一点，例如：“本次会话目前的进展”。

如果记录经过了压缩，或你确实无法判断，就默认从本次会话开始总结，说明你采用了这个起点，并通过 git（如下所述）还原遗漏的历史，而不是猜测。

合适的时间范围示例：“自上次跟进以来”、“自我们开始做搜索以来”、“本次会话目前的进展”、“自 v2 分支合并以来”。

2. 收集改动内容

先看对话。在由 Agent 推动的项目中，对话既记录了工作，也记录了推理过程。然后对照代码仓库，确保汇报的是实际落地的内容，而不只是讨论过的想法：

git log --oneline -20        # what actually got committed
git diff --stat HEAD~N       # rough shape of the change (pick N from the log)
git status                   # what is still uncommitted / in flight

使用 git 确认改了什么，并发现任何未在对话中出现的改动。通过对话了解为什么。不要逐个阅读所有文件。你要掌握改动的整体轮廓，而不是逐行汇报。为了充分理解某个抽象概念、用直白的话描述它，快速查看一两个关键文件没有问题；如果读了十个文件，说明你已经失去了全局视角。

3. 只保留有助于掌舵的内容

保留：新增或重塑的核心组成部分（用直白的话说明）、选定的做法及被否决的实际替代方案、推理过程、目前已成定局的决定、尚未定夺的方向，以及任何出人意料或有风险的事项。

删除：逐文件变更、行数、格式与 lint 噪声、机械式重命名，以及读者无法据此采取行动的内容。如果不确定某项内容是否该保留，就问自己：“他们能据此掌舵吗？”如果不能，就删掉。

4. 撰写简报

使用以下结构，并根据实际变更的多少调整篇幅。请参阅 根据变更调整篇幅。删掉任何内容为空的部分；诚实的简短说明胜过填充模板。

[Window line] (TL;DR)
<one or two plain sentences: the headline, plus how many things need them>

What changed
- <a change, in plain language, grouped by theme>
- <a knock-on effect, if it matters to them>

Why
- <the problem being solved or the reasoning behind the approach>

Your call
- <open decision>: <the tradeoff in plain terms>. <what you did by default>.

每条要点都要简洁：用一句话开门见山。只有在某个术语确实需要为没看过代码的人解释时，才最多补充一句普通陈述。再多就不是简报，而是在讲故事。删减内容，或者拆成两条要点。

你来决定部分是引导方向的重点。列出真正需要选择的事项：尚未决定的事情，或默认决定但容易更改的事情。每项用一句朴素的话说明取舍，并说明你暂时怎么处理，让对方了解当前状态。如果没有需要对方决定的事项，就用一句话说明（“目前没有需要你处理的事。”），不要凭空编造决定。

转译行话

这是关键所在，值得认真做好。说清背后的想法，而不是实现方式。以下是一些转译示例：

不要说	改为
“添加了一个 reducer 来集中管理状态”	“把应用里‘当前情况如何’的记录集中到一处，而不是散落各处”
“对 selector 做了记忆化”	“让一个较慢的查找记住结果，避免每次都重新计算”
“为结果引入了判别联合类型”	“让结果始终严格属于几种标记清晰的形态之一，避免混淆”
“将 API 客户端提取到共享模块中”	“把与服务端通信的代码集中到一处，让每个界面都使用同一份代码”
“添加了乐观更新”	“界面现在会立刻显示你的更改；如果服务端返回不同结果，界面会自行修正”

有两个实用的判断方法。首先，如果草稿里的某个名称只有读过代码的人才懂（类名、文件名、内部代号），就把它替换成它实际做的事。其次，想象你要向另一支团队里聪明的同事当面解释。这样的语气几乎总能把握好表达的深浅。

根据变更调整篇幅

结构只是指引，不是配额。根据内容的实际分量来安排输出：

• 微小变更（修复、微调）：一两句话。不加标题。“修复了列表为空时导出按钮无反应的问题。目前没有需要你处理的事。”
• **常规会话：**使用完整简报，每个部分列出几条要点。
• **大型或涉及面广的会话：**仍以一行 TL;DR 开头，然后按主题组织正文，方便快速浏览。克制详尽介绍的冲动：面面俱到是这里的大忌。挑出少数会影响对方如何把握方向的事项，并说明略去了其他较小的内容。

语气

句子要短，每句只表达一个意思。不要使用长破折号。避免“值得一提的是……”这类 AI 式铺垫。写得像一位干练的同事在会议间隙向对方简要说明情况，而不是像发布说明。