Code review

When you give Claude Code a task to complete in your codebase, Claude will often report back in a succinct way. Underneath the description of what Claude changed, there can be a variety of files that were changed (from small to major changes). Oftentimes, the session that wrote the code changes themselves (and explained them) is not the highest-quality judge of those changes. It's a good practice to give every change a look yourself before you keep it, and then have Claude review it again from a clean context, without this session's history.

Review the actual changes

A diff is the before-and-after of a change: the lines removed and the lines added, file by file. The /diff command opens an interactive viewer of your uncommitted changes in that form, and it can also show what each of Claude's turns changed. Use the up and down arrows to move between files and Enter to open one.

The most important things that deserve a second look every time are:

• Changes you didn't ask for. A config value that was edited while Claude was in the file or a rewritten helper method that you didn't mention.
• Tests that got weaker. If the project you're working in contains tests, identify any that were skipped, deleted, or loosened until they passed.
• New packages and hard-coded values. A dependency that was added for only one function, a URL or a key written straight into the code.

If the whole change is wrong, run /rewind (or press Esc twice on an empty prompt), pick the prompt that produced it, and choose Restore code and conversation. One limit worth knowing: files changed by shell commands Claude ran, such as a package install, aren't rolled back.

The exercise below uses a small signup-form task: Claude's summary on top, the eight files Claude touched underneath.

Ask for a second opinion

The Explore → Plan → Code → Commit lesson said to have a second reviewer on a change before you commit it. A long session carries everything it has read and decided. That's the context you learned to manage in the previous lesson, and it's exactly the history you don't want in a reviewer. /code-review is that second reviewer: it reviews the change in a clean context, with none of your session's history, and reports what it finds. It edits nothing unless you ask it to.

The review runs in the background, anywhere from seconds to a few minutes, and counts against your usage like any other task, so save it for changes that deserve a second look. The findings arrive in your conversation when it finishes. You can also ask in plain words, and Claude can start the same review from the request. If Claude answers inline instead of starting a review, run the command yourself.

For the signup-form change, the review came back with four findings:

Decide what to do with each finding

Sort each finding into one of three piles:

1. Fix now. This is a real problem, it matters, and it must be fixed.
2. Ask why. This is the pile for findings you can't quite verify or that seem off. It's possible for reviewers that are reading code changes cold to also miss things.
3. Leave it. This is a real problem but small or inconsequential. These can often be batched into a group of fixes that you'll cover in one future session.

To ask why, quote the finding back to Claude and ask Claude to check again. For the second finding above, you would type:

Whenever you ask for a fix, it's good to ask for evidence with it:

If a fix eventually grows into a large change of its own, run the review again.

When it pays off to review things more closely

A simple, one-line change often needs a quick glance at the diff and nothing else. You should use a human review and a Claude review when a change is bigger than you could hold in your head, when it touches something sensitive or does something destructive, and before you hand the work to a teammate.

Try it: sort the four findings

Recap

• Read the actual diff of the file changes before you trust the summary alone. Run /diff and look for changes you didn't ask for, weaker tests, and new packages or hard-coded values.
• Get a second opinion from a clean context with /code-review (or ask in plain words and let Claude start it). The reviewer reports, and Claude doesn't edit unless you ask.
• Treat each finding as fix now, ask why, or leave it, and ask for evidence with every fix.

When the reviewer flags the same issue a few times, it might be a good idea to write a rule for Claude to read at the start of every session. That file is CLAUDE.md, and it's next.