review-brief

审查简报

读者不会阅读差异内容。他们会先花 30 秒浏览，然后只读那些可能造成影响的代码。请据此优化。

流程

1. 获取差异（git log --oneline main..HEAD、git diff --stat main..HEAD），并完整阅读每个有实质性变更的文件。
2. 找出不变的核心：之前哪里有问题，现在什么是正确的。用一句话说明。
3. 对每个代码块进行分类。符合以下关键标准的内容必须逐字放入代码部分。其他内容各占表格一行，或合并说明。
4. 按照下方布局撰写简报。每个引用的行号都必须对照工作树核实。
5. 让第二个 Agent 审查代码，而非文案：“有什么错误、夸大或遗漏？”交付前修复实际问题，并说明已修复。

关键代码标准

如果代码块涉及以下任何内容，就必须作为代码展示：

• Schema。 Drizzle 表、列、索引、迁移、信任边界上的 Zod schema、MCP 工具输入或输出 schema。
• 数据库写入。 新增或变更的 INSERT/UPDATE/DELETE、条件 WHERE 子句、工作流步骤或 cron 中运行的任何内容。
• 安全。 身份验证检查、范围或组织或项目访问控制、密钥、使用凭据的外部调用、任何默认放行的逻辑。
• 核心逻辑。 决定 bug 所涉结果的分支或表达式：状态赋值、验证关卡、排序比较器、重试或超时策略。
• 糟糕实现。 任何让你在代码审查中难以为其辩护的内容。通过字符串匹配厂商错误消息来选择 UI 文案；用正则表达式代替解析器；硬编码查找表；该用指标却用了 console.warn；吞掉异常的 catch；魔法超时；为弥补缺失参数而新增的数据库读取；悄悄改变行为的回退逻辑。请展示这些代码，在上方句子中指出这是糟糕实现，并说明目前可以接受还是应该阻止合并。

每段展示 5 到 20 行，删减至只保留关键判断；上方用一句话说明应注意什么，下方用一行指出出错时的失效模式。通常展示 3 到 6 段。如果超过 6 段，PR 可能应该拆分；请指出这一点。

布局

用一句话说明之前哪里有问题，以及现在什么是正确的。

前后对比图。 用 ASCII 流程图分成两列，展示用户可见的路径。方框表示步骤，箭头表示流向。标注 bug 所在位置。

关键代码。 按风险从高到低、按阅读顺序展示关键代码片段。本节是简报的重点，不要留待后续再说。

其余内容，统一放入一张表。 按风险排序：

| # | 文件 | 功能 | 唯一需要检查的事项 |

其余每项有意义的变更各占一行。将注册、重命名、格式调整和测试 fixture 合并到最后一行。

不存在的内容。 用项目符号列出读者可能以为已新增、但实际上没有的内容：没有迁移、没有新依赖、没有持久化结构变更、没有新的身份验证路径。

可能引发不同意见的决策。 列出两到四项。每项包括：所选方案、替代方案、该方案的代价。每项说明不超过一句。

状态表。 列出合并门槛所需的数字：测试、试运行计数、“已应用到生产环境：否”。

两分钟上手。 提供两到三条能运行此变更的命令。

分支状态。 提交、是否已推送、PR 链接或“尚无 PR”。

规则

• 任何段落不得超过两句话。
• 每个项目符号的开头几个词都加粗，方便扫读。
• 三项或更多同类事实应使用表格。
• 代码必须放在代码围栏中，不能写在正文里。只有读者必须查看某个文件时，才写出文件名。
• 除非另有要求，否则删去历史、被否决的替代方案和迁移过程说明。
• 绝不能为了简化而牺牲准确性。会影响读者行动的细节，应保留为一句话。
• 正文不超过 600 词。代码片段和表格不计入字数。

反模式

• 按编号逐步讲解，每个步骤都写一段文字，还附上一段“检查：”。
• 用文字描述 WHERE 子句、身份验证检查或状态表达式，而不是直接展示。
• 把有问题的代码藏在“你可能会有异议的决定”这一条里。如果它在代码中，就展示代码。
• 把代码留到“要我展示代码吗？”时再给。读者要的是评审简报；代码就是简报。
• 在正文中内嵌 PR 描述草稿。把它放进文件，再提供链接。