Articles/Claude Code

⟐ Claude Code/2026-04-07Advanced

Claude Code × Python FastAPI in Production — Architecture, pytest, and Docker Deployment

Building production-ready Python FastAPI servers with Claude Code as an AI pair programmer — Pydantic v2, pytest automation, Docker, and CI/CD, with working code at each step.

Claude Code²⁵⁵ Python¹⁷FastAPIpytestDocker⁵API DevelopmentBackend⁴ Production²³

✦ Premium Article

A week after adding Redis caching to one of my side-project APIs, the response-time graph looked exactly the same as before. No errors. Nothing unusual in the logs. The cache simply never hit once.

The cause was the cache key. The decorator built it from str(kwargs), and kwargs carried the injected database session — whose default repr contains a memory address. Every request produced a different key. Redis had become a write-only warehouse.

FastAPI is fast, type-safe, and pleasant to write async code in, and pairing it with Claude Code gets a production skeleton standing in remarkably little time. But code that looks like it works tends to settle in quiet places like that one.

What follows is the workflow for building a production FastAPI server with Claude Code, organized around implementation patterns — plus the defects this workflow tends to produce, each one run locally and measured rather than guessed at. As an indie developer shipping alone, I have found that generating faster and distrusting the output are not competing habits. They fund each other.

Written with one situation in mind: you know Python and FastAPI well enough, but stall just before production-grade architecture, testing, and deployment.

Prerequisites and Setup

Required Environment

Python 3.12+
Claude Code CLI (latest version)
Docker Desktop
Git

For Claude Code installation and initial setup, see the Claude Code Project Initialization Automation Guide.

Project Structure Overview

Here's the production project layout we'll build:

fastapi-app/
├── CLAUDE.md              # Design guidelines for Claude Code
├── app/
│   ├── main.py            # FastAPI application entry point
│   ├── api/
│   │   └── v1/
│   │       ├── router.py  # API v1 router
│   │       ├── users.py   # User endpoints
│   │       └── items.py   # Item endpoints
│   ├── core/
│   │   ├── config.py      # Environment and settings management
│   │   ├── security.py    # Auth and JWT
│   │   └── database.py    # SQLAlchemy async session management
│   ├── models/
│   │   ├── user.py        # SQLAlchemy models
│   │   └── item.py
│   └── schemas/
│       ├── user.py        # Pydantic v2 schemas
│       └── item.py
├── tests/
│   ├── conftest.py        # pytest fixtures
│   ├── unit/
│   └── integration/
├── Dockerfile
├── docker-compose.yml
└── .github/workflows/ci.yml

CLAUDE.md Design — Giving Your AI the Right Context

The quality of code Claude Code generates depends directly on how well it understands your project. CLAUDE.md is your technical specification document for Claude Code — the difference between getting generic boilerplate and production-quality code.

Writing an Effective CLAUDE.md

Place this file at the root of your project:

# FastAPI Production API — CLAUDE.md
 
## Technology Stack
- Python 3.12 / FastAPI 0.115+ / Uvicorn
- SQLAlchemy 2.0 (async) + asyncpg (PostgreSQL)
- Pydantic v2 (strict validation mode)
- JWT authentication (python-jose + passlib bcrypt)
- pytest-asyncio + httpx (async testing)
- Docker + docker-compose
 
## Coding Standards
- All functions and classes must have full type hints
- Use async/await consistently — never mix sync and async code
- All endpoint response models must be defined with Pydantic schemas
- Database sessions must be obtained via Depends() dependency injection
- HTTPExceptions are centralized in app/core/exceptions.py
 
## Testing Standards
- Write pytest tests alongside every new feature
- Unit tests: pure functions in app/core/
- Integration tests: use real DB (in-memory SQLite for tests)
- Coverage target: 80% minimum
 
## Prohibited Patterns
- Global mutable state
- print() debugging (use logging module)
- Hardcoded credentials (environment variables only)

With this context in place, Claude Code will automatically know to use async SQLAlchemy, write pytest-asyncio tests, and maintain type safety throughout — without needing to be reminded on every prompt.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Learn the exact prompting strategies to use Claude Code for accelerating FastAPI project design, coding, and testing

✦Master the full production workflow — pytest, Docker, GitHub Actions CI/CD — with working code you can use immediately

✦Discover how to combine Claude Code's multi-agent and Hooks features to automatically maintain backend API quality

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Step 1: Project Initialization — Generating the Scaffold

Start Claude Code and let it create the entire project foundation in one shot:

mkdir fastapi-app && cd fastapi-app
# Place CLAUDE.md first (content above)
claude

Use this prompt:

Following the CLAUDE.md specifications, generate the complete project scaffold
for a production FastAPI API.

Required files:
1. app/core/config.py — environment variable management using pydantic-settings
2. app/core/database.py — SQLAlchemy 2.0 async engine + session factory
3. app/core/security.py — JWT access token generation and verification
4. app/main.py — lifespan events, CORS middleware, health endpoint
5. requirements.txt — pinned versions
6. pyproject.toml — ruff + mypy configuration

Create all files now.

Generated Code Example

Here's the app/core/config.py Claude Code produces:

# app/core/config.py
from pydantic_settings import BaseSettings, SettingsConfigDict
from functools import lru_cache
 
class Settings(BaseSettings):
    """Application settings — auto-loaded from environment variables."""
 
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        case_sensitive=False,
    )
 
    # Application
    app_name: str = "FastAPI Production API"
    app_version: str = "1.0.0"
    debug: bool = False
 
    # Database
    database_url: str = "postgresql+asyncpg://user:password@localhost/dbname"
    database_pool_size: int = 10
    database_max_overflow: int = 20
 
    # JWT
    secret_key: str  # Required: use 256-bit random string in production
    algorithm: str = "HS256"
    access_token_expire_minutes: int = 30
 
    # CORS
    allowed_origins: list[str] = ["http://localhost:3000"]
 
@lru_cache
def get_settings() -> Settings:
    """Return singleton settings instance (for DI)."""
    return Settings()

The @lru_cache pattern ensures settings are loaded only once per process, which is important when using Depends(get_settings) across many request handlers. Claude Code applies these kinds of production best practices automatically when the CLAUDE.md sets clear expectations.

Step 2: Model and Schema Design — Pydantic v2 × SQLAlchemy 2.0

When designing models with Claude Code, the key is providing rich, specific requirements rather than vague descriptions:

Create app/models/user.py and app/schemas/user.py.

User model requirements:
- id: UUID (auto-generated)
- email: unique constraint, max 255 chars
- hashed_password: str
- is_active: bool (default True)
- is_superuser: bool (default False)
- created_at / updated_at: auto-managed timestamps

Three Pydantic schemas:
- UserCreate: for registration input (plain text password)
- UserRead: for API responses (password excluded)
- UserUpdate: for partial updates (all fields Optional)

Use SQLAlchemy 2.0 Mapped[T] annotation style throughout.

The generated app/models/user.py:

# app/models/user.py
import uuid
from datetime import datetime
from sqlalchemy import String, Boolean, func
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
class Base(DeclarativeBase):
    pass
 
class User(Base):
    __tablename__ = "users"
 
    id: Mapped[uuid.UUID] = mapped_column(
        primary_key=True, default=uuid.uuid4, index=True
    )
    email: Mapped[str] = mapped_column(
        String(255), unique=True, index=True, nullable=False
    )
    hashed_password: Mapped[str] = mapped_column(nullable=False)
    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
    is_superuser: Mapped[bool] = mapped_column(Boolean, default=False)
    created_at: Mapped[datetime] = mapped_column(
        default=func.now(), server_default=func.now()
    )
    updated_at: Mapped[datetime] = mapped_column(
        default=func.now(), onupdate=func.now(), server_default=func.now()
    )

SQLAlchemy 2.0's Mapped[T] annotations provide full IDE autocomplete and pass mypy's strict type checking — a major quality-of-life improvement over the older column declaration style. Claude Code generates this modern syntax automatically when you specify the version in CLAUDE.md.

Step 3: API Endpoint Development

For endpoint generation, describe your requirements layer by layer:

Implement app/api/v1/users.py.

Endpoints:
- POST /users/ — new user registration (with duplicate email check)
- GET /users/me — get current authenticated user
- GET /users/{user_id} — get user details (superusers only)
- PATCH /users/{user_id} — update user information
- DELETE /users/{user_id} — soft delete (set is_active=False)

Requirements:
- All endpoints use async def
- DB operations use SQLAlchemy AsyncSession via Depends
- Authentication check via get_current_user dependency
- Return appropriate HTTPExceptions (400/401/403/404)
- All responses typed with UserRead schema

The core of the generated output:

# app/api/v1/users.py
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import select
 
from app.core.database import get_db
from app.core.security import get_current_user, get_password_hash
from app.models.user import User
from app.schemas.user import UserCreate, UserRead, UserUpdate
 
router = APIRouter(prefix="/users", tags=["users"])
 
@router.post("/", response_model=UserRead, status_code=status.HTTP_201_CREATED)
async def create_user(
    user_in: UserCreate,
    db: AsyncSession = Depends(get_db),
) -> UserRead:
    """Register a new user. Returns 400 if the email already exists."""
    result = await db.execute(select(User).where(User.email == user_in.email))
    if result.scalar_one_or_none():
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="This email address is already registered.",
        )
    hashed_pw = get_password_hash(user_in.password)
    db_user = User(email=user_in.email, hashed_password=hashed_pw)
    db.add(db_user)
    await db.commit()
    await db.refresh(db_user)
    return db_user
 
@router.get("/me", response_model=UserRead)
async def read_current_user(
    current_user: User = Depends(get_current_user),
) -> UserRead:
    """Return the currently authenticated user's profile."""
    return current_user

With response_model=UserRead, FastAPI automatically excludes hashed_password from the response — no manual filtering required.

Step 4: pytest Test Suite — Full Async API Testing

FastAPI + SQLAlchemy async testing requires some non-trivial setup. Claude Code handles this complexity gracefully when given the right prompt:

Create tests/conftest.py.

Requirements:
- Use in-memory SQLite (aiosqlite) as the test database
- Reset the database before each test for complete isolation
- Use pytest-asyncio with asyncio_mode = "auto"
- Test endpoints using httpx.AsyncClient
- Fixtures: normal user, superuser, JWT tokens
- Also create pytest.ini with asyncio_mode = auto

The generated tests/conftest.py:

# tests/conftest.py
import pytest
import pytest_asyncio
from httpx import AsyncClient, ASGITransport
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from sqlalchemy.pool import StaticPool
 
from app.main import app
from app.core.database import Base, get_db
from app.core.security import get_password_hash, create_access_token
from app.models.user import User
 
TEST_DATABASE_URL = "sqlite+aiosqlite:///:memory:"
 
test_engine = create_async_engine(
    TEST_DATABASE_URL,
    connect_args={"check_same_thread": False},
    poolclass=StaticPool,  # Required for in-memory sharing
)
 
@pytest_asyncio.fixture(autouse=True)
async def setup_db():
    """Create tables before each test; drop them after."""
    async with test_engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    yield
    async with test_engine.begin() as conn:
        await conn.run_sync(Base.metadata.drop_all)
 
@pytest_asyncio.fixture
async def db_session():
    async with AsyncSession(test_engine) as session:
        yield session
 
@pytest_asyncio.fixture
async def client(db_session: AsyncSession):
    """FastAPI test client with database overridden."""
    app.dependency_overrides[get_db] = lambda: db_session
    async with AsyncClient(
        transport=ASGITransport(app=app), base_url="http://test"
    ) as ac:
        yield ac
    app.dependency_overrides.clear()
 
@pytest_asyncio.fixture
async def normal_user(db_session: AsyncSession) -> User:
    user = User(
        email="test@example.com",
        hashed_password=get_password_hash("testpassword123"),
    )
    db_session.add(user)
    await db_session.commit()
    await db_session.refresh(user)
    return user
 
@pytest_asyncio.fixture
def user_token(normal_user: User) -> str:
    return create_access_token(subject=str(normal_user.id))

Integration Test Examples

# tests/integration/test_users.py
import pytest
from httpx import AsyncClient
 
@pytest.mark.asyncio
async def test_create_user_success(client: AsyncClient):
    response = await client.post(
        "/api/v1/users/",
        json={"email": "new@example.com", "password": "securepass123"},
    )
    assert response.status_code == 201
    data = response.json()
    assert data["email"] == "new@example.com"
    assert "hashed_password" not in data  # Verify password is excluded
 
@pytest.mark.asyncio
async def test_create_user_duplicate_email(client: AsyncClient, normal_user):
    response = await client.post(
        "/api/v1/users/",
        json={"email": normal_user.email, "password": "anypassword"},
    )
    assert response.status_code == 400
 
@pytest.mark.asyncio
async def test_read_current_user(client: AsyncClient, user_token: str):
    response = await client.get(
        "/api/v1/users/me",
        headers={"Authorization": f"Bearer {user_token}"},
    )
    assert response.status_code == 200
    assert response.json()["email"] == "test@example.com"

The app.dependency_overrides pattern is the cornerstone of effective FastAPI testing. By swapping the production database dependency with an in-memory test fixture, tests remain completely isolated, fast, and reproducible.

Run the tests:

pytest --cov=app --cov-report=html tests/
 
# Expected output:
# ==================== 12 passed in 1.83s ====================
# TOTAL: 84%

Step 5: Advanced Error Handling and Middleware Architecture

Production APIs need centralized, consistent error handling. Claude Code excels at generating boilerplate-heavy but critical infrastructure code like this.

Custom Exception Hierarchy

Create app/core/exceptions.py with a custom exception hierarchy.

Requirements:
- Base AppException with status_code, detail, and error_code fields
- Subclasses: NotFoundError, RequestValidationFailure, AuthenticationError, PermissionDeniedError
- Do not reuse the name of any Python builtin or pydantic exception
- FastAPI exception handler that converts these to JSON responses
- Include request_id in every error response for tracing

Generated app/core/exceptions.py:

# app/core/exceptions.py
from fastapi import Request
from fastapi.responses import JSONResponse
import uuid
 
class AppException(Exception):
    """Base exception for all application errors."""
 
    def __init__(
        self,
        status_code: int,
        detail: str,
        error_code: str = "INTERNAL_ERROR",
    ):
        self.status_code = status_code
        self.detail = detail
        self.error_code = error_code
        super().__init__(detail)
 
class NotFoundError(AppException):
    def __init__(self, resource: str, resource_id: str):
        super().__init__(
            status_code=404,
            detail=f"{resource} with id '{resource_id}' was not found.",
            error_code="NOT_FOUND",
        )
 
class RequestValidationFailure(AppException):
    # Deliberately not named ValidationError — that name belongs to pydantic
    def __init__(self, detail: str = "The request payload is invalid."):
        super().__init__(422, detail, "VALIDATION_FAILED")
 
class AuthenticationError(AppException):
    def __init__(self, detail: str = "Authentication required."):
        super().__init__(401, detail, "AUTHENTICATION_REQUIRED")
 
class PermissionDeniedError(AppException):
    # Deliberately not named PermissionError — that name is a builtin
    def __init__(self, detail: str = "Insufficient permissions."):
        super().__init__(403, detail, "PERMISSION_DENIED")
 
# Register with FastAPI in main.py
async def app_exception_handler(request: Request, exc: AppException) -> JSONResponse:
    """Convert AppException subclasses to consistent JSON error responses."""
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "error": {
                "code": exc.error_code,
                "detail": exc.detail,
                # Reuse the id the logging middleware attached, so the error
                # response and the access log line share one identifier.
                "request_id": getattr(request.state, "request_id", str(uuid.uuid4())),
            }
        },
    )

With this pattern, every error your API returns follows a consistent structure. Frontend clients can check error.code to handle specific error types programmatically, rather than parsing free-form error strings.

Two of those class names are chosen deliberately. The obvious names — ValidationError and PermissionError — collide with pydantic.ValidationError and with a Python builtin, and the collision is silent.

I checked this on Python 3.10.12. In a module that defines its own PermissionError, an except PermissionError around real filesystem code no longer catches the builtin:

class PermissionError(AppException):  # shadows the builtin
    ...
 
try:
    open("/tmp/ro_dir/f.txt", "w")   # a genuine EACCES
except PermissionError:
    print("caught")
except Exception as e:
    print("slipped past ->", type(e).__name__, ":", e)

Output:

slipped past -> PermissionError : [Errno 13] Permission denied: '/tmp/ro_dir/f.txt'

Remove the custom class and the same except clause catches it immediately. The failure mode is that your handler misses real permission errors, and because the type name printed in logs is identical either way, nothing in your logs will point at the cause. Naming the classes in the prompt is the cheapest possible fix.

Request Logging Middleware

# app/core/middleware.py
import time
import uuid
import logging
from fastapi import Request, Response
 
logger = logging.getLogger(__name__)
 
async def logging_middleware(request: Request, call_next) -> Response:
    """Log all requests with timing and correlation IDs."""
    request_id = str(uuid.uuid4())[:8]
    start_time = time.perf_counter()
 
    # Attach request_id to request state for use in handlers
    request.state.request_id = request_id
 
    response = await call_next(request)
 
    duration_ms = (time.perf_counter() - start_time) * 1000
    logger.info(
        "HTTP request",
        extra={
            "request_id": request_id,
            "method": request.method,
            "path": request.url.path,
            "status_code": response.status_code,
            "duration_ms": round(duration_ms, 2),
        },
    )
    return response

Add this to app/main.py:

from app.core.middleware import logging_middleware
from app.core.exceptions import AppException, app_exception_handler
 
app = FastAPI(...)
app.middleware("http")(logging_middleware)
app.add_exception_handler(AppException, app_exception_handler)

Every request now produces a structured log entry with timing data. This makes debugging production issues dramatically easier because you can filter logs by request_id and see the full request lifecycle.

Step 6 (Extended): Async Background Tasks and Rate Limiting

Background Task Pattern

For operations that shouldn't block the request-response cycle — sending emails, generating reports, updating caches — use FastAPI's BackgroundTasks:

# app/api/v1/users.py (extended)
from fastapi import BackgroundTasks
from app.services.email import send_welcome_email
 
@router.post("/", response_model=UserRead, status_code=status.HTTP_201_CREATED)
async def create_user(
    user_in: UserCreate,
    background_tasks: BackgroundTasks,
    db: AsyncSession = Depends(get_db),
) -> UserRead:
    """Register user and send welcome email in the background."""
    # ... user creation logic ...
    db_user = User(email=user_in.email, hashed_password=hashed_pw)
    db.add(db_user)
    await db.commit()
    await db.refresh(db_user)
 
    # Enqueue welcome email — doesn't block the response
    background_tasks.add_task(send_welcome_email, email=db_user.email)
 
    return db_user

For more demanding workloads, ask Claude Code to generate a Celery + Redis configuration. The prompt pattern is: "Add Celery task queue support with Redis as the broker. Create a tasks.py with an example email-sending task, and show how to trigger it from a FastAPI endpoint."

Simple Rate Limiting with slowapi

Rate limiting is often overlooked until an API gets abused. Claude Code can add it quickly:

# requirements.txt addition: slowapi
 
# app/main.py (additions)
from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address
from slowapi.errors import RateLimitExceeded
 
limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter
app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
 
# Apply to sensitive endpoints:
@router.post("/auth/token")
@limiter.limit("5/minute")  # Max 5 login attempts per minute per IP
async def login(request: Request, form_data: OAuth2PasswordRequestForm = Depends()):
    ...

The request: Request parameter is mandatory even if the handler never touches it — slowapi locates the caller by that argument name. Dropping it fails loudly rather than silently: the decorator raises at import time with Exception: No "request" or "websocket" argument on function "<function login at ...>", so the process never starts. Verified with a 2/minute limit, the sequence was 200, 200, then 429 on the third call, with _rate_limit_exceeded_handler producing the 429.

One deployment caveat: get_remote_address reads the peer address. Behind a load balancer (Fly.io, Railway, most PaaS) every request appears to come from the same IP, so a per-IP limit turns into a global one. Either swap in a key_func that trusts X-Forwarded-For, or enforce the limit at the proxy.

Claude Code Hooks for Automated Quality Gates

As covered in the Claude Code Hooks Automation Techniques Guide, you can configure Claude Code to automatically run tests after every file modification.

`.claude/settings.json`

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "cd /path/to/fastapi-app && python -m pytest tests/ -x -q --tb=short 2>&1 | tail -20"
          }
        ]
      }
    ]
  }
}

With this configuration, every time Claude Code writes or edits a file, pytest runs automatically. When a test fails, Claude Code sees the output and attempts a fix — establishing a tight "generate → test → fix" loop that produces substantially better code than a single-pass generation approach.

Step 6: Docker Setup — Production-Grade Container Design

Dockerfile Generation Prompt

Create a production-grade Dockerfile.

Requirements:
- Multi-stage build (builder + runtime stages)
- python:3.12-slim base image
- Run as non-root user (security best practice)
- .dockerignore to exclude unnecessary files
- Target image size under 200MB
- Health check configuration

Generated Dockerfile:

# Stage 1: Build dependencies
FROM python:3.12-slim AS builder
 
WORKDIR /build
 
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc libpq-dev \
    && rm -rf /var/lib/apt/lists/*
 
COPY requirements.txt .
RUN pip install --no-cache-dir --user -r requirements.txt
 
# Stage 2: Production runtime
FROM python:3.12-slim AS runtime
 
# Security: create non-root user
RUN useradd --create-home --shell /bin/bash appuser
WORKDIR /home/appuser/app
 
# Copy only installed packages from builder
COPY --from=builder /root/.local /home/appuser/.local
 
COPY --chown=appuser:appuser app/ ./app/
 
USER appuser
 
ENV PATH=/home/appuser/.local/bin:$PATH
 
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
    CMD python -c "import httpx; httpx.get('http://localhost:8000/health')" || exit 1
 
EXPOSE 8000
 
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

docker-compose.yml (Development)

version: "3.9"
 
services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql+asyncpg://postgres:password@db:5432/appdb
      - SECRET_KEY=dev-secret-key-change-in-production
      - DEBUG=true
    depends_on:
      db:
        condition: service_healthy
 
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
 
volumes:
  postgres_data:

docker compose up -d
curl http://localhost:8000/docs  # Swagger UI should appear

Step 7: GitHub Actions CI/CD Pipeline

# .github/workflows/ci.yml
name: CI/CD Pipeline
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: "pip"
 
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install pytest pytest-asyncio pytest-cov httpx aiosqlite
 
      - name: Lint (ruff)
        run: ruff check app/ tests/
 
      - name: Type check (mypy)
        run: mypy app/
 
      - name: Run tests
        run: pytest tests/ --cov=app --cov-report=xml --cov-fail-under=80
 
  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: flyctl deploy --remote-only
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

This pipeline runs linting, type checking, and tests on every PR. Coverage must stay above 80% or deployment is blocked. It deploys automatically to Fly.io on every merge to main.

Step 8: Multi-Agent Code Review Automation

Building on the patterns in the Claude Code Multi-Agent Parallel Execution, you can run a dedicated review agent in parallel with your main development session.

Create .claude/review_agent.md:

# FastAPI Code Review Agent
 
You are a FastAPI security and performance specialist reviewer.
 
## Review priorities (in order)
1. Security: SQL injection, auth bypass, privilege escalation risks
2. N+1 queries: Loop-based SELECT statements (suggest selectinload/joinedload)
3. Type safety: Gaps in Pydantic validation
4. Async safety: Blocking sync calls (e.g., requests library instead of httpx)
5. Error handling: Appropriate use of HTTPException
 
## Output format
For each issue:
- Location: filename:line_number
- Severity: CRITICAL / WARNING / INFO
- Issue: What's wrong
- Fix: Specific code example

Running this review agent as a subagent in a separate Claude Code session creates continuous parallel review — you develop in one session while the other watches for quality regressions.

Performance Optimization Patterns

Connection Pool Tuning

One of the most common production issues with FastAPI + SQLAlchemy async is connection pool exhaustion under load. Here's how to configure it correctly:

# app/core/database.py (production settings)
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
from app.core.config import get_settings
 
settings = get_settings()
 
engine = create_async_engine(
    settings.database_url,
    pool_size=20,           # Maintained connections
    max_overflow=10,         # Additional connections allowed above pool_size
    pool_pre_ping=True,      # Verify connection health before use
    pool_recycle=3600,       # Recycle connections older than 1 hour
    echo=settings.debug,     # Log SQL in debug mode only
)
 
async_session_factory = async_sessionmaker(
    engine,
    expire_on_commit=False,  # Prevent lazy loading after commit
    class_=AsyncSession,
)
 
async def get_db() -> AsyncSession:
    async with async_session_factory() as session:
        try:
            yield session
            await session.commit()
        except Exception:
            await session.rollback()
            raise

The expire_on_commit=False setting is particularly important in async contexts. Without it, accessing model attributes after a commit() triggers additional database queries, which can cause "MissingGreenlet" errors in async code.

Eager Loading to Prevent N+1 Queries

Ask Claude Code to audit your queries with this prompt: "Review all SQLAlchemy queries in the project and identify any that will cause N+1 problems when relationships are accessed. Add appropriate selectinload or joinedload options."

Example of what it will convert:

# BEFORE: N+1 problem — fetches each user's items in a separate query
users = await db.execute(select(User))
for user in users.scalars():
    print(user.items)  # Triggers a new SELECT per user!
 
# AFTER: Single query with eager loading
from sqlalchemy.orm import selectinload
 
stmt = select(User).options(selectinload(User.items))
result = await db.execute(stmt)
users = result.scalars().all()
# All items loaded in ONE additional query — no N+1

Response Caching with Redis — the Generated Version Never Hits

For read-heavy endpoints, Redis caching is the obvious next step, and this is the decorator that tends to come out of that prompt:

def cache(ttl_seconds: int = 300, key_prefix: str = ""):
    def decorator(func):
        @wraps(func)
        async def wrapper(*args, **kwargs):
            cache_key = f"{key_prefix}:{func.__name__}:{str(kwargs)}"  # problem one
            cached = await redis_client.get(cache_key)
            if cached:
                return json.loads(cached)
            result = await func(*args, **kwargs)
            await redis_client.setex(cache_key, ttl_seconds, json.dumps(result))  # problem two
            return result
        return wrapper
    return decorator

It reads correctly. Mounted on a real FastAPI app (Python 3.10.12, FastAPI 0.141.1) it fails twice over.

First, any endpoint with a response_model returns a 500:

TypeError: Object of type ItemRead is not JSON serializable

json.dumps cannot serialize a Pydantic model, so a textbook response_model=list[ItemRead] endpoint breaks on every request the moment caching is added.

Second, once you return plain dicts so serialization succeeds, the cache still never hits. Here are the keys generated by two requests to the same URL:

items:get_popular_items:{'db': <FakeSession object at 0x735ea09ee680>}
items:get_popular_items:{'db': <FakeSession object at 0x735ea086ceb0>}

kwargs carries the session injected by Depends(get_db), and the default repr of an object includes its memory address. Two requests produced two handler executions and two distinct cache entries — a 0% hit rate, with no error and no warning. The only visible symptom is Redis memory climbing.

The fix has two parts: name the arguments that belong in the key, and hand serialization to Pydantic.

# app/core/cache.py
import json
from functools import wraps
from pydantic import TypeAdapter
 
def cache(ttl_seconds: int = 300, key_prefix: str = "", model=None, cache_kwargs: tuple = ()):
    """Cache on the named kwargs only; serialize through Pydantic when a model is given."""
    adapter = TypeAdapter(model) if model is not None else None
 
    def decorator(func):
        @wraps(func)
        async def wrapper(*args, **kwargs):
            key_parts = [f"{k}={kwargs[k]!r}" for k in cache_kwargs if k in kwargs]
            cache_key = f"{key_prefix}:{func.__name__}:" + "&".join(key_parts)
 
            cached = await redis_client.get(cache_key)
            if cached is not None:
                return adapter.validate_json(cached) if adapter else json.loads(cached)
 
            result = await func(*args, **kwargs)
            payload = adapter.dump_json(result) if adapter else json.dumps(result)
            await redis_client.setex(cache_key, ttl_seconds, payload)
            return result
        return wrapper
    return decorator

Usage declares what the response actually depends on:

@router.get("/items/popular", response_model=list[ItemRead])
@cache(ttl_seconds=60, key_prefix="items", model=list[ItemRead], cache_kwargs=("limit",))
async def get_popular_items(limit: int = 10, db: AsyncSession = Depends(get_db)):
    ...

Measured again under the same conditions — six requests to /items/popular plus one to ?limit=5 — the handler ran twice, and exactly two keys existed: items:get_popular_items:limit=10 and items:get_popular_items:limit=5.

Naming cache_kwargs forces you to answer "what does this response actually vary on?" every time you add caching. That is the question people skip, and skipping it is how one user ends up served another user's data. If an endpoint's output depends on who is asking, the identifying argument must appear in cache_kwargs.

Pre-Deployment Production Checklist

Before deploying to Fly.io or Railway, verify these items:

Security

SECRET_KEY is a 256-bit random string (openssl rand -hex 32)
ALLOWED_ORIGINS contains only your production domain(s)
DEBUG=false in production
No known vulnerabilities in dependencies (pip audit)

Performance

Database connection pool size is appropriate for production load
Heavy operations are offloaded to BackgroundTasks or a task queue
No N+1 queries (verify with echo=True on the SQLAlchemy engine)

Observability

Structured logging is configured (structlog recommended)
/health endpoint checks database connectivity
Error tracking service (Sentry, Datadog, etc.) is configured

Deploy to Fly.io:

fly launch --name my-fastapi-app --region nrt
fly secrets set SECRET_KEY="$(openssl rand -hex 32)"
fly secrets set DATABASE_URL="postgresql+asyncpg://..."
fly deploy
fly status && fly logs

Summary

From CLAUDE.md design through deployment, the workflow above holds together because each piece feeds the next.

Key takeaways:

CLAUDE.md is the foundation: Explicit technology stack, coding standards, and constraints dramatically improve code generation quality
Iterative prompting wins: Step-by-step instructions produce better results than trying to generate everything at once
Co-generate tests: Requesting endpoint and pytest tests together eliminates the "I'll write tests later" trap
Hooks create feedback loops: Auto-running tests on every file save turns Claude Code into a self-correcting developer

Claude Code is not merely a code generator — it participates in design decisions, debugging, and test writing.

It is also worth being precise about what this article measured rather than assumed:

The generated Redis cache decorator returned 500 on any response_model endpoint, and even with plain dicts produced two cache keys for two identical requests — a 0% hit rate
A custom PermissionError class silently stopped except PermissionError from catching real filesystem permission errors
Removing the request argument from a @limiter.limit handler raised at import time, not at request time

None of the three were visible by reading the code. Generation got faster; the reading did not get easier. If anything, the time saved is best spent measuring.

Start with one thing: print the cache key in your own project and hit the same URL twice. If the two keys differ, you already know what to fix.

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.