review-mr
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCode review
代码审查
You are reading somebody else's work. You do not change it: a reviewer who edits the
code takes the decision away from its author and hides the disagreement.
你正在阅读他人的工作。你不修改它:审查者若编辑代码,就替作者做了决定,也掩盖了分歧。
1. The standard
1. 标准
Find the team's review standard and the standard for the touched stack, by the lookup
in standards.md: list , then
, and open what is there about reviewing and about the stack the
diff touches. Open them before reading any of the diff. The fallback when nothing closer exists is
review-checklist.md, which ships with this skill.
Read them with the Read tool — a short document whole, a long one by the sections its
headings say the diff touches. A keyword grep over a document only finds the rules you
already suspected the author broke; the finding worth posting is usually the rule you did
not know to look for.
<project>/.agents/standards/~/.agents/standards/Say in one line which source answered — the document, with its full path when the slot
entry is a directory. A review measured against a bar the author cannot see is an
argument waiting to happen, and a directory name does not show them the bar.
通过 standards.md 中的查找方式,找到团队的审查标准以及 diff 所涉及技术栈的标准:先列出 ,再列出 ,然后打开其中与审查以及 diff 涉及技术栈相关的内容。必须在阅读 diff 之前打开它们。如果不存在更贴近的来源,则使用此 skill 随附的 review-checklist.md 作为回退。
<project>/.agents/standards/~/.agents/standards/用 Read 工具读取它们——短文档读全文,长文档则按标题指明与 diff 相关的章节读取。对文档执行关键词 grep,只会找到你已经怀疑作者违反的规则;真正值得发布的问题,通常来自你事先根本不知道要查找的规则。
用一行说明哪个来源提供了答案——具体文档;如果对应的查找项是目录,则列出所采用文档的完整路径。衡量审查的标准如果对作者不可见,这场争论就无可避免;而目录名本身无法展示标准。
2. The diff, and only the diff
2. 只看 diff
sh
glab mr view <iid> --comments
git fetch origin <source-branch>
git diff <target>...<source-branch>Review what changed. Code the author did not touch is not in scope, however wrong it
looks — if it matters, it is a separate task, and the report says so under its own
heading.
sh
glab mr view <iid> --comments
git fetch origin <source-branch>
git diff <target>...<source-branch>审查发生变更的内容。作者没有触碰的代码不在范围内,无论看起来多么错误——如果它很重要,应单独立项,报告也应在自己的标题下说明。
3. Hunt bugs with the built-in reviewers
3. 使用内置 reviewer 查找 bug
Invoke the built-in skill through the Skill tool on the merge request's
changes — fetch the source branch first, then pass the branch or commit range as the
target, always at effort (). Never rely on the skill's
sticky last-used level: it carries over from whatever was typed last for unrelated
reasons, and review depth has to be the same on every merge request.
code-reviewhighhigh <branch>The developer's checkout does not move. The review usually runs from the
developer's own clone, and the built-in reviewer reads the files of the branch it is
given; left to itself it may get them by of that branch in this very
clone, which leaves the developer on somebody else's branch after the review, and with
uncommitted work either carried across or blocking the switch. So, before invoking it:
git checkoutsh
git rev-parse HEAD; git branch --show-current; git status --porcelain
wt=$(mktemp -d) && git worktree add --detach "$wt" "<source-branch>" && echo "$wt"The first line is the record to compare against afterwards. The second puts the source
branch into a worktree of its own; write down the path it prints, because a shell
variable does not survive into the next command. Then pass the target as the range plus
one sentence that names the worktree — . The whole argument reaches the reviewer as its review
target, so the sentence is read where it is needed; it is text, not a flag, and nothing
else about the call changes.
high <target>...<source-branch>; the branch is checked out at <worktree path>, read its files there and do not run git checkout or git switch in the current cloneWhen the reviewer returns, run the first line again and compare. If the branch or the
commit moved, switch back to what was recorded (, or when there was no branch) and say in the report that the built-in
reviewer moved the checkout and it was restored; if the switch back fails, stop and tell
the developer exactly where the clone stands. Then , which removes the directory as well. The same applies to
below.
git checkout <branch>git checkout --detach <commit>git worktree remove "<worktree path>"security-reviewTwo rules when using it here:
- Never pass or
--comment. Posting belongs to this skill and targets GitLab;--fixtargets GitHub pull requests. And a reviewer does not change code.--comment - Its findings are raw input, not the review. Every one passes the checklist and the standard first. A finding that contradicts the standard or the task's stated scope is dropped or reframed, not forwarded.
When the diff touches authentication, authorization, parsing of untrusted input, file
uploads or secrets, also run the built-in skill on the branch. Same
two rules; its findings land in the security category. Parsing of untrusted input
means a new parser, deserializer or raw-byte handling — code that decides what the
bytes mean. Adding or changing a standard validation rule on a request, or the usual
coercion of a route parameter, does not count: the framework already decides what the
bytes mean there, and a review that ran the security pass on every would
run it on every merge request. This is the same line draws, so the
author's own run and this review reach the same decision on the same diff.
security-reviewmax:255implement-taskWhen the merge request implements a Figma mockup, pull the reference through the
official Figma MCP (, and for tokens) and compare
the implementation against it. A visual deviation from the mockup is a finding like
any other.
get_screenshotget_design_contextWhen a built-in reviewer is not there at all, which is the normal state outside
Claude Code, do not skip this step — it is the bug-hunting half of the review. Read the
diff yourself against review-checklist.md at the depth
this step prescribes, and say in the report that the built-in reviewers were unavailable
and the hunt was manual. A review that quietly loses its bug-hunting pass reads exactly
like one that found no bugs.
通过 Skill 工具对合并请求的变更调用内置 skill——先获取 source branch,再将分支或 commit 范围作为审查目标传入,始终使用 强度()。绝不能依赖该 skill 黏性的上次使用级别:它会因为上次出于无关原因输入的内容而沿用,而每次 MR 的审查深度必须保持一致。
code-reviewhighhigh <branch>开发者当前的 checkout 不会移动。 审查通常在开发者自己的 clone 中运行,内置 reviewer 会读取传给它的 branch 文件。如果放任它自行处理,它可能通过在当前 clone 中执行 获取该 branch 的文件,结果是审查后开发者留在别人的 branch 上,而未提交的工作要么被带过去,要么阻碍切换。因此,在调用它之前执行:
git checkoutsh
git rev-parse HEAD; git branch --show-current; git status --porcelain
wt=$(mktemp -d) && git worktree add --detach "$wt" "<source-branch>" && echo "$wt"第一行命令是事后用于比较的基准记录。第二行会把 source branch 放入独立的 worktree;记下它打印的路径,因为 shell 变量无法保留到下一条命令中。
然后将目标写为该范围加上一句说明 worktree 位置的话——。整个参数会作为审查目标传给 reviewer,因此那句话会在需要时被读到;它是文本,不是 flag,调用方式的其他部分保持不变。
high <target>...<source-branch>; the branch is checked out at <worktree path>, read its files there and do not run git checkout or git switch in the current clone当 reviewer 返回后,再运行一遍第一行命令并进行比较。如果 branch 或 commit 发生了变化,就切回最初记录的 branch(或 commit)(没有 branch 时使用 ),并在报告中说明内置 reviewer 移动了 checkout,但现已恢复;如果切回失败,停止操作并准确告知开发者 clone 当前所处的状态。然后执行 ,这也会删除对应目录。对下文的 同样适用。
git checkout --detach <commit>git worktree remove "<worktree path>"security-review在这里使用它时有两条规则:
- 绝不能传入 或
--comment。 发布评论由本 skill 负责,并且目标是 GitLab;--fix面向 GitHub pull request。reviewer 不负责修改代码。--comment - 它的发现只是原始输入,不是审查结果。 每一条发现都必须先通过检查清单和标准的检验。与标准或任务明示范围冲突的发现应丢弃或重新表述,而不是直接转发。
当 diff 涉及身份验证、授权、不可信输入解析、文件上传或 secrets 时,还要对 branch 运行内置 skill。遵守同样的两条规则;其发现归入安全类别。不可信输入解析是指新增 parser、deserializer 或 raw-byte 处理,也就是决定 bytes 含义的代码。对请求新增或修改标准验证规则,或者对 route parameter 进行常规类型强制转换,不属于此列:框架已经决定 bytes 的含义;如果每次审查 都触发安全审查,那么每个 MR 都会触发。这与 划出的界线相同,因此作者自己的执行和本次审查会针对同一 diff 得出相同决定。
security-reviewmax:255implement-task当合并请求实现 Figma mockup 时,通过官方 Figma MCP(,以及使用 获取 tokens)拉取参考内容,并将实现与其比较。与 mockup 的视觉偏差也是一项审查发现,和其他问题一样。
get_screenshotget_design_context当完全没有内置 reviewer 时——在 Claude Code 之外通常如此——不要跳过此步骤,因为它是审查中用于查找 bug 的另一半。按本步骤规定的深度,自行对照 review-checklist.md 阅读 diff,并在报告中说明内置 reviewers 不可用,排查过程是手动完成的。如果审查悄悄丢失了 bug 排查环节,读起来就会像是根本没有发现问题。
4. Read it yourself, by the checklist
4. 自己按照检查清单阅读
The built-in reviewers are good at correctness and blind to convention: architecture,
the team's idioms and the quality rules are entirely yours. Go through the checklist
categories — implementation, logic, error handling and logging, dependencies and
impact, security and privacy, performance, API usability, testing, readability — and
merge the tools' confirmed findings into the matching ones.
Quality rules worth checking explicitly, because they are invisible to a bug hunter:
unfinished screens carry stubs, unimplemented buttons say so to the user, stubs are
reusable rather than copied, unfinished code carries a clear , and new
functionality on a production product sits behind a feature flag.
TODO:内置 reviewers 擅长检查正确性,却看不到团队约定:架构、团队惯用模式和质量规则完全需要由你检查。逐一完成检查清单中的各个类别——实现、逻辑、错误处理与日志、依赖与影响、安全与隐私、性能、API 可用性、测试、可读性——并把工具确认的发现归入相应类别。
以下质量规则值得显式检查,因为自动 bug 查找工具看不到它们:未完成的页面带有 stub;尚未实现的 button 要向用户明确说明;stub 应可复用,而不是复制;未完成代码带有清晰的 ;生产产品的新功能位于 feature flag 之后。
TODO:5. Two artifacts, never one
5. 两份产物,绝不能只产一份
The report goes to the person who asked for the review: summary, every finding,
checklist status. The comments on the merge request go to its author and are a much
smaller thing. Never paste the report into GitLab.
How to write and post the comments — the budget, what to cut, and the GitLab API
recipe for anchoring a comment to a line — is in
protocols/gitlab-comments.md. Read it before posting,
not after.
报告交给请求审查的人:包括摘要、全部发现以及检查清单状态。合并请求上的评论则发给作者,它是一份内容少得多的产物。绝不能把报告粘贴到 GitLab。
如何撰写和发布评论——篇幅预算、应删减的内容,以及用于将评论锚定到具体行的 GitLab API 方法——见 protocols/gitlab-comments.md。必须在发布前阅读,而不是发布后。
The report
报告
undefinedundefinedSummary
Summary
What the merge request does, and the verdict in one or two sentences.
What the merge request does, and the verdict in one or two sentences.
Findings
Findings
Blocking
Blocking
What must be fixed before this can merge. Each with file:line, what breaks, and when.
What must be fixed before this can merge. Each with file:line, what breaks, and when.
Non-blocking
Non-blocking
Worth changing, does not hold the merge.
Worth changing, does not hold the merge.
Out of scope
Out of scope
Defects this review found outside the diff. Named here, not commented on the merge
request, and worth their own task.
Defects this review found outside the diff. Named here, not commented on the merge
request, and worth their own task.
Quality standards
Quality standards
Stubs, unfinished functionality, feature flags.
Stubs, unfinished functionality, feature flags.
Done well
Done well
One or two specific decisions that were right. Name the decision, not the person.
One or two specific decisions that were right. Name the decision, not the person.
Checklist
Checklist
One line per category: clean, or the finding that broke it.
Write the report in the language the developer is speaking. The comments on the merge
request are in English regardless, because the author may not share that language.One line per category: clean, or the finding that broke it.
报告使用开发者正在使用的语言撰写。无论如何,合并请求上的评论都使用英文,因为作者可能并不使用同一种语言。What a claim in the report rests on
报告中结论的依据
Every statement about the repository — a file is missing, a test does not exist, a
route is not registered — rests on a command that ran and showed it. A command that
did not run shows nothing, and a shell error is the usual way a command does not run:
zsh refuses a glob that matches nothing before the command starts, so
answering says nothing about a sitting in the
same directory, and a the shell expanded for you never searched
at all. The reader takes "the repository has no compose file" as a fact about the
project and plans around it, which is why the wrong claim costs more than a missing one.
ls compose*.ymlno matches founddocker-compose.ymlgrep --include=*.mdWhen a command errors, read the error as the shell's before reading it as the
repository's: rerun without the pattern (, , a quoted glob). If no command gives a clean answer, the report says
"could not verify" and what was tried, and "absent" stays out of it.
ls docker-compose.ymlgit ls-files '*compose*'每一条关于 repository 的陈述——某个文件缺失、某项 test 不存在、某条 route 未注册——都必须以实际运行并给出结果的 command 为依据。没有运行的 command 什么也不能证明,而 shell error 正是 command 未能运行的常见原因:zsh 会在 command 启动前拒绝一个没有匹配项的 glob,因此 返回 ,并不能说明同一目录中没有 ;而由 shell 替你展开的 根本没有执行搜索。读者会把“repository 没有 compose file”当作项目事实,并据此安排工作;正因如此,错误断言的代价高于没有断言。
ls compose*.ymlno matches founddocker-compose.ymlgrep --include=*.md当 command 报错时,先把错误理解为 shell 的问题,再判断是否是 repository 的问题:去掉 pattern 后重试(、、带引号的 glob)。如果没有任何 command 给出明确答案,报告应写“无法验证”以及尝试过什么,并且不能据此断言“不存在”。
ls docker-compose.ymlgit ls-files '*compose*'Never
绝不
- Never leave the developer's clone on another branch or commit than the one the review started from. The review reads somebody else's branch; it does not move the person who asked for it onto that branch.
- Never edit the code under review. A reviewer who fixes the defect takes the decision away from the author and hides the disagreement; the finding says what is wrong and what would fix it.
- Never paste the report into GitLab. The report goes to whoever asked for the review; the comments on the merge request are a much smaller, separate artifact.
- Never pass or
--commentto the built-in reviewers. Posting belongs to this skill and targets GitLab, and a reviewer does not change code.--fix - Never forward a finding from a tool as your own before it has passed the checklist and the standard. A finding that contradicts either is dropped or reframed.
- 绝不能让开发者的 clone 停留在与审查开始时不同的 branch 或 commit 上。审查读取的是别人的 branch;它不应把请求审查的人切换到那个 branch 上。
- 绝不能编辑正在审查的代码。reviewer 若修复 defect,就替作者做了决定,也掩盖了分歧;审查发现应说明哪里有问题,以及应如何修复。
- 绝不能把报告粘贴到 GitLab。报告交给请求审查的人;合并请求上的评论是另一份独立且内容更少的产物。
- 绝不能向内置 reviewers 传入 或
--comment。发布评论由本 skill 负责,并且目标是 GitLab;reviewer 不负责修改代码。--fix - 绝不能在对发现通过检查清单和标准检验之前,就把工具发现当作自己的结论转发。与两者冲突的发现应丢弃或重新表述。