Back to Details

review-brief

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Review brief

审查简报

The reader will not read the diff. They will skim for 30 seconds, then read only the code that could hurt them. Optimize for that.
读者不会阅读 diff。他们只会浏览 30 秒，然后只阅读可能对其造成影响的代码。应以此为目标进行优化。

Process

流程

  1. Get the diff (
    git log --oneline main..HEAD
    , 
    git diff --stat main..HEAD
    ) and read every non-trivial changed file in full.
  2. Find the invariant core: what was broken, what is true now. One sentence.
  3. Classify every hunk. Anything matching the crucial criteria below goes into the code section verbatim. Everything else gets one table row or is folded.
  4. Write the brief in the layout below. Every line number cited must be verified against the working tree.
  5. Run a second agent as a reviewer of the CODE, not the prose: "what is wrong, overstated, or missing?" Fix real bugs before delivering, and say you did.
  1. 获取 diff（
    git log --oneline main..HEAD
    、
    git diff --stat main..HEAD
    ），并完整阅读每个存在实质性变更的文件。
  2. 找出不变量的核心：之前哪里出了问题，现在什么情况是正确的。用一句话概括。
  3. 对每个变更区块进行分类。任何符合下述关键标准的内容都应原样放入代码部分。其余内容要么各占一行表格，要么合并处理。
  4. 按照以下布局编写简报。引用的每个行号都必须对照 working tree 进行验证。
  5. 让第二个 Agent 审查代码而非文字：询问“有什么错误、夸大或遗漏？”交付前修复真正的 bug，并说明已进行修复。

Crucial code criteria

关键代码标准

A hunk is crucial and must be shown as code if it touches any of:
  • Schema. Drizzle tables, columns, indexes, migrations, Zod schemas at a trust boundary, MCP tool input or output schemas.
  • Database writes. New or changed INSERT/UPDATE/DELETE, conditional WHERE clauses, anything that runs inside a workflow step or a cron.
  • Security. Auth checks, scope or org or project gating, secrets, external calls with credentials, anything that fails open.
  • Core logic. The branch or expression that decides the outcome the bug was about: a status assignment, a validation gate, a ranking comparator, a retry or timeout policy.
  • Jank. Anything you would be embarrassed to defend in review. String-matching a vendor error message to pick UI copy. A regex standing in for a parser. A hard-coded lookup table. A 
    console.warn
    where a metric belongs. A swallowed catch. A magic timeout. A DB read added to work around a missing parameter. A fallback that quietly changes behaviour. Show it, name it as jank in the sentence above, and say whether it is acceptable for now or should block.
Show each as 5 to 20 lines, trimmed to the decision, with one sentence above saying what to notice and one line below naming the failure mode if it is wrong. Three to six excerpts is normal. If there are more than six, the PR should probably be split; say so.
如果变更区块涉及以下任何内容，则属于关键内容，必须以代码形式展示：
  • Schema。 Drizzle 表、列、索引、迁移、位于信任边界处的 Zod schema、MCP 工具输入或输出 schema。
  • 数据库写入。 新增或修改的 INSERT/UPDATE/DELETE、带条件的 WHERE 子句，以及任何在 workflow 步骤或 cron 中运行的内容。
  • 安全。 Auth 检查、scope、org 或 project 权限控制、secrets、带凭据的外部调用，以及任何采用 fail-open 策略的逻辑。
  • 核心逻辑。 决定 bug 所涉及结果的分支或表达式，例如状态赋值、验证门控、排名比较器、重试或超时策略。
  • Jank。 任何会在审查时让你感到难为情的实现。例如通过字符串匹配厂商错误信息来选择 UI 文案、用正则表达式代替 parser、使用硬编码的查找表、在应该记录 metric 的位置使用 
    console.warn
    、吞掉异常、设置魔法超时、为弥补缺失参数而增加数据库读取，或通过 fallback 悄悄改变行为。展示相关代码，在上方的句子中明确指出它是 Jank，并说明目前是否可以接受，还是应当阻止合并。
每段展示 5 到 20 行代码，裁剪至与决策相关的部分。代码前用一句话说明需要关注什么，代码后用一行说明出错时会导致什么故障模式。 通常展示三到六段代码。如果超过六段，PR 可能应该拆分；应明确指出这一点。

Layout

布局

One sentence stating what was broken and what is true now.
Before / after diagram. One ASCII flow, two columns, showing the user-visible path. Boxes are steps, arrows are what flows. Label the bug locations.
The code that matters. The crucial excerpts, in reading order by risk. This section is the point of the brief. Do not defer it to a follow-up.
Everything else, in one table. Sorted by risk:
| # | File | What it does | The one thing to check |
One row per remaining meaningful change. Fold registrations, renames, formatting, and fixtures into a single final row.
What does NOT exist. Bullets naming the things a reader would assume were added and were not: no migration, no new dependency, no change to a persisted shape, no new auth path.
Decisions you might disagree with. Two to four bullets. Each: the choice, the alternative, the cost of the choice. No defence longer than one sentence.
Status table. Whatever numbers gate the merge: tests, dry-run counts, "applied to prod: No".
Try it in two minutes. The two or three commands that exercise the change.
Branch state. Commits, pushed or not, PR link or "no PR yet".
用一句话说明之前哪里出了问题，以及现在什么情况是正确的。
变更前 / 变更后图。 使用一个包含两列的 ASCII 流程图，展示用户可见的路径。方框表示步骤，箭头表示流转内容。标注 bug 所在位置。
真正需要关注的代码。 按风险从高到低排列关键代码片段。这是简报的核心，不要将其推迟到后续补充。
其余内容全部放在一张表中。 按风险排序：
#文件作用唯一需要检查的事项
每项剩余的实质性变更占一行。将注册、重命名、格式调整和 fixtures 合并为最后一行。
不存在的内容。 使用项目符号列出读者可能以为已经添加、但实际并未添加的内容：没有 migration、没有新依赖、持久化数据结构没有变化、没有新增 auth 路径。
可能存在分歧的决策。 两到四个项目符号。每项包括：所选方案、替代方案以及该选择的代价。辩解不超过一句话。
状态表。 列出所有影响合并决策的数据：测试、dry-run 数量、“已应用到生产环境：否”等。
两分钟内验证。 提供两到三个用于验证变更的命令。
分支状态。 列出 commits、是否已 push、PR 链接或“尚未创建 PR”。

Rules

规则

  • No paragraph over two sentences anywhere.
  • Bold the first few words of every bullet so the list skims by its openers.
  • Tables for anything with three or more parallel facts.
  • Code goes in fences, never in prose. Name a file only when the reader has to go there.
  • Cut history, rejected alternatives, and migration narrative unless asked.
  • Never simplify into inaccuracy. A detail that changes what the reader would do stays, as one line.
  • Under 600 words of prose. Code excerpts and tables do not count.
  • 任何段落都不得超过两句话。
  • 每个项目符号的前几个词都要加粗，以便读者通过开头快速浏览。
  • 存在三个及以上并行事实时使用表格。
  • 代码必须放在代码块中，绝不能放在正文里。只有当读者必须前往该文件时才提及文件名。
  • 除非用户要求，否则删除历史记录、已否决的替代方案和迁移过程的叙述。
  • 绝不能为了简化而造成不准确。任何会改变读者操作方式的细节都必须保留，并单独占一行。
  • 正文不超过 600 字。代码片段和表格不计入其中。

Anti-patterns

反模式

  • A numbered walkthrough with paragraphs per stop and a "Check:" paragraph.
  • Describing a WHERE clause, an auth check, or a status expression in words instead of showing it.
  • Hiding jank in a "decisions you might disagree with" bullet. If it is in the code, show the code.
  • Saving the code for "want me to show you the code?" The reader asked for a review brief; the code is the brief.
  • A draft PR description inline. Put it in a file and link it.
  • 使用编号逐步讲解，并在每一步后附上一段说明和“检查：”段落。
  • 用文字描述 WHERE 子句、auth 检查或状态表达式，而不是直接展示代码。
  • 将 Jank 藏在“可能存在分歧的决策”项目中。如果它存在于代码中，就必须展示代码。
  • 保留代码，并询问“需要我展示代码吗？”读者要求的是审查简报；代码本身就是简报。
  • 直接在正文中起草 PR 描述。应将其放入文件并提供链接。