reviewing-code
Use when reading a diff or pull request for defects, when acting as the reviewer on a change you did not write, or when review feedback arrives on your own change.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- reviewing-code
- description
- Use when reading a diff or pull request for defects, when acting as the reviewer on a change you did not write, or when review feedback arrives on your own change.
03 SKILL.md 正文
Reviewing code
A review exists to catch what the author could not see. Not to show diligence or produce a list. What you bring is that you do not share the author's assumptions.
Ground rules
- The reviewer does not fix. A review carrying a patch gets read as a patch, and its findings are
never read. Enforce with read-only tools where possible —
vvkit-swift:swift-reviewersetstoolsfor this reason. - Scope is the diff. Read whatever context you need; report only on touched lines. Pre-existing problems bury this change's findings. Exception: the diff makes an existing defect reachable — a dead path now called, an input no longer validated upstream.
- An empty diff: say so and stop. Reviewing the whole repo instead is a task nobody asked for.
Severity is consequence, not confidence
| Bucket | Meaning |
|---|---|
| Critical | Ships broken: data loss, a crash on a reachable path, a security or privacy hole |
| Important | Works today, fails on a plausible input, on another platform, or under concurrency |
| Minor | Correct but will mislead the next reader, or violates a stated convention |
| Optional | Taste. Kept under its own heading, never interleaved with the three above |
Mixed with taste, the reader calibrates on the weakest item and skims the Critical with it.
Every finding names a location and a failure
- Cite
file:line. A finding without a location gets skipped, however right. - State what input or state produces what wrong result. No breaking input means a preference — Optional. "Add tests" or "add docs" counts only when it names the uncovered behavior.
- Two sentences: what breaks and when, then the smallest fix in words, not a patch. Longer only when the evidence needs it; never drop a real finding to stay short.
What to hunt first
Correctness before convention:
- Absence — a value assumed present: a force-unwrap, a non-null assertion, an assumed index, a default hiding a missing case.
- Lifetime — acquired, not released: a retain cycle, an observer or timer never torn down, a subscription outliving its owner.
- Shared state — non-atomic read-modify-write, initialization reachable from two threads, mutable state crossing an isolation boundary.
- Trust boundaries — outside input reaching a query, shell, path or template unescaped; a handler with no authorization, or one checking who the caller is but not what they own; a secret in code or logs. Confirm the input is attacker-controlled and reachable first — where the framework escapes it, it is noise.
- Contracts — a changed API, schema, wire format, persisted field or event that something deployed still reads. A rename is breaking even when every caller in this repo was updated.
- Counterfeit values — another layer's type hand-built from data that did not come from there, its invented fields read downstream as real. Fix: an entry point taking the data's own type.
- Swallowed failure — an error discarded, a result ignored, a plausible empty value instead of a failure.
- Remote calls — no timeout, a retry around a non-idempotent operation, a retry loop with no cap.
- Boundaries — first, last, empty, maximum, negative.
- Behavior changing without a test —
vvkit:writing-testsdecides whether one is owed.
Convention after, and only where established — vvkit:writing-comments for over-commented diffs.
Review against the requirements
- A plan, design or ticket is input. Check everything it asks for is present; flag every deviation for the author to confirm. A problem in the plan itself: say so.
- Where the design is silent, judge by what a reasonable user would expect, graded by effect.
- Before the verdict, list each behavior you set aside as outside the requirements, one line with the reason. The author rules on each.
Finding nothing is a result
- Say so plainly. Manufactured findings teach the author to skim, and the next Critical gets skimmed.
- Do not imply a check that never ran. A PR description is context, not proof; a limit on what you could verify gets one sentence.
Output shape
## Critical
- path/to/File.ext:42 — what breaks, and under what conditions
## Important
- path/to/Other.ext:17 — what breaks, and under what conditions
## Minor
- ...
## Optional
- ...
- Then which findings block, and a verdict: ready, not ready, or ready with named fixes.
- That is the whole review: it opens on the first finding — no introduction, praise, recap, checklist or closing summary. Empty buckets are left out; Optional holds at most two. A clean diff gets one line saying so, then the verdict.
- On a re-review, update the earlier findings rather than restating them. A finding fixed or rebutted stays closed without new evidence.
Asking for a review
Request one after substantial work, and always before merging to the default branch. Give the reviewer what it cannot infer, and none of your reasoning:
- What was built and what it should do — the plan, design or ticket.
- The exact range: from the start commit or
git merge-base <base> HEADtoHEAD. NeverHEAD~1for multi-commit work. - Read-only.
git show,git diff,git log; never moveHEADor touch the working tree. - No sub-reviewers. One seat; a diff too large for one pass is reviewed in passes, and says so.
Then fix Critical at once, Important before moving on, and record Minor.
When you are the author
A finding is a claim, and gets the same scrutiny as any claim.
- Clarify every unclear item before implementing any — items are often related.
- Check each against the code. Does it break behavior? Does the current form exist for a reason — a platform floor, a compatibility constraint, a decision the human made?
- Grep before building it "properly". An unused path gets deleted, not completed.
- Push back with evidence — a test, a call site, a constraint. Wrong pushback: say what you checked, and fix it.
- One item at a time, tested each, blocking first.
- A conflict with the human's earlier decision goes to the human.
- Acknowledge with the change — "Fixed: the nil path at
Parser.swift:88" — not "Great catch!".
04 同仓库更多 Skills
no-heading
Use when proving that the validator rejects a body with no H1 and a force-loading @-link.
wrong-name-does-not-match-dir
Dispatches a subagent per task and reviews between each one.
writing-tests
Use when adding or changing behavior, fixing a bug, or judging whether an existing or generated test earns its place.
writing-skills
Use when authoring or editing a skill, agent, command or hook for this kit, or when deciding whether a piece of guidance belongs in a skill at all.
writing-project-instructions
Use when creating or editing a CLAUDE.md or AGENTS.md, when it has grown long, or when a rule in it also exists in an installed skill.
writing-logs
Use when adding or reviewing log statements, or when deciding what level a message belongs at.