# AI Code Review Checklist — Ship Better with AI Help

> Structured checklist for reviewing AI-generated code before merging. Covers correctness, security, performance, maintainability, and AI-specific pitfalls like hallucinated imports and phantom APIs.

## Install

Paste the prompt below into your AI tool:

## Quick Use

Before merging AI-generated code, run through this checklist:

```markdown
## 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
```

---

## Intro

AI coding agents write functional code fast, but they also introduce unique failure modes — hallucinated package imports, phantom API endpoints, outdated patterns, and over-engineered abstractions. This checklist is a structured review process specifically designed for AI-generated code, covering the standard quality checks plus AI-specific pitfalls that human-written code rarely has. Best for developers and team leads reviewing AI-generated PRs. Works with: any codebase, any AI agent.

---

## 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:

```typescript
// 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:

```javascript
// 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:

```typescript
// 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:

```python
# 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)
```bash
npm run build  # or equivalent
npm test
```
If it does not build, stop. Send back to AI.

### Step 2: Dependency Check (1 minute)
```bash
# 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.

---

## Source & Thanks

> Compiled from production experience reviewing thousands of AI-generated PRs.
>
> Share this checklist with your team to improve AI code quality.

---

<!-- ZH -->

## 快速使用

合并 AI 生成的代码前，运行以下检查：

```markdown
- [ ] 代码能编译运行
- [ ] 没有虚构的 import（不存在的包）
- [ ] 没有虚构的 API 端点
- [ ] 没有硬编码的密钥
- [ ] 没有过度工程化
```

---

## 简介

AI 编码 Agent 写代码快，但也引入独特的失败模式 — 虚构包名、虚构 API、过时模式和过度工程。本清单是专为 AI 生成代码设计的结构化审查流程，覆盖标准质量检查和 AI 特有陷阱。适合审查 AI 生成 PR 的开发者和技术负责人。

---

## 来源与感谢

> 来自审查数千个 AI 生成 PR 的生产经验。

---
Source: https://tokrepo.com/en/workflows/ec06a6a1-4564-4862-bfe4-4166c74fee60
Author: Prompt Lab