What's the actual difference between /code-review and just asking Claude to look at code directly in conversation without the command?
The biggest difference is in how it executes and how it uses context. Pasting code directly into the conversation and asking about it means the review process consumes the main conversation's context space, and if there are many files involved, the conversation can get unwieldy. /code-review currently runs as a background Subagent with its own independent context window — the file-by-file analysis doesn't consume the main conversation's space, and only the final result gets sent back.
Another difference is the default review scope. Asking directly in conversation means the scope is entirely whatever you pasted or asked about; /code-review has a clearly defined default behavior (reviewing the current diff, or a specified PR), meaning you don't need to manually copy and paste the code you want reviewed — it reads the actual changed content directly. For situations where there's already a clear diff or PR, /code-review is usually more convenient than pasting code manually; but if you just want to quickly discuss one small piece of logic, asking directly in conversation might actually be more direct.
If I'm not sure which PR number to use, or unclear what the current diff scope actually is, is there a simple way to check first?
The most direct approach is checking the state with regular git commands before running /code-review: git status shows which files are currently modified, added, or deleted; git diff shows the actual content of the changes. If your changes have already been pushed as a PR, you can check that PR's number directly on GitHub (or whatever code hosting platform you use) and feed that number into the command.
If you're unsure whether there's something not yet committed, a useful habit is asking yourself before running /code-review: "if this review only covers what I haven't committed yet, would it miss something I wanted it to check?" If the answer is yes, you probably want to review an already-submitted PR rather than the current workspace diff, and appending the PR number directly after the command is more accurate in that case.
After a background review finishes, if I feel a suggestion is too vague and I can't tell what it's actually referring to, how do I follow up efficiently?
A more efficient way to follow up is to directly quote the specific text from the review result that's unclear, and ask two things: "exactly which line or function is this suggestion referring to," and "why is this a problem — what would actually happen if I don't change it." This kind of specific follow-up usually gets a more useful answer faster than vaguely asking "what does this mean," because you've already helped narrow down the scope of the question.
If, after following up, you find the suggestion doesn't actually fit your project's real situation (say, the approach it suggests can't be done that way in your project for a specific reason), you can directly explain that context, bringing the conversation to "how should this suggestion be adjusted for our situation" rather than simply accepting or rejecting it outright. This back-and-forth discussion is itself part of judging whether the suggestion genuinely should be adopted — there's no need to rush a decision the moment the result comes back.
If I'm the first person on my team trying to bring /code-review into daily workflow, how should I explain it to teammates and set reasonable expectations?
A more practical approach is to actually run it a few times yourself first, gather concrete cases, and then bring those cases to the team discussion, rather than vaguely saying "this tool is great." For example, you could put together two categories of concrete examples: "cases where it genuinely caught an edge case I hadn't noticed myself" and "cases where its suggestion didn't match our team's conventions and needed human judgment." This lets everyone clearly understand where its strengths and limits actually lie, rather than mistakenly assuming it's an all-powerful automated gatekeeper.
For team communication, the most important mindset to calibrate is: /code-review provides an opinion worth referencing, not a mechanism that replaces human review. Positioning it as "running one pass before human review to filter out obvious issues, so human review can focus its energy where professional judgment is genuinely needed" usually matches actual usage results better than letting people mistakenly think "now that we have this tool, we don't need human review anymore" — and it's less likely to make people lose trust in the tool the first time it hits a limitation, since expectations weren't overinflated to begin with.
If this is your first time running a code review in Claude Code, the most direct way to get started is to open a project that already has some code changes (uncommitted, or already submitted as a PR), and type /code-review into the conversation. This command analyzes the current diff or a specified PR, checks the code for issues item by item, and reports back once it's done. Here's a full walkthrough of what a first-time user typically runs into, showing what actually happens at each step and where beginners tend to get stuck.
/code-review reviews the current diff by default — the changes you've made but may not have committed yet. If you want to review a specific PR, you can append the PR number directly after the command: /code-review <level> <pr#>. A common point of confusion for beginners is not being sure exactly what scope is currently being reviewed; a safer approach is to run git status or git diff first to confirm what changes actually exist right now, then issue /code-review, avoiding a mismatch between expected and actual review scope.
/code-review currently runs as a background Subagent, meaning the review process itself (reading files, analyzing) doesn't display live in the conversation — what you see is the reported result once the review finishes, and you can keep working on other things in the same conversation thread while it runs. First-time users often mistake "nothing's moving on screen" for "it's stuck," but this is actually normal — the whole point of background execution is to keep the review process from flooding the conversation. Just wait for the report; if you want to check progress, you can also check whether it's still running in the background.
Once the review is done, the reported content typically points out specific issues (potential edge cases, readability suggestions, whether it follows project conventions). A common mistake at this stage is treating every single suggestion as a mandatory requirement to fix — in reality, these are suggestions, and you still need to apply your own understanding of the code to judge which ones genuinely need changing and which can be set aside for now. If a suggestion seems to touch on logic you're not familiar with, asking directly in the same conversation, "what exactly is this suggestion referring to, and why is it a problem," is usually faster than guessing on your own.
The first common mistake is treating /code-review as a one-shot, black-box operation you don't need to think about further. A better mindset is treating it like feedback from "an experienced colleague who doesn't know your team's specific conventions" — the issues it catches are usually worth taking seriously, but whether to actually act on them still depends on combining it with your own understanding of the project's context. The second mistake is getting the review scope wrong — for instance, assuming you're reviewing an entire file when you're actually only reviewing the changed portion of the diff, missing old code that wasn't touched but genuinely has an issue. If you need to review an entire file rather than just the changed part, say so explicitly.
The most practical advice for a first-time user: try it once on a branch with limited blast radius, where an imperfect review result won't have serious consequences, and actually get a feel for what kinds of issues it catches compared to your own usual review habits, before deciding whether to fold it into your regular development workflow. After running it once or twice, you'll have a clearer sense of what kind of issues it's good at catching (obvious missing edge cases, for instance) and which kinds probably still need your own judgment based on project context (whether something follows an unwritten team convention, say).