review-brief

一轮修改收尾时，把「为什么改、改了什么、怎么审」沉淀成一份自包含的审查简报，交给另一个没有本对话上下文的 agent 独立复查。

整个 skill 只有一条铁律：审查方读不到你的对话历史。简报里没写的，审查方就不知道。需求原话、变更边界、验证方法，宁可多写一句，不能让审查方靠猜。

触发场景

判断不出是哪种就直接问一句："需求是在这个对话里提的，还是之前在别的会话里？"

Procedure

Step 1 — 沉淀需求

场景 A（从对话历史提取，不要凭印象转述）：

• 原始需求：用户原话逐字引用（blockquote）。分多次说的按时间合并；中途改过主意的保留演变（"最初要 X，后确认为 Y"——审查方需要知道代码为什么长这样）。报错日志、截图说明、复现数据也原样贴，不要转述
• 问题背景（bug / 排查类必填）：现象、复现步骤、期望行为 vs 实际行为、环境 / 版本、根因分析、修复思路（为什么改这里能解决根因，而不是只盖住症状）。给不出复现步骤就写"未能记录，需向用户补充"，让审查方知道缺什么
• 澄清与追加约束：讨论中确认的细节、被否掉的方案（"不要用 XX 方式实现"也是约束）
• 验收标准：怎么算做完。用户说过的直接引；用户没说的，从需求推导可观察、可验证的条目，每条标注"⚠ agent 整理，用户未明确"——这批条目正是审查方最该帮忙盯的
• 覆盖情况：哪些验收标准做了、哪些没做 / 只做了一半 / 明确延后。审查方的核心任务之一就是抓漏，没做的必须显式列出来

如果你是子会话、只能拿到父会话的转述而不是完整原始对话：按场景 B 的「二手需求」处理，逐字引用转述内容并注明来源，别假装读过原对话。

场景 B（先问再写）：问用户要需求描述或 issue / 工单链接、当时的验收标准，以及这是不是 bug（是 bug 就追问复现步骤和期望行为）。不要根据代码反推需求再冒充原始需求——反推内容只能作为推断写并标注。拿到的需求原文同样要逐字引用，不要改写成自己的话。

用户也可能已经带着需求文字来（二手转述，不是实现方对话的原始记录）：直接逐字引用并注明来源，不要因为拿不到原始对话就推脱；缺的信息写进简报"局限性"。

Step 2 — 圈定变更范围

先跑只读命令摸清状态（全程只读，不改任何东西）：

git rev-parse --show-toplevel    # 仓库根；简报路径和命令都相对它，不假定 cwd 就是根
git status --porcelain           # 未提交改动 + 未跟踪文件
git status -sb                   # 分支 + ahead/behind，判断是否已推送
git log --format='%h %ad %s' --date=short -15   # 近期提交（带日期）
git branch --show-current

按状态三分支：

工作区里可能混着与本需求无关的本地改动（别的任务、本地配置）：单独列一节标注"与本次需求无关，不要计入审查范围"。不隔离清楚，审查方会把无关改动当成这次改的。

已提交时，确定"本次"提交集合的依据按优先级取：

1. 对话历史里有明确记录（本会话亲手提交了哪几笔）→ 直接用
2. 用户指定（"最近 3 个提交"、"abc1234 之后的所有提交"）→ 按用户说的
3. 按 message 与时间推断 → 列出候选让用户确认，绝不静默猜。提交边界搞错，后面整个审查都在做无用功

区间里如果混入了无关提交（期间顺手合并、修别的 bug），逐条标出来并说明哪些不在本次范围；连续区间表达不了时，别硬凑 base..head，直接列相关提交的 hash 清单，逐笔给 git show。

base 取第一个相关提交的父提交（<hash>^），简报里显式写出 base 和 head。第一个相关提交就是仓库首个提交时没有父提交，用空树 hash 4b825dc642cb6eb9a060e54bf8d69288fbee4904 作 base，或逐笔 git show。

动笔前确认审查方怎么拿到这份变更，并写进简报头：

• 同一工作区（另一个 agent 会话）→ 直接跑简报里的命令
• 同一仓库的另一份 clone → 给远端 URL、分支、head，审查方 fetch 后 checkout
• 只能拿到简报（粘贴到别的 AI）→ 另存 patch 到简报同目录：git diff <base>..<head> > review-briefs/<slug>.patch；未提交改动同理 git diff HEAD > review-briefs/<slug>.patch。untracked 文件不进 patch，要把内容附在简报里或说明需在工作区查看
• 仓库没有配置远端：变更位置写"仅本机工作区（未配置远端）"，审查方必须同工作区或收 patch

用户没说审查方环境时，默认按"同一工作区"写，同时附一份 patch 兜底，并在报告里说明这个假设。

另外 git status --porcelain 看不到被 .gitignore 忽略的文件。本次如果改了这类文件（本地配置、生成物），用 git status --ignored 确认并单独列出。

非 git 目录：跳过 git 命令，从对话历史手工列改动文件，简报里注明"非 git 仓库，无 diff"；能让用户提供改动前的文件拷贝最好，否则审查依据只剩文件清单 + 关键改动摘录，要在局限性里写清。

Step 3 — 逐文件整理变更清单

对每个变更文件搞清三件事：改了什么、为什么改、怎么验证没改坏。产出两样：

文件清单表（放简报 §2.3，路径相对仓库根）：

关键改动摘录（放简报 §2.4）：挑 3-5 个最要紧的 hunk 原文贴出（带 file:line），其余不贴，全量 diff 让审查方用命令自取：

git diff <base>..<head>              # 整体 diff
git show <hash>                      # 单个提交
git diff <base>..<head> -- <file>    # 单文件

diff 合计超过约 500 行时摘录更要克制：只贴"不看就没法判断是否符合需求"的部分，其余靠命令，并在局限性一节注明。

Step 4 — 拟审查要点（三维度）

简报的智力核心。每条都要针对本次改动，带 file:line 或具体验证方法；"注意边界条件"这类通用空话一条都不要写。

① 需求符合性：逐条验收标准列表格（验收标准 → 对应改动 → 怎么验证）。没有对应改动的验收标准也要列，标"无对应改动"，请审查方确认是漏做还是有意延后——漏做和范围外改动一样，都是审查方最该抓的。缺口写在这里即可；只有它同时构成实现风险时才去 §3.2 展开，用交叉引用代替整段重复。另列范围外改动小节：本次顺手做了但需求没要求的（顺手重构、格式化、修了别的 bug），如实列出让审查方裁决是保留还是拆走——藏着掖着，被发现一次，整份简报的信任就没了。

② 潜在 bug / 风险点：

• 自己拿不准的点优先写：改动时心里发虚的地方（"过期判断和校验的先后顺序好像不对，没测"）是简报里最值钱的内容，如实写、标位置、说不确定的理由。场景 B 补生成时你并不是实现方，别冒充"实现方自评"：写成"简报生成方推断，未向实现方核实"
• 再按改动类型过一遍：边界与空值、错误处理、类型转换、并发 / 时序、硬编码值、调试代码与 console.log 残留——只在真的碰到时列
• 每条带 <file:line>，能写复现方法就写
• 测试充分性：这次补没补、改没改测试，覆盖了哪些验收标准与原 bug？只做手工验证的写清验证方式。没补测试本身要作为风险列出来，别让审查方误以为有回归保护

③ 影响面：

• 调用方：被改的函数 / 组件 / 接口还有谁在用——真的去 grep，把结果写进简报，不要只写"已检查无影响"
• 共享接口 / 数据结构 / 配置默认值：动了没有，变了谁受影响，有没有兼容性 / 迁移问题
• 同步项：测试要不要补、文档要不要改、生成物 / 锁文件要不要重跑（每个项目有自己的对应物）
• 按改动类型补查（相关才列）：安全与隐私、性能与资源、依赖 / 许可证、项目规范一致性
• 建议回归：最小回归集——必须过一遍的功能点、必须跑的测试命令、前置条件（装依赖 / 起服务）

Step 5 — 写入并报告

• 位置：<仓库根>/review-briefs/YYYY-MM-DD-<slug>.md（slug 取需求关键词的短横线英文或拼音）；用户指定路径则用用户的；同名文件已存在就追加 -HHMM 后缀，不覆盖
• review-briefs/ 是本次交接产物，不属于被审查的变更。简报 §2.2 里要提醒审查方把它从 git status 里排除；默认不提交、不改 .gitignore，报告里提一句即可。用户希望仓库保持干净时，按用户指定路径写到仓库外
• 写"工作区干净"这类话要加"生成前"限定：简报落盘后，review-briefs/ 自己就是一条未跟踪记录
• 语言跟随用户（默认中文）
• 报告：文件路径 + 一句用法（"把这个文件发给另一个 agent，它会按文档开头的指引开始审查"）+ 审查方环境假设（同工作区 / 远端 clone / 只拿简报需附 patch）+ 提醒 review-briefs/ 是未跟踪产物

Step 6 — 自检

• 需求原话逐字引用了；所有非原话内容都标了"agent 整理 / 推断"
• bug / 排查类：现象、复现步骤、期望 vs 实际、根因、修复思路都写了（或明确写"非 bug 类"）
• 未实现 / 部分实现 / 延后的需求点写了；没有对应改动的验收标准也列了
• 提交范围有明确依据（对话记录或用户确认过），不是猜的；区间内的无关提交标出来了
• 每个变更文件都有"改了什么 + 为什么"
• 实现方自测记录如实（跑了什么、结果、没跑什么）；场景 B 没冒充实现方自评
• 审查要点每条都具体（file:line / 验证命令），没有通用空话
• 自己拿不准的点写了，范围外改动也列了
• 写明了审查方怎么拿到变更（同工作区 / clone / patch），以及审查前的状态核对要求
• 自包含：想象把文件直接发给一个全新会话，它每一步都不需要追问——哪里会卡住，哪里就是没写够
• 给审查方的命令在约定的审查环境下都能直接复制执行（含前置条件）

简报模板

按此结构写，空节写"无"不删节。各节怎么填见 Procedure 对应步骤。

# 审查简报：<一句话标题>

> **给审查 agent**：本文档由实现方或补生成方（另一个 agent 会话）生成，你是审查方，不需要实现方的对话历史。
> **先核对再动手**：仓库路径 / 分支 / HEAD / 工作区状态应与 §2 一致；不一致时以仓库实际为准，并在结论里说明差异。
> **简报是自述，不是证据**：文中的结论、行号、风险点都要回仓库自己核对。
> **审查范围**：§3 是线索，不是边界。通读 §2 的全量变更，独立找简报没列的问题。
> 路线：§1 了解需求 → §2 查看变更 → §3 逐项审查 → 按 §4 的格式汇报结论。
> 文档本身有缺口（需求不清、范围不明）也算审查发现，一并指出。

| 项 | 值 |
| --- | --- |
| 生成时间 | 2026-10-17 14:30 +08:00（带时区） |
| 仓库 / 分支 | `D:\path\to\repo` @ `main`（head `def5678`） |
| 需求来源 | 对话原文 / issue #123 / 用户口述 |
| 变更状态 | 已提交 2 个提交（`5c8fcbb..2e40ed1`）/ 未提交 / 混合 |
| 变更位置 | 本机工作区未推送 / 已推送 origin / 仓库未配置远端 |
| 审查方环境 | 同一工作区直接跑命令 / 另一份 clone（远端 URL）/ 只拿到本简报（附 patch 文件名） |
| 实现方 | <agent 名称或模型>；未知时写"未知（本文由补生成方整理）"；自测记录见 §2.5 |

## 1. 需求 / 问题

### 1.1 原始需求（用户原话）

> 逐字引用……（报错日志、截图说明、复现数据原样贴，不要转述）

### 1.2 问题背景与诊断（bug / 排查类必填，其他写"无"）

- 现象：……
- 复现步骤：……
- 期望行为 vs 实际行为：……
- 环境 / 版本：……
- 根因分析：……
- 修复思路：……（为什么改这里能解决根因，而不是只盖住症状）
- 修复前对照：`git show <fix-commit>^:<file>`（可选）

### 1.3 澄清与追加约束

- ……

### 1.4 验收标准

1. ……（用户原话）
2. ……（⚠ agent 整理，用户未明确）

### 1.5 覆盖情况

- 已实现：……
- 未实现 / 部分实现 / 延后：……（没有就写"全部覆盖"）

## 2. 变更范围

### 2.1 提交记录（如有）

| # | 提交 | 日期 | 说明 |
| --- | --- | --- | --- |
| 1 | `abc1234` | 2026-10-17 | fix: …… |

基线 `abc1234^`（不在本次变更内）→ `def5678`；整体 diff：`git diff abc1234^..def5678`（约 150 行）

区间内无关提交：无 / 列出……

### 2.2 未提交变更（如有）

```text
 M src/auth.ts          （+36 −12）
?? src/auth-captcha.ts  （新增）
```

- untracked 文件不进 `git diff`，找全变更用：`git status --porcelain`
- 生成前工作区干净；本简报自身会以 `?? review-briefs/` 出现，它是交接产物，不属于被审查变更，审查时排除
- 与本需求无关的本地改动：无 / 说明

### 2.3 文件清单与意图

| 文件 | 变更 | 意图（为什么改） |
| --- | --- | --- |
| src/auth.ts | 修改 | 登录接口加验证码校验（对应验收标准 2） |

### 2.4 关键改动摘录

（3-5 个 hunk 原文，带 file:line，每段一句"为什么贴这段"）

### 2.5 实现方自测记录

| 命令 / 验证方式 | 结果 | 备注 |
| --- | --- | --- |
| `npm test` | 4/4 通过 | |

未运行：……（没跑什么、为什么）

原始记录拿不到时（典型是场景 B）：写"实现方未提供自测记录，下表为简报生成时的复跑结果"，不要把复跑冒充成实现方当时的测试。

## 3. 审查要点

### 3.1 需求符合性

| 验收标准 | 对应改动 | 怎么验证 |
| --- | --- | --- |
| 1. …… | `src/auth.ts:88` | 跑 `npm test` 的 X 用例 / 按以下步骤手工验证 |
| 2. 需求 B | **无对应改动**（全仓无相关逻辑） | 按命令 A 复现：预期过滤但实际仍输出 → 判漏做 |

没有对应改动的验收标准也要列出来（标"无对应改动"），请审查方确认是漏做还是有意延后。

**范围外改动**：……（需求没要求但本次做了的；无则写"无"）

### 3.2 潜在 bug / 风险点

1. `src/auth.ts:88`：过期判断在校验之后，过期验证码可能仍通过——**实现方自评：拿不准，没测过**，请重点验证
2. ……

**测试充分性**：……（补了哪些测试、覆盖哪些标准；没补测试本身也是风险）

### 3.3 影响面

- **调用方**：……（grep 结果，带文件与行号）
- **共享接口 / 数据结构 / 配置默认值**：……（变了就列，没有写"无"）
- **需要同步**：测试 / 文档 / 配置 / 生成物
- **按改动类型补查**：安全与隐私 / 性能与资源 / 兼容性 / 迁移（相关才列）
- **建议回归**：最小回归集 + 测试命令 + 前置条件（装依赖 / 起服务）

### 3.4 建议审查步骤

0. 核对分支、HEAD、`git status` 与 §2 一致；不一致先报告差异
1. `git diff abc1234^..def5678` 通读全量 diff（约 150 行；未提交改动用 `git diff HEAD`）
2. 对照 §3.1 逐条验证需求，含"无对应改动"的条目
3. 重点看 §3.2 风险点，并独立找简报没列的问题
4. 跑 `npm test`；手动过一遍登录主流程

## 4. 输出要求

- 先给总体结论：**通过 / 有条件通过 / 不通过**，一句话理由
- 按三档逐条汇报，每条带 `file:line` 与理由：**阻塞**（不符合需求 / 确定 bug / 破坏其他模块）、**建议**（不阻塞的改进）、**疑问**（拿不准，向实现方求证）
- 逐条回答验收标准：通过 / 不通过 / 无法验证；"无对应改动"的条目单独说明
- 附上实际执行的命令与结果；无法验证的条目写清原因和缺什么条件
- 说明审查覆盖了哪些方面、哪些没覆盖
- 只审查，不改代码（除非用户另行要求）

## 简报局限性

（如实写，如"需求为用户事后口述，非原始记录"；没有就写"无"）

Output contract

• 产出 <仓库根>/review-briefs/YYYY-MM-DD-<slug>.md；审查方拿不到工作区时另产出与简报同目录的 <slug>.patch；模板各节齐全（空节写"无"，不删节）
• 简报里写明审查方环境假设与变更获取方式；默认假设同一工作区
• review-briefs/ 与 patch 是交接产物，默认不提交；报告里提醒用户它们是未跟踪文件
• 全程只读 git；除 review-briefs/ 下的简报与 patch 外，不修改被审查仓库的任何代码与配置（.gitignore 也不动）
• 简报里的命令在约定的审查环境下可直接复制执行
• 结束时报告：文件路径 + 一句用法 + 审查方环境假设

Failure handling

Examples

输入（场景 A）：同一会话里用户报了"导出 Excel 超过 1000 行就卡死"，agent 修完并提交了 2 个 commit；用户说"生成审查简报，我发给另一个 AI 复查" 输出：review-briefs/2026-10-17-excel-export-freeze.md——§1.1 逐字引用卡死描述与用户补充的复现步骤；§1.2 写根因（全量载入内存）与修复思路（流式写出）；§1.5 写"合并单元格导出未实测，列入未覆盖"；§2.1 两笔提交（含日期）+ 整体 diff 命令；§2.5 写"npm test 全绿，未做手工导出验证"；§3.2 含一条实现方自评"改成流式写入后，合并单元格的处理没测过"；§4 要求逐条回答验收标准。

输入（场景 B）：新会话，用户说"帮我给最近的提交出一份审查简报" 输出：先问需求来源和验收标准，拿到需求文字后 git log 列出近几笔作为候选让用户确认，确认后生成简报——提交边界用的是用户确认的那个；实现方未知就写"未知（补生成方整理）"，推断出的风险标"简报生成方推断"；若审查方不在同一工作区，同时产出 patch。

输入（场景 A 变体）：改动还没提交，用户说"还没想好怎么提交，先出简报" 输出：§2 走"未提交变更"分支，写明 untracked 文件清单与"新文件不进 git diff"的提醒，并注明 review-briefs/ 是简报产物、不算变更。

与相邻技能的边界

Windows (win32) platform notes

用到的 git 命令（rev-parse / status / log / diff / show / branch）全部只读、跨平台通用，Git Bash 与 PowerShell 都行；路径含空格记得加引号。写简报文件用 Write 工具，无平台差异。