01 · Reality check
What Claude actually does well here
Good at
- Tracing a focused change across related files
- Finding missing edge-case and regression tests
- Turning a review brief into structured questions
- Explaining unfamiliar code and likely data flow
- Suggesting maintainability improvements after risk review
Not the right tool for
- Proving production safety or performance
- Replacing a security specialist on high-impact systems
- Knowing unseen configuration, generated code or runtime state
- Guaranteeing that a vulnerability was not missed
- Approving a merge without human ownership
02A · Working notes
Start with the contract, not the style
A review is only useful when the reviewer knows what the change is supposed to do. Begin with the issue, acceptance criteria, supported inputs, expected outputs and non-goals. Include the smallest relevant diff instead of a whole repository dump. If the change is a bug fix, show the failing example or regression test. If it is a feature, state the user-visible behaviour and the invariants that must remain true. Claude can then compare the implementation with an explicit contract rather than judging code by surface patterns.
Ask for style suggestions separately. Mixing formatting preferences with correctness and security findings makes the important issues harder to see. A good first pass should return only defects, likely defects and missing tests, each tied to evidence. This keeps the review useful when the code is ordinary but correct, and prevents a long list of low-value rewrites from obscuring a real authorization or data-integrity problem.
Give Claude enough context to trace behaviour
Paste the changed files plus the interfaces they call, the relevant schema or types, and the tests that describe the current behaviour. For a pull request, include the base branch summary and any migration, configuration or feature-flag changes. Say explicitly which files are missing. Ask Claude to label every claim as observed in the supplied code, inferred from naming or dependent on an unseen file. That simple distinction is one of the best protections against a plausible invented explanation.
For a large repository, use passes. First ask for a map of the changed path and its trust boundaries. Next ask it to inspect one risk category, such as input validation or concurrency. Finally ask for a test plan. Narrow passes are easier to verify than one request to find everything, and they let you stop when the context no longer represents the real change.
Review correctness and edge cases
Ask whether the implementation works for empty, duplicate, malformed, delayed, repeated and unauthorized inputs. Have Claude identify the state transition, the source of truth and the error path for each important operation. For a web handler, trace request parsing, validation, business logic, persistence and response serialization. For a background job, trace retries, idempotency, partial failure and observability. For a data transformation, compare input cardinality, null handling, ordering and units.
Do not accept a finding because it sounds technical. Open the referenced lines, construct the smallest counterexample and check whether a test already covers it. A finding that depends on an assumption should be phrased as a question and assigned to the person who can confirm the assumption. The output you want is a short list of reproducible risks, not a performance of certainty.
Use a separate security and privacy pass
Security review deserves its own prompt and its own owner. Ask Claude to inspect authentication and authorization boundaries, tenant isolation, user-controlled redirects, injection paths, secret handling, file uploads, logging, rate limits and sensitive data exposure. Tell it what the application considers sensitive and which trust boundaries exist. Ask for the attack precondition, affected asset, likely impact and a safe verification step.
Treat this as triage, not a security certification. Claude may miss a vulnerability, misunderstand deployment controls or recommend a fix that creates a new problem. Never paste live secrets, production tokens or unnecessary personal data into an unapproved account. For a high-impact issue, reproduce in a safe environment and involve a qualified security reviewer. Keep the original finding, decision and remediation in the review record so the team can learn from it.
Turn findings into tests before changing code
For each accepted defect, ask Claude to propose a minimal regression test that fails before the fix and passes after it. Review the test for the same blind spot as the finding: a test that repeats the implementation's assumptions will not protect you. Include boundary values, authorization variants and failure handling where they matter. For integration behaviour, use a realistic fixture or contract test instead of mocking away the interesting part.
Then make the fix independently, run the focused test, and run the broader suite. Ask Claude to review the new diff for whether it actually addresses the original scenario without weakening another invariant. This loop converts a conversational suspicion into executable evidence. It also gives future reviewers a durable explanation of why a line exists, which is more valuable than preserving an AI chat transcript alone.
Ask for maintainability feedback only after safety
Once correctness and security are covered, ask whether the change is understandable and proportionate. Useful questions include: does the name match the domain, is the error observable, is the abstraction needed, does the code duplicate a policy, and will the next engineer know what must not change? Ask Claude to distinguish a real maintenance risk from a personal preference.
Prefer small improvements that reduce cognitive load or make an invariant explicit. Avoid broad refactors in the same change as a security or behaviour fix unless the refactor is necessary and separately tested. Claude is good at suggesting clearer decomposition, but it cannot know your team's operational history, release constraints or future ownership unless you provide that context. The human reviewer decides whether a cleaner design is worth the scope and risk.
Use a repeatable review prompt
A reusable prompt should force scope, evidence, severity and uncertainty. It should tell Claude not to invent files, APIs, test results or runtime behaviour. Require file and line references for observed claims, a short reproduction or reasoning path, and a recommendation that preserves the stated contract. Ask it to return at most a small number of findings and to say when it found no material issue in a category.
Keep the prompt beside the repository's contribution guidance, but do not turn it into an automatic approval policy. A project can use Claude as a second set of eyes in pull requests, local review or pre-merge analysis. The exact interface changes, so describe the evidence you supplied rather than assuming the model can see the branch, CI, deployment or issue tracker.
Know what Claude cannot establish
A code review model cannot prove that production configuration matches the repository, that a dependency is safe, that a distributed system behaves under real load, or that a policy is legally sufficient. It may not see generated code, environment variables, infrastructure, feature flags, database contents or the user journey outside the supplied files. It can also miss subtle races and confidently misunderstand a framework.
Use the review to choose better verification: run the tests, inspect logs in a safe environment, check dependency and infrastructure changes, exercise permission cases, and get specialist review where the impact warrants it. If Claude says a change is safe, translate that into specific evidence you can obtain. The useful result is not a confidence score. It is a clearer list of questions, tests and decisions before a human accepts the change.
02 · The method
Step by step
- 1
Write the intended contract
State what the change must do, what must not change, and how success will be tested.
- 2
Provide a bounded evidence packet
Include the focused diff, relevant interfaces, schemas, tests and constraints. Name anything Claude cannot see.
- 3
Run a correctness pass
Ask for ranked findings with file references, counterexamples and uncertainty labels.
- 4
Run a dedicated security pass
Inspect trust boundaries, permissions, injection, secrets, uploads, logging and tenant isolation.
- 5
Convert accepted findings to tests
Create a regression test before or alongside the fix, then run focused and broad checks.
- 6
Make a human release decision
Review the final diff and evidence, especially for auth, data, payments and production changes.
03 · Use this now
Copy-paste prompt for an evidence-led review
Copy and paste
Act as a careful code reviewer. Review only the evidence I provide; do not invent files, runtime behaviour, test results, APIs or requirements. Change goal and acceptance criteria: [PASTE] Diff and relevant code: [PASTE] Constraints, threat model and tests: [PASTE] Return at most five material findings. For each, include: severity (blocker, high, medium, low), file and line, the exact evidence, a concrete failure scenario, why it violates the contract or creates risk, and a minimal fix or test. Separate observed facts from inferences. Check correctness, edge cases, authorization, input handling, secrets, data exposure, concurrency, error handling and missing regression tests. If a category has no material finding, say so. Do not approve the change; finish with a verification plan a human reviewer can run.
04 · Avoid these
Common mistakes
- Asking for a generic review without the intended contract
- Pasting secrets or unnecessary personal data
- Accepting a finding without opening the referenced code
- Mixing low-value style comments with security risks
- Skipping tests because the review sounds confident
- Treating no findings as a security certification
05 · Questions
Frequently asked questions
Can Claude review a pull request?
Yes, if you provide the change and enough surrounding context. It can identify likely correctness issues, missing tests, unclear logic and some security risks. It cannot see or prove unseen runtime state, deployment configuration or production behaviour. Use it as a second reviewer and verify findings before acting.
Should I give Claude my whole repository?
Usually start with a bounded evidence packet: the diff, changed files, relevant interfaces, tests and configuration assumptions. A whole repository can add noise and may contain secrets or private data. State what Claude has not seen so it does not infer that missing context is safe.
Can Claude find security vulnerabilities?
It can surface some common risks and help structure a threat-model review, but it cannot guarantee that code is secure. Separate security from style, provide the trust boundaries, reproduce important findings safely and involve a qualified reviewer for high-impact systems.
How do I stop Claude from inventing a bug?
Require file and line references, the exact evidence, a failure scenario and an uncertainty label. Then inspect the code and run a minimal reproduction or test. Findings based on unseen files should be questions, not asserted defects.
Should Claude approve my code?
No. It can recommend whether more verification is needed, but a human owner should decide whether to merge. The decision must account for tests, operational context, data sensitivity, release risk and the people responsible for the system.
What should I ask Claude after fixing a finding?
Give it the new diff and the regression test, then ask whether the fix addresses the original scenario, introduces a new edge case or weakens another invariant. Still run the test suite and inspect the final code yourself.
Related guides
Primary sources
- Anthropic Claude Code: Set up Claude Code
- Anthropic Claude Code: CLI reference
- OWASP: Code Review Guide
Product menus and plan limits change. The linked vendor documentation is the authority when your screen differs.