AI Code Review Checklist — Ship Better with AI Help

AI Code Review Checklist

Correctness

• Code compiles/runs without errors
• All tests pass (existing + new)
• Edge cases handled (null, empty, boundary values)
• Error messages are helpful, not generic

AI-Specific Checks

• No hallucinated imports (packages that do not exist)
• No phantom API endpoints (URLs that were made up)
• No outdated patterns (deprecated APIs, old syntax)
• Function signatures match actual library versions
• No circular dependencies introduced

Security

• No hardcoded secrets or API keys
• User input is validated and sanitized
• SQL queries use parameterized statements
• No eval() or dynamic code execution
• Auth checks on protected routes

Performance

• No N+1 query patterns
• Large lists are paginated
• Expensive operations are cached or lazy-loaded
• No unnecessary re-renders (React)

Maintainability

• Code follows project conventions (CLAUDE.md)
• No over-engineering (YAGNI)
• Variable names are descriptive
• No dead code or commented-out blocks

---

## AI-Specific Pitfalls

### 1. Hallucinated Imports
AI invents packages that sound real but do not exist:

```python
# AI wrote this — package does not exist!
from fastapi_ratelimit import RateLimiter  # FAKE

# Verify: pip install fastapi_ratelimit → ERROR
# Real solution: use slowapi or custom middleware

Fix: Run pip install or npm install BEFORE merging. Check that all imports resolve.

2. Phantom API Endpoints

AI makes up API URLs based on naming conventions:

// AI assumed this endpoint exists — it does not!
const users = await fetch("/api/v2/users/bulk-update");

// Verify: Check your API docs or route files

Fix: Cross-reference every API call with your actual route definitions.

3. Outdated Patterns

AI uses deprecated APIs from its training data:

// AI used old React pattern
componentDidMount() { ... }  // Class component — should be useEffect

// AI used old Node.js
fs.readFile(path, 'utf8', callback)  // Callback — should be fs.promises

Fix: Check that generated code uses current APIs for your dependency versions.

4. Over-Engineering

AI loves abstractions, even when they are not needed:

// AI created a full factory pattern for a one-time operation
class UserServiceFactory {
  createService(type: string): IUserService { ... }
}

// You just needed:
async function getUser(id: string) { ... }

Fix: Ask "would I write this abstraction by hand?" If not, simplify.

5. Confident But Wrong

AI writes plausible-looking code that has subtle bugs:

# Looks correct, but off-by-one in pagination
items = db.query(Item).offset(page * page_size).limit(page_size)
# Should be: .offset((page - 1) * page_size)

Fix: Always verify business logic, especially math, dates, and pagination.

Review Process

Step 1: Compile & Run (30 seconds)

npm run build  # or equivalent
npm test

If it does not build, stop. Send back to AI.

Step 2: Dependency Check (1 minute)

# Check all imports actually exist
npm ls  # Node.js
pip check  # Python

Step 3: Quick Scan (2 minutes)

• Read the diff, not the full files
• Look for AI-specific pitfalls above
• Check file names and structure match conventions

Step 4: Deep Review (5-10 minutes)

• Verify business logic
• Check security (OWASP basics)
• Run through the full checklist above

FAQ

Q: Why do I need a special checklist for AI code? A: AI introduces unique failure modes (hallucinated imports, phantom APIs, outdated patterns) that traditional code review checklists do not cover.

Q: Should I review AI code differently than human code? A: Yes — trust but verify. AI code is more likely to be syntactically correct but semantically wrong. Focus on logic and dependencies, not formatting.

Q: How long should an AI code review take? A: 5-15 minutes for most changes. The checklist helps you focus on the highest-risk areas first.