A Maintainer's Guide to Reviewing Code with Claude

AI code review is valuable when it expands a maintainer's attention, not when it replaces engineering judgment. Claude can trace control flow, compare a diff with a stated contract, and enumerate failure modes quickly. It can also misunderstand repository conventions, invent a requirement, or confidently report an issue that disappears once the surrounding code is considered.

The useful question is therefore not “Can Claude approve this pull request?” It is “How can Claude help a qualified reviewer find and test risks that might otherwise be missed?”

Start With a Review Packet

A raw diff rarely contains enough information for a meaningful review. Give Claude a compact review packet containing:

• the ticket or design objective;
• the expected behavior and explicit non-goals;
• the relevant diff and nearby interfaces;
• repository conventions that affect the change;
• test commands and supported runtime versions;
• known security, privacy, or compatibility constraints.

Remove secrets, customer data, credentials, private keys, and unrelated proprietary code before sharing any material. Follow your organization's approved tooling and data-retention policy.

Use an initial prompt that makes the decision boundary clear:

Act as a senior maintainer performing a risk-focused review.

Objective: [ticket outcome]
Non-goals: [what this change intentionally does not solve]
Compatibility requirements: [API/runtime/data constraints]
Validation commands: [tests, type checks, migrations]

Review the supplied diff for correctness, security, compatibility,
failure handling, data integrity, observability, and missing tests.
Report only actionable findings. For each finding include:
1. file and relevant code location;
2. concrete failure scenario;
3. expected impact;
4. evidence from the supplied code;
5. the smallest reasonable fix or test.

Separate confirmed defects from questions and low-confidence risks.
Do not approve or reject the pull request.

That last instruction matters. The model is assisting the review; it does not own the repository, production risk, or merge decision.

Review in Four Passes

1. Reconstruct the change

First ask Claude to describe the old behavior, new behavior, changed interfaces, and data flow. Compare this explanation with the ticket and the actual diff. If the reconstruction is wrong, correct the context before asking for findings. A model working from an incorrect mental model will produce polished but irrelevant feedback.

2. Inspect by risk category

Avoid a single vague request to “find bugs.” Run focused passes:

• Correctness: boundary values, null or empty input, ordering, state transitions, and incomplete branches.
• Security: authorization checks, injection surfaces, unsafe deserialization, secret exposure, and trust boundaries.
• Compatibility: public APIs, database migrations, serialized formats, configuration defaults, and rollback behavior.
• Reliability: timeouts, retries, idempotency, concurrency, partial failure, and resource cleanup.
• Operability: logs, metrics, error messages, feature flags, and a safe recovery path.
• Tests: untested contracts and failure paths, not merely a demand for more coverage.

For a database change, for example, ask what happens when the application and schema versions are temporarily mismatched during a rolling deployment. For an API client, ask whether retries can duplicate a write. Concrete operational scenarios produce better findings than abstract checklists.

3. Challenge every finding

Treat each AI finding as a hypothesis. Open the cited code and answer:

1. Is the described path reachable?
2. Does another layer already enforce the missing condition?
3. Can a minimal test reproduce the failure?
4. Is the recommendation consistent with local architecture?
5. Would the proposed fix create a new regression?

Discard style opinions that are not connected to readability, maintainability, or an established repository rule. Ask Claude to retract any claim it cannot support with supplied evidence. This reduces review noise and protects the author's time.

4. Convert accepted risks into verification

An accepted comment should end in a test, an observable invariant, or an explicit design decision. Ask for a minimal regression test, but review the generated test just as carefully as production code. A test that restates the implementation may pass while failing to verify the contract.

Handling Large Pull Requests

For a large change, review in layers: public interfaces first, then data models and migrations, then core behavior, then adapters and UI, and finally tests. Maintain a short risk register so conclusions remain consistent across prompts. Do not paste the same enormous repository snapshot repeatedly; provide the narrow context required for each layer and link it back to the shared objective.

Claude's current models are designed for tool-using and coding workflows, but model capability does not remove the need for repository-specific evidence. Review Anthropic's current model information before standardizing a workflow because availability and behavior evolve over time: Claude Sonnet 5.

A Practical Definition of Done

Before the human reviewer approves the pull request, confirm that:

• the implementation satisfies the ticket and declared non-goals;
• every accepted AI finding was independently verified;
• security and permission checks occur at the correct trust boundary;
• schema and API changes are compatible or deliberately versioned;
• failure, retry, and rollback behavior are understood;
• regression tests check externally meaningful behavior;
• logs and metrics make important failures diagnosable;
• generated suggestions do not introduce copied secrets, licenses, or unreviewed dependencies;
• the designated maintainer, not the model, owns the final decision.

The best result is not a longer review. It is a smaller set of defensible findings, tied to real failure scenarios and backed by verification.