Back to Details

review-walkthrough

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Review walkthrough

审查讲解

Review a pull request the way a senior developer mentors a peer through it. Teach each part of the change and the code around it until the reviewer could change that code themselves, put each decision to them, and finish with one GitHub review the reviewer posts as their own. The code stays as the author left it: every change you want becomes a finding.
Write everything with 
writing-lean
. The findings, the summary and how to post them are in REVIEW.md; every GitHub call is in GITHUB.md.
The reviewer sets the pace. From step 3 on, a step ends when its Done when holds and the reviewer says to move on. Answering a round settles its findings, not the step: ask if they're ready.
以资深开发者指导同事的方式审查 pull request。逐步讲解变更的每个部分及其周边代码，直到审阅者能够自行修改这些代码；每个决定都交由审阅者作出，最后整理为一条 GitHub review，由审阅者以本人名义发布。代码保持作者提交时的原样：你希望修改的每一处都会成为 finding。
所有内容均使用 
writing-lean
编写。findings、summary 以及发布方式见 REVIEW.md；所有 GitHub 调用见 GITHUB.md。
审阅者决定节奏。 从第 3 步开始，只有当该步骤的完成条件成立且审阅者表示可以继续时，该步骤才结束。回答完一轮问题只代表本步骤的 findings 已处理完毕，并不代表可以进入下一步：应询问审阅者是否已准备好。

1. Pin the pull request

1. 锁定 pull request

The argument is a pull request number or URL. A pull request is required, because the walkthrough reads its linked issue, description, checks and earlier reviews. With none, stop and suggest 
open-pr
.
Record its number, repository, base, head SHA, author, and the issue it closes. Check whether an agent wrote it: a 
copilot/
branch, a bot author, or agent co-authors on its commits.
When the reviewer has reviewed this pull request before, this is a follow-up review: record the commit their last review covered (GITHUB.md). The diff under review runs from that commit to the head, or from the base when there is none.
Done when each of those is recorded, and the diff under review is known.
参数为 pull request 编号或 URL。必须提供 pull request，因为本次审查讲解会读取其关联的 issue、description、checks 和历史 reviews。若未提供，则停止并建议使用 
open-pr
。
记录其编号、repository、base、head SHA、author，以及它将关闭的 issue。检查它是否由 Agent 编写：例如 
copilot/
分支、bot 作者，或其提交中存在 Agent 共同作者。
如果审阅者此前已审查过此 pull request，则这是一次 follow-up review：记录其上次 review 覆盖到的 commit（GITHUB.md）。待审查的 diff 从该 commit 延伸至 head；若不存在上次 review，则从 base 开始。
完成条件：上述各项均已记录，且待审查的 diff 已确定。

2. Start the background work

2. 启动后台工作

Dispatch these as background subagents, so they run while the reviewer answers step 3:
  • code-review
     over the diff under review. Its requirements are the closing issue and its agent brief, plus the earlier review's findings in a follow-up review. Add 
    house-rules
    and 
    writing-lean
    to its Standards sources as documented standards; they override its smell baseline. When 
    code-review
    isn't installed, the subagent instead checks the closing issue and every acceptance criterion in its agent brief against the diff under review, and reports each as met, partly met or missing.
  • Checks. Read the pull request's checks. Cite passing ones as they are. Run locally only the checks that failed and the documented checks CI doesn't run, using the commands in the repo's 
    AGENTS.md
    .
  • Earlier threads. Fetch every review thread, from any reviewer, and read every reply. Classify each unresolved thread against the commits since: addressed (with the commit), partly addressed, not addressed, or no longer applies. For each resolved thread, note whether a reply confirms the fix.
Done when all three are running.
将这些任务分派给后台 subagents，使其在审阅者回答第 3 步时并行运行：
  • code-review
    ：对待审查的 diff 执行 code-review。其输入要求包括待关闭的 issue 和 Agent brief；在 follow-up review 中，还包括 earlier review 的 findings。将 
    house-rules
    和 
    writing-lean
    作为有文档记录的标准加入其 Standards 来源；这些标准会覆盖其 smell baseline。如果未安装 
    code-review
    ，则由 subagent 改为对照待审查的 diff 检查待关闭的 issue 及其 Agent brief 中的每条 acceptance criterion，并分别报告为已满足、部分满足或缺失。
  • Checks。 读取 pull request 的 checks，并如实引用已经通过的 checks。仅在本地运行失败的 checks，以及 
    AGENTS.md
    中有文档记录但 CI 不运行的 checks，并使用其中的命令。
  • Earlier threads。 获取来自所有审阅者的每条 review thread，并阅读每条回复。根据此后的 commits 对每条未解决的 thread 进行分类：已处理（附上对应 commit）、部分处理、未处理，或已不再适用。对于每条已解决的 thread，记录是否有回复确认修复。
完成条件：三项任务均已启动。

3. Meet the reviewer

3. 与审阅者会面

Work out who is invoking the skill from 
gh
and git, then confirm in one round:
  • how well they know this codebase,
  • what the review is for: general, correctness, security, performance, or learning the area,
  • whether they are the pull request's author.
When the reviewer is the author, tell them now how that limits the review's event; see REVIEW.md.
When the diff under review runs past about 400 changed lines or touches many files, recommend asking for a split before going further. In a follow-up review, recommend carrying on instead: commits answering a review rarely split well.
Their answers set how deep each step teaches and which findings rank first: a security review leads with leaks.
Done when the reviewer has answered, and has decided on a split if you recommended one.
通过 
gh
和 git 判断谁正在调用该 skill，然后在同一轮中确认：
  • 对该代码库的熟悉程度
  • 本次 review 的目的：常规审查、正确性、安全性、性能，或学习该领域
  • 是否为 pull request 的作者
如果审阅者就是作者，现在就告知他们这会如何限制该 review 可选的 event；见 REVIEW.md。
如果待审查的 diff 超过约 400 行变更或涉及许多文件，建议在继续之前请求拆分。在 follow-up review 中则建议继续进行：用于回应 review 的 commits 通常不适合拆分。
这些回答会决定每一步的讲解深度以及 findings 的优先顺序：例如，以安全为目的的 review 会优先指出信息泄漏问题。
完成条件：审阅者已回答问题；如果建议拆分，审阅者也已作出决定。

4. Plan the steps

4. 规划步骤

Wait for the 
code-review
findings and the earlier threads, then build the step plan from them and the diff under review. Where 
code-review
and a thread disagree on an earlier finding, the thread's replies win: they hold the reviewer's later decisions. Order the plan from the shared foundation (helpers, contracts, data shapes) out to the edges and interfaces, so each step builds on the last. Give the most time to steps holding serious findings, and fold quiet areas into their neighbours.
Show the plan as a numbered list, one line per step naming its files, and let the reviewer reorder, merge or skip steps. Then add the closing steps: remaining specs, local testing, and draft and post.
Done when the reviewer accepts the plan and every file in the diff under review sits in a step or on the not-reviewed list.
等待 
code-review
的 findings 和 earlier threads 完成，然后据此结合待审查的 diff 制定步骤计划。如果 
code-review
与某条 thread 对 earlier finding 的判断不一致，以该 thread 的回复为准，因为其中保留了审阅者后续的决定。按照从共同基础（helpers、contracts、data shapes）向外扩展至边缘部分和 interfaces 的顺序排列计划，让每一步都建立在上一步之上。为涉及严重 findings 的步骤留出最多讲解时间，并将没有明显问题的区域并入相邻步骤。
以编号列表展示计划，每步一行并注明相关文件，让审阅者重排、合并或跳过步骤。然后添加收尾步骤：剩余 specs、本地测试，以及起草和发布。
完成条件：审阅者已接受计划，且待审查 diff 中的每个文件都已出现在某个步骤中或列入 not-reviewed 列表。

5. Walk each step

5. 逐步讲解每个步骤

Teach each step in this order:
  1. Purpose: why this code exists and what problem it solves.
  2. How it works: show the code itself, not just links. Quote each block you discuss verbatim in a fenced code block, under a heading or link to its exact lines, with 
    // ←
    markers on the lines a finding or point refers to; condense only boilerplate, and say so. Links alone are hard to follow. Give enough of the surrounding system for the reviewer to change this code afterwards.
  3. What's significant: risks, traps, and problems that predate the pull request.
  4. Coverage: which specs exercise it, and the specific gaps.
  5. Try it locally: a short way to see it work. When the step changes something a user sees, kick the tires with the reviewer now, unless running the app is costly and the requested changes will touch the same path; then recommend deferring it. Put everything else on the local-testing checklist in the draft.
Raise each earlier thread in the step that covers its code. Note it when it's addressed, propose carrying it when it isn't (see REVIEW.md), and let the reviewer decide when it no longer applies.
End the step with a round: every proposed finding, numbered as in REVIEW.md, each with your recommendation and worded so that "yes" accepts it, then "Questions, or ready for the next step?":
❓ **F3** - **<finding title>**: <the problem, and why it matters>

➡️ <your recommended fix, and its label and blocking status>
Add each agreed finding to the draft as soon as it's agreed.
Done when the reviewer's questions are answered and every finding is agreed or rejected.
按以下顺序讲解每个步骤：
  1. 目的：为什么存在这段代码，以及它解决了什么问题。
  2. 工作方式：展示代码本身，而不只是链接。在相应标题下或精确行号链接处，用 fenced code block 逐字引用所讨论的每个代码块；在 finding 或观点所指的行上添加 
    // ←
    标记。只能压缩 boilerplate，并明确说明这一点。仅提供链接很难让人跟得上。提供足够的周边系统上下文，让审阅者之后能够自行修改此代码。
  3. 值得注意之处：风险、陷阱，以及早于本 pull request 就存在的问题。
  4. 覆盖情况：哪些 specs 会覆盖它，以及具体缺口。
  5. 在本地试用：用一种简短方式展示其运行效果。当某一步会改变用户可见内容时，应立即与审阅者一起实际试用；只有在运行应用成本较高且所请求的更改会触及同一路径时，才建议延后。其余所有内容都加入草稿中的 local-testing checklist。
在讲解覆盖其代码的步骤时，提出每条对应的 earlier thread。已处理时注明；若未处理，则建议将其继续带入最终 review（见 REVIEW.md）；若已不再适用，则由审阅者决定。
每一步最后都要进行一轮确认：每个拟议 finding 的编号方式与 REVIEW.md 一致，每条都附上你的建议，并将措辞写成审阅者回答“yes”即可接受，然后询问“有问题，还是准备进入下一步？”：
❓ **F3** - **<finding 标题>**: <问题及其重要性>

➡️ <建议的修复方式，以及 label 和 blocking 状态>
每个 finding 一经确认，就立即加入草稿。
完成条件：审阅者的问题均已得到回答，且每个 finding 都已被接受或拒绝。

6. Remaining specs

6. 剩余 specs

Cover the spec files no step discussed, and the gaps that cut across steps, such as a path that only runs on reconnect or failure. End with a round.
Done when every spec file in the diff under review has been discussed and every finding is agreed or rejected.
讲解此前没有任何步骤涉及的 spec 文件，以及横跨多个步骤的缺口，例如仅在重连或失败时才会运行的代码路径。最后进行一轮确认。
完成条件：待审查 diff 中的每个 spec 文件均已讨论，且每个 finding 都已被接受或拒绝。

7. Local testing

7. 本地测试

Show the local-testing checklist and offer to run it with the reviewer now, or to leave it until the requested changes land.
Done when the reviewer has run the checklist or chosen to defer it.
展示 local-testing checklist，并提出现在与审阅者一起运行，或等请求的更改落地后再运行。
完成条件：审阅者已运行 checklist，或选择延后执行。

8. Draft and post

8. 起草并发布

Follow REVIEW.md to draft the summary and comments, recommend an event, and post.
Done when the review is posted, or left pending for the reviewer to submit, and its URL is shown to the reviewer.
按照 REVIEW.md 起草 summary 和 comments，推荐一个 event，并发布。
完成条件：review 已发布，或保持 pending 以供审阅者提交，并向审阅者显示其 URL。

9. Recap

9. 回顾总结

In chat, recap the codebase concepts the session taught, one line each, so the reviewer leaves with a map of the area. Offer to reply "Addressed in 
<sha>
" to each earlier thread found addressed and still unresolved, and resolve it, confirming each with the reviewer.
Done when the reviewer has the recap and has answered any offer.
在聊天中逐行总结本次 session 讲解的代码库概念，让审阅者最终掌握该领域的知识地图。提出可以向每条已判定为已处理但仍未解决的 earlier thread 回复“Addressed in 
<sha>
”，并将其 resolve；每项操作都与审阅者确认。
完成条件：审阅者已收到回顾总结，并已回应相关提议。