Review Handoff

---
name: review-handoff
description: 根据自己的需求背景和一个或多个 CodeUp PR，生成可直接发给同事的 Review 交接内容。用户要“简略 Review 概要”“群里发一段 Review 说明”时直接输出含任务、需求、PR、验收项目、源分支和改动摘要的短版；用户要“Review 文档”“整理 PR 说明”“把背景、根因和修复方案写成 MD”时生成完整 Markdown。两种模式都先核对真实仓库与 diff，只解释有证据的改动，不替 reviewer 下最终通过结论。
---

# Review 交接内容

目标是让同事不用重新考古需求，也不用逐文件猜作者意图，就能快速进入真正的代码审查。输出必须忠于已验证事实，同时让不了解这块业务的人一遍读懂。

## 输入

通常包括：

- 一个或多个 CodeUp PR 链接；
- 需求背景、问题现象或 OA 需求/缺陷 ID；
- 作者判断的根因和修复方案；
- 可选的验收 project ID、源分支、环境、日志、测试和上线信息。

用户可能把元信息粘贴成列表、`diff` 代码块、HTML 转义文本或带断行的链接。先归一化格式，再识别以下字段；没有提供的字段不强行补齐：

```text
任务：T-xxxx
需求：D-xxxx
PR：<仓库或服务> CodeUp #<编号> (<链接>)
验收项目：<project ID>
源分支：<branch>
```

用户可能只给一个或多个 PR，也可能只给零散口述。先从各 PR 描述、关联工作项、提交、真实 diff 和对应仓库恢复可验证信息，不要把能自行获取的内容重新问用户。

只有 PR 无法访问、仓库无法定位，或缺失信息会让文档在“问题是什么/为什么改”上产生两种实质不同的版本时，才请求补充。先自查代码、测试和关联材料，每次只追问一个最上游、最可能改变文档的关键问题；信息足够后立即停止追问。无法验证但不妨碍形成草稿的内容要明确写“待确认”，不能替作者编造。

## 边界

- 用户明确要“简略、概要、短版、直接回复、不生成文件”时，在当前对话输出短版；明确要“完整文档、Review 文档、MD、Markdown、保存到目录”时创建完整 Markdown 文件并返回可点击路径。“发群里、可直接复制”只有在没有指定文件形式时才默认短版；例如“发群里的 Review 文档”仍生成文档。只说“Review 说明”且未限定形式时，默认生成完整文档。
- 不自动修改 PR 描述或向同事发送消息。
- 不修改业务代码，不评论、通过或合并 PR，不 commit、push 或部署。
- 不覆盖同名既有文档。优先遵循仓库已有 `review-docs/`、`docs/` 或同类目录；没有惯例时保存在当前任务工作区，文件名使用 `<需求标识或简短名称>-review.md`。重名时使用明确后缀。
- 不复制 Token、Cookie、凭据、完整 Prompt、大段日志或未脱敏用户数据。
- 输出只解释本次改动及其一个或多个 PR，不混入未来规划、顺手重构或未经确认的改进建议。

## 工作流

### 0. 选择输出模式

先根据用户的交付意图选择一种模式，不把长度偏好反问用户：

- **简略概要**：适合群聊、Review 邀请或 PR 评论前的交接，直接在对话中给出；正文控制在约 150～300 个汉字，元信息不计入。
- **完整文档**：适合让 reviewer 独立理解需求与链路，创建 Markdown 文件；复杂链路可加入具体 Case。

两种模式共享同一套事实核验。简略概要是完整因果链的压缩，不是降低证据标准；信息不足时写“待确认”或省略非关键字段，不用空话凑齐模板。

### 1. 固定 PR 与仓库

1. 解析每个 PR 的仓库、源分支、目标分支、patch set 和 commit。
2. 通过已登录 CodeUp 页面、已配置只读 OpenAPI 或 Git 远端取得真实 diff、PR 描述、提交和 CI 状态。
3. 涉及远端现状时，先检查工作区、分支和 worktree，再 `git fetch`；不要覆盖或清理未知改动。
4. 多仓需求逐个核对，不把一个仓库的改动和验证结果套到另一个仓库。

PR 链接必须放在输出最上方，并明确仓库。完整文档中单仓也使用表格；简略概要中每个 PR 单独一行，方便直接复制。

### 2. 重建作者意图

分别整理以下内容：

- **需求背景**：哪块功能承担什么业务职责，为什么现在需要改；
- **问题描述**：什么条件下、哪一步出现什么问题、造成什么影响；
- **问题根因**：最早哪个值、状态、分支或机制偏离预期，后续消费者为什么把偏离放大成用户可见问题；
- **修复方案**：在哪个关键节点增加、删除或调整了什么逻辑，为什么能截断根因；
- **保持不变**：哪些正常路径、接口合同或既有行为不应被这次修改改变。

作者原先的解释也要用代码和可用运行事实复核。若只能从 diff 推断根因，写“根据已取得的 PR diff 推断”；若根因依赖某环境配置而未验证，写清缺口。交接文档不能用确定语气包装未闭合因果链。

### 3. 压缩改动

完整文档用一张“改动前 / 改动后”表表达关键逻辑。表格按链路节点组织，而不是按文件列表组织：

| 链路 | 改动前 | 改动后 |
|---|---|---|
| 状态写入 | ... | ... |
| 下游消费 | ... | ... |

只有表格无法解释关键判断时才附代码片段，每段只保留必要几行并解释其业务含义。不要贴完整 diff、逐提交流水账或所有改动文件。

简略概要把同一条因果链压缩成三部分：问题或动机、核心改动、Review 重点。每部分一两句，优先写业务结果和第一次发生变化的关键节点；验证信息只有在已取得证据或存在会改变审查判断的缺口时才单列。

### 4. 必要时用一个具体 Case 走通方案

当修改跨越多个方法、服务或状态，单看背景和改前/改后表仍可能“似懂非懂”，或者用户明确要求用例子说明时，在文档中加入一个具体 Case。优先使用脱敏复现、已有测试样例或 PR 中可验证的代表性输入；只能依据代码构造时标注“基于代码静态推演”，不能包装成已经在线上发生的事实。

使用同一份输入对齐展示改动前和改动后：从谁触发、初始输入/状态开始，经过关键方法和判断，直到下游或用户可见结果。每一步注明文件和方法，并用业务白话说明职责；重点指出第一次分叉和状态变化，不重复贴完整 diff。简单单点改动若表格本身已经一眼能懂，可以省略本节。

### 5. 给 reviewer 明确入口

“请重点 Review”只列最需要人判断的事项：简略概要 1～2 项，完整文档 2～4 项，例如：

- 根因和修复点是否对齐；
- 上下游或跨仓消费者是否覆盖完整；
- 正常路径、失败恢复、并发或幂等是否受影响；
- 测试与上线配套是否能证明修改有效。

不要写“请帮忙看看有没有问题”这种没有审查焦点的话，也不要替同事宣布代码已经合理。

### 6. 记录验证边界

区分：

- 已验证：真实 diff、单测/集成测试、复现、日志、配置、CI、部署；
- 未验证：尚未执行但可能改变审查判断的内容；
- 不适用：本改动不涉及的环境或链路，不要为了模板完整虚构验证项。

最新 `main` 不是某环境的部署证明，代码默认值不是当前运行时配置。若只完成静态核验，直接说明。

## 简略概要模板

用户要短版时直接从元信息列表开始，不添加“Review 概要”或其他标题。只保留用户提供或已核实的元信息；任务、需求、验收项目和源分支不是每次都必填。单 PR 使用普通列表；多项目或多 PR 时按项目分组，每组明确对应的 PR、验收项目和源分支，不能把某个项目的信息套到其他 PR。

```markdown
- 任务：`<T-xxxx>`
- 需求：`<D-xxxx>`
- PR：[<仓库或服务> CodeUp #<编号>](<url>)
- 验收项目：`<project ID>`
- 源分支：`<branch>`

改动概要：<问题或改动动机>；<最早的偏离或关键机制>；<本次如何修复，以及正常路径保持什么不变>。

请重点 Review：<最值得 reviewer 判断的 1～2 个风险或契约点>。

验证：<已验证证据；若存在关键缺口则写“待确认：...”>
```

多项目或多 PR 时，元信息改用下面的分组结构，正文仍只保留一份改动概要：

```markdown
- 任务：`<T-xxxx>`
- 需求：`<D-xxxx>`
- `<项目或仓库 A>`
  - PR：[CodeUp #<编号>](<url>)
  - 验收项目：`<project ID>`
  - 源分支：`<branch>`
- `<项目或仓库 B>`
  - PR：[CodeUp #<编号>](<url>)
  - 验收项目：`<project ID>`
  - 源分支：`<branch>`

改动概要：<本次改动的共同目标，以及各项目分别承担的修改>。

请重点 Review：<跨项目契约，以及各 PR 自身最需要判断的风险>。
```

没有验证信息且不存在需要提示的关键缺口时，省略“验证”一行。不要把任务号、需求号、分支名、project ID 或 PR 标题本身推断成改动内容；改动概要仍须来自 PR 描述、真实 diff、关联工作项或用户提供且可核对的事实。

## 完整文档模板

用户要完整文档时按下面顺序写。内容足够短时可以合并“影响范围”和“验证情况”，但不能省略仓库/PR、背景、问题、根因和修复方案。

```markdown
# <需求名称> Review 说明

| 仓库 | PR |
|---|---|
| `<repo>` | [CodeUp PR](<url>) |

## 需求背景
<两三句话说明功能职责与改动动机>

## 问题描述
<触发条件 → 出错步骤 → 实际影响>

## 问题根因
<首次偏离 → 后续如何消费 → 为什么形成问题；未验证部分明确标注>

## 修复方案

| 链路 | 改动前 | 改动后 |
|---|---|---|
| <关键节点> | <原逻辑> | <新逻辑> |

<一小段说明为什么这次改动能截断根因，以及哪些正常路径保持不变。>

## 具体 Case 走读

Case：<真实复现 / 测试样例 / 代表性输入；注明来源和是否运行验证>
初始状态与预期：<谁触发、关键输入、原本应该得到什么>

| 步骤 | 输入或当前状态 | 代码位置与方法 | 业务作用 | 改动前 | 改动后 | 最终影响 |
|---|---|---|---|---|---|---|
| ① | <...> | `<repo/path:line>` · `<method()>` | <...> | <...> | <...> | <交给下游什么或用户看到什么> |

<只在有助于理解或用户明确要求时保留；用两句话指出首次分叉和修复为什么生效。>

## 影响范围
<涉及的服务、角色、数据、接口或环境；没有证据的范围不扩大>

## 验证情况
已验证：<...>
未验证：<... / 无关键缺口>

## 请重点 Review
- <需要 reviewer 判断的重点 1>
- <重点 2>
```

## 写作要求

- 先讲功能和用户结果，再讲技术机制；必要术语第一次出现时用半句话解释。
- 背景回答“这块做什么”，问题回答“哪里偏离”，根因回答“为什么偏离”，不要三节重复同一句话。
- 使用确定、平实的语气，不写“全面优化”“彻底解决”等没有验证依据的宣传词。
- 默认控制在同事 3～5 分钟能理解核心改动的长度；若具体 Case 是听懂复杂链路所必需，不为满足字数限制截断因果链。复杂多仓需求优先增加表格行，不增加背景故事。

## 完成检查

交付前确认：

- 输出顶部每个仓库都有对应的正确 PR；
- 根因与真实修改位置能互相解释；
- 改动前/后按业务链路而不是文件清单组织；
- 跨多个方法、服务或状态且容易抽象难懂时，已用同一份具体输入走通改动前后；Case 来源、文件、方法、首次分叉和最终影响都有依据；
- 已验证与未验证没有混写；
- reviewer 能直接指出该看哪些风险，不需要重新询问作者“你到底改了什么”；
- 简略概要直接从元信息开始，没有额外标题，也没有为了模板完整重复背景、问题和根因；每个项目、PR、验收项目和源分支的对应关系清楚；
- 完整文档没有覆盖既有内容，最终回复包含可点击的绝对路径。