review-handoff

Review 交接内容

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

输入

通常包括：

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

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

任务：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. 压缩改动

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

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