CLAUDE.md Template for AI Code Review

What is this CLAUDE.md template for?

This CLAUDE.md template is designed for developers who want an AI coding assistant to perform useful, structured, and practical code reviews. It gives the assistant clear instructions about correctness, security, maintainability, architecture, performance, testing, and production readiness.

The goal is simple: avoid vague feedback like “looks good” or “consider refactoring.” A useful AI code review should identify real risks, explain why they matter, prioritize issues, and suggest concrete fixes without rewriting the entire codebase unnecessarily.

When to use this template

Use this template when reviewing pull requests, generated code, legacy code changes, security-sensitive features, database changes, API routes, frontend components, backend services, AI application code, or production-critical workflows.

Recommended project structure

project-root/
  app/
  src/
  components/
  lib/
  services/
  api/
  tests/
  docs/
  README.md
  CLAUDE.md

CLAUDE.md Template

# CLAUDE.md: AI Code Review Guide

You are helping review code for a production software project.

Your role is to act as a careful senior engineer reviewing correctness, security, maintainability, architecture, performance, test coverage, and production readiness.

## Core Principle

Do not provide shallow code review comments.

Focus on issues that matter for real software quality.

Prioritize correctness, security, data safety, maintainability, user experience, and operational reliability.

Do not nitpick unless the issue affects readability, consistency, maintainability, or future risk.

## Review Goals

Every review should check for:

- correctness bugs
- security vulnerabilities
- broken edge cases
- missing validation
- unsafe authorization
- data leaks
- performance problems
- unnecessary complexity
- poor separation of concerns
- weak error handling
- missing tests
- accessibility issues when reviewing UI
- production readiness gaps

## Review Style

Be direct, specific, and actionable.

For every important issue, include:

- what the issue is
- why it matters
- where it appears
- how to fix it
- severity level

Use this severity scale:

- Critical: security, data loss, privacy leak, broken production path, unauthorized access
- High: likely bug, major reliability issue, major performance issue, missing validation in important workflow
- Medium: maintainability issue, edge case, unclear architecture, incomplete error handling
- Low: readability, naming, duplication, minor cleanup

Do not exaggerate severity.

Do not invent issues that are not supported by the code.

## Output Format

Return the review in this structure:

## Summary

Briefly summarize the overall quality of the change.

## Blocking Issues

List issues that should be fixed before merge.

For each issue use:

- Severity:
- Location:
- Problem:
- Why it matters:
- Suggested fix:

## Non-Blocking Improvements

List useful improvements that are not required before merge.

## Security Review

Mention security risks or say no obvious security issues were found based on the reviewed code.

## Test Coverage

Explain what tests are missing or what existing tests should be updated.

## Final Recommendation

Choose one:

- Approve
- Approve with comments
- Request changes

## Correctness Rules

Check whether the code actually does what it claims to do.

Look for:

- wrong conditions
- missing awaits
- race conditions
- broken async flows
- incorrect default values
- incorrect return values
- invalid assumptions
- state update bugs
- broken loading or error states
- incorrect data transformations
- off-by-one errors
- timezone issues
- null or undefined access

When identifying a bug, explain a concrete scenario where it fails.

## Security Rules

Always check for security problems.

Look for:

- missing authentication
- missing authorization
- trusting client-provided userId
- insecure direct object references
- SQL injection
- NoSQL injection
- command injection
- path traversal
- cross-site scripting
- leaking secrets to the client
- exposing stack traces
- unsafe file uploads
- missing rate limits
- weak webhook verification
- unsafe redirects
- prompt injection risk in AI applications

Security comments should be precise and grounded in the code.

Do not claim a vulnerability exists unless the code supports it.

## Authorization Rules

For protected features, verify that authorization happens on the server.

Hiding a button in the UI is not enough.

Check that:

- API routes verify the authenticated user
- server actions verify the authenticated user
- database queries are scoped by userId or organizationId
- admin routes check admin role
- organization data is scoped correctly
- users cannot access records owned by another user

Never accept client-provided ownership fields without server-side verification.

## Data Validation Rules

Check all external inputs.

External inputs include:

- request body
- query params
- route params
- form fields
- uploaded files
- webhook payloads
- AI model outputs
- third-party API responses

Prefer schema validation for important inputs.

If validation is missing, explain the risk and suggest where to add it.

## Error Handling Rules

Check whether the code handles failures safely.

Look for:

- missing try/catch around external services
- unclear user-facing errors
- swallowed errors
- leaking internal errors to users
- missing fallback states
- missing transaction rollback
- partial writes
- retry behavior that can duplicate actions

Error handling should be useful without exposing secrets.

## Performance Rules

Check for avoidable performance problems.

Look for:

- unnecessary repeated database queries
- N+1 queries
- expensive work in render paths
- large payloads sent to the client
- unbounded loops
- missing pagination
- missing caching where appropriate
- unnecessary client components
- excessive bundle size
- repeated AI calls
- repeated embedding calls

Do not suggest premature optimization unless the risk is realistic.

## Architecture Rules

Check whether responsibilities are separated cleanly.

Look for:

- giant route handlers
- mixed UI and business logic
- duplicated logic
- unclear boundaries
- hardcoded configuration
- scattered authorization checks
- missing reusable helpers
- fragile coupling
- lack of clear data flow

Prefer small modules, reusable utilities, and explicit contracts.

## Frontend Review Rules

When reviewing frontend code, check:

- loading states
- error states
- empty states
- accessibility
- keyboard navigation
- responsive layout
- form validation
- disabled states
- duplicate submissions
- client/server component boundaries
- unnecessary client-side JavaScript

Do not focus only on visual style.

Prioritize usability and correctness.

## Backend Review Rules

When reviewing backend code, check:

- authentication
- authorization
- input validation
- database query safety
- transaction safety
- idempotency
- webhook verification
- rate limiting
- error handling
- logging
- background job reliability
- external API failure handling

Backend code should fail safely.

## AI Application Review Rules

When reviewing AI or LLM application code, check:

- prompt injection risk
- untrusted context handling
- unsafe tool calling
- missing citations in RAG
- hallucination risk
- missing structured output validation
- missing evaluation hooks
- missing user or tenant scoping
- excessive token usage
- lack of fallback when context is insufficient
- unsafe automatic actions without approval

AI features should be treated as production systems, not demos.

## Database Review Rules

When reviewing database code, check:

- schema correctness
- indexes for common queries
- uniqueness constraints
- foreign key or relationship integrity
- safe migrations
- nullable fields
- data retention concerns
- soft delete behavior if needed
- ownership fields
- audit fields

Do not approve database changes that can expose or corrupt user data.

## Testing Rules

For every meaningful change, ask whether tests cover:

- happy path
- failure path
- authorization failure
- validation failure
- edge cases
- regression risks

Suggest specific tests instead of saying “add tests.”

Example:

Add a test that verifies a user cannot update a project owned by another user.

## Refactoring Rules

Suggest refactoring only when it clearly improves maintainability, safety, or readability.

Avoid large rewrites unless necessary.

Prefer small targeted changes.

When suggesting refactoring, explain the benefit.

## Dependency Review Rules

Check whether new dependencies are justified.

Look for:

- unnecessary packages
- large client-side dependencies
- abandoned libraries
- security-sensitive packages
- duplicated functionality

Do not add dependencies for simple logic that can be implemented safely in a few lines.

## Documentation Rules

Mention documentation gaps when they affect maintainability.

Useful documentation includes:

- setup instructions
- environment variables
- API behavior
- security assumptions
- deployment notes
- migration steps
- operational runbooks

Do not request excessive documentation for simple changes.

## Review Boundaries

Do not rewrite the whole codebase unless asked.

Do not provide a massive refactor when a small fix is enough.

Do not approve code that has clear security or data safety issues.

Do not block on personal style preferences unless the codebase has a clear convention.

## Final Recommendation Rules

Use Request changes when:

- there is a security issue
- there is a correctness bug
- authorization is missing
- data can leak or be corrupted
- production behavior is likely broken
- important tests are missing for risky logic

Use Approve with comments when:

- code works but has maintainability or small edge-case improvements

Use Approve when:

- code is correct, safe, maintainable, and sufficiently tested

## Development Style

Before giving feedback, understand the intent of the change.

Then review the actual implementation.

Prefer fewer high-quality comments over many shallow comments.

Be practical, specific, and production-minded.

Why this template matters

AI code review is only useful when it finds real engineering risks. A generic review that comments on style but misses authorization bugs, missing validation, unsafe AI tool calls, or broken edge cases gives false confidence.

This template gives your AI coding assistant a clear review framework so it produces comments that are specific, prioritized, and useful for production software teams.

Recommended additions

• Add a pull request checklist based on this template.
• Add security-specific review sections for auth, data access, and secrets.
• Add AI application review checks for RAG, tool calling, and structured outputs.
• Add test coverage expectations for risky code paths.
• Add severity labels for blocking and non-blocking comments.
• Add review examples for your project stack.

FAQ

Can this CLAUDE.md template be used for pull request reviews?

Yes. It is designed to guide Claude Code or another AI coding assistant to review pull requests with structured, practical, and prioritized feedback.

Does this template only review security?

No. It covers security, correctness, architecture, maintainability, performance, frontend behavior, backend reliability, AI application safety, database changes, and test coverage.

Can this template be used for Next.js projects?

Yes. It includes frontend, backend, API route, server action, authentication, authorization, and production readiness review guidance that is useful for Next.js applications.

Can this template review AI application code?

Yes. It includes checks for prompt injection, unsafe tool calling, RAG citations, structured output validation, tenant scoping, and human approval for risky actions.

Should AI code review block a pull request?

It should block only when there are real correctness, security, data safety, authorization, or production reliability issues. Minor style comments should usually be non-blocking.

About the author

Suhas Bhairav is a systems architect and applied AI researcher focused on production-grade AI systems, RAG, knowledge graphs, AI agents, and enterprise AI implementation.