Reviews a diff at three altitudes — design, correctness, style — and explains the reasoning behind each note so the author learns something instead of just applying a patch.
Review the following {{LANGUAGE}} change the way a senior engineer reviews a colleague's work: honestly, specifically, and with the reasoning shown. HOUSE STANDARDS: {{STANDARDS}} DIFF: {{DIFF}} Structure the review in three passes, in this order: **Pass 1 — Design.** Is this the right shape of solution? Does it belong here? What will this make harder in six months? Skip if the change is trivial, and say so rather than inventing concerns. **Pass 2 — Correctness.** Bugs, race conditions, unhandled errors, boundary cases, security. For each: give the concrete input or state that triggers it and the resulting wrong behaviour. If you cannot name the trigger, you are guessing — drop the note. **Pass 3 — Craft.** Naming, structure, idiom, tests. Only things that would survive a "does this matter?" challenge. For every note, use this format: - **What:** the observation, one line. - **Why:** the principle behind it, one line. Not "best practice" — the actual reason. - **Fix:** a code suggestion, or "author's call" if it's genuinely taste. Finally, add a section called **What's good here** with two specific things done well, and a one-line verdict: approve / approve with comments / needs work. Do not restate what the code does. Do not comment on formatting a linter handles.
Tools for this prompt
Where the input below comes from. The ones marked needed change the output a lot — fallbacks for each are further down.
This prompt is only as good as what you feed it. Web search covers anything public — these are the inputs it can't reach.
The diff. `gh pr diff` gives you the whole change with surrounding context.
Don't have it: Ask the user to paste the diff or file directly.
Only tools that web search cannot replace are listed. Anything public — reviews, job ads, papers, salary data — an agent can already fetch, so it is not listed here. No paid placements or affiliate links; if that changes, this line will say so.
A prompt is a skill with the serial numbers filed off. Install it once and your agent reaches for it on its own.
Paste this into ChatGPT, Claude Code, Codex, Cursor, or whatever you use:
Install the code-review-that-teaches skill globally from https://promptsbuddy.com/prompts/code-review-that-teaches/skill.md.claude/skills/code-review-that-teaches/SKILL.md
---
name: code-review-that-teaches
description: "Reviews a diff at three altitudes — design, correctness, style — and explains the reasoning behind each note so the author learns something instead of just applying a patch. Use when the user asks for help with engineering tasks like code-review, engineering, mentorship."
license: CC-BY-4.0
metadata:
source: https://promptsbuddy.com/prompts/code-review-that-teaches
author: "Meghna"
version: "2.1"
---
# A code review that teaches instead of nitpicks
Reviews a diff at three altitudes — design, correctness, style — and explains the reasoning behind each note so the author learns something instead of just applying a patch.
## Inputs to collect first
Ask the user for anything below that they have not already given you. Do not
invent values for these.
- `DIFF` — The diff or full file. Include surrounding context if the change is small. (e.g. git diff main...HEAD)
- `LANGUAGE` — Language and framework, so idiom advice is right. (e.g. TypeScript, Next.js App Router)
- `STANDARDS` — Anything the model can't infer: house style, perf budgets, review norms. (e.g. We prefer explicit over clever. No new dependencies without discussion.)
## Tools this works with
Do not require any of these. If one is unavailable, use the stated fallback and
say which input is missing rather than inventing it.
- **GitHub** (needed) — The diff. `gh pr diff` gives you the whole change with surrounding context. If its MCP server is connected, fetch this yourself.
- Without it: Ask the user to paste the diff or file directly.
- https://github.com/
## Instructions
Review the following {{LANGUAGE}} change the way a senior engineer reviews a
colleague's work: honestly, specifically, and with the reasoning shown.
HOUSE STANDARDS:
{{STANDARDS}}
DIFF:
{{DIFF}}
Structure the review in three passes, in this order:
**Pass 1 — Design.** Is this the right shape of solution? Does it belong here?
What will this make harder in six months? Skip if the change is trivial, and say
so rather than inventing concerns.
**Pass 2 — Correctness.** Bugs, race conditions, unhandled errors, boundary
cases, security. For each: give the concrete input or state that triggers it and
the resulting wrong behaviour. If you cannot name the trigger, you are guessing —
drop the note.
**Pass 3 — Craft.** Naming, structure, idiom, tests. Only things that would
survive a "does this matter?" challenge.
For every note, use this format:
- **What:** the observation, one line.
- **Why:** the principle behind it, one line. Not "best practice" — the actual reason.
- **Fix:** a code suggestion, or "author's call" if it's genuinely taste.
Finally, add a section called **What's good here** with two specific things done
well, and a one-line verdict: approve / approve with comments / needs work.
Do not restate what the code does. Do not comment on formatting a linter handles.
## Notes from people who use this
- Feed it the whole file when the diff is under ~40 lines — reviews of isolated hunks invent problems that the surrounding code already solves.
- The 'Why' line is the teaching. If it reads like a slogan, push back: 'explain why, from first principles.'
- Keep STANDARDS in a snippet file and paste it every time. Consistency across reviews is most of the value.
---
A code review that teaches instead of nitpicks · by Meghna · v2.1
From PromptsBuddy — https://promptsbuddy.com/prompts/code-review-that-teaches
Licensed CC BY 4.0.
Every prompt is also available at /prompts/code-review-that-teaches/skill.md — see all install options.
A flat review sorts by whatever the model noticed first, which is almost always naming — the cheapest observation. Forcing design first means the expensive question gets asked while there's still attention left to answer it. If the architecture is wrong, the variable names don't matter.
The correctness pass has one rule doing all the work: name the trigger. Models generate plausible bug reports for free. Requiring a concrete input that produces concrete wrong behaviour kills most of the false positives, because a fabricated bug usually can't produce one.
Everyone drops the What's good here section, and it's the reason the review gets read. A review that is only corrections trains the author to defend rather than to think. Two specific compliments — specific, not "nice work" — change how the rest lands.
Produces the orientation doc a new engineer actually needs: the three things that will confuse them, the load-bearing files, and the conventions nobody wrote down.
Meghna