CLAUDE.md Template for SOTA FastAPI Backend Development

What is this CLAUDE.md template for?

This CLAUDE.md template configures your AI assistant to act as an elite backend architect specialized in Python and FastAPI. It ensures the assistant avoids outdated synchronous patterns, non-standard project layours, and weak validation routines, steering it instead toward state-of-the-art (SOTA), high-throughput production paradigms.

By enforcing asynchronous standards, Pydantic v2 conventions, strict dependency injection, and proper exception mapping, it minimizes manual refactoring and eliminates typical AI-generated architectural technical debt.

When to use this template

Use this template when setting up a new Python backend project, scaling a SaaS API layer, implementing async background task systems, configuring database connection pooling, or instructing your AI agent to refactor legacy sync code into high-performance async workflows.

Recommended project structure

project-root/
  app/
    api/
      v1/
        endpoints/
        router.py
    core/
      config.py
      database.py
      security.py
      exceptions.py
    models/
    schemas/
    services/
    main.py
  tests/
  .env.example
  CLAUDE.md
  requirements.txt

CLAUDE.md Template

# CLAUDE.md: FastAPI Backend Engineering Guide

You are working as a Principal Backend Architect building a state-of-the-art (SOTA), production-ready FastAPI application.

Your mandate is to write clean, maintainable, fully async, type-safe, and highly performant Python code.

## Core Execution Principles

- **Strict Asynchrony**: Always write async route handlers and leverage async database drivers (e.g., asyncpg with SQLAlchemy). Avoid blocking I/O inside async functions.
- **Absolute Type Safety**: Utilize explicit PEP 484 type hints everywhere. Enforce type correctness using static analysis patterns.
- **Pydantic v2 Paradigms**: Write modern Pydantic v2 schemas using proper field definitions, field_validators, and model_validators.
- **Explicit Dependency Injection**: Use FastAPI's `Depends()` explicitly for database sessions, authentication, and service initializations.

## Project Directory Layout

Maintain strict separation of concerns using the following blueprint:
- `app/main.py`: Application instantiation, middleware configuration, and root router orchestration.
- `app/api/`: Versioned routing (`v1/endpoints/`) handling HTTP semantics exclusively.
- `app/core/`: Application state configuration (`config.py`), database engines (`database.py`), and global security/exception definitions.
- `app/models/`: Declarative ORM entities (e.g., SQLAlchemy / SQLModel).
- `app/schemas/`: Pydantic validation contracts defining explicit ingress and egress shapes.
- `app/services/`: Pure business logic completely uncoupled from transport/HTTP paradigms.

## Technical Implementation Rules

### 1. Route Handlers & Controller Layer
- Keep route handlers highly descriptive, lightweight, and thin. Delegating core compute or mutations to the Service layer.
- Always specify exact `response_model` classes and correct HTTP status codes in decorators.
- Never leak raw ORM entities directly into responses; return validated Pydantic schemas.

### 2. Database Operations (SQLAlchemy/SQLModel)
- Always utilize `AsyncSession` for session handling, yield-managing contexts with dependency injection.
- Write queries utilizing advanced async constructs (`scalars().all()`, `execute()`). Avoid relying on implicit lazy loading.
- Enforce precise transactional context boundaries using `async with async_session.begin():` blocks for compound mutations.

### 3. Error Handling & Exceptional Control Flow
- Define domain-specific custom exceptions inheriting from a base application error class.
- Implement global application exception handlers using `@app.exception_handler()` to transform exceptions into clean, structured JSON responses.
- Never bubble raw internal stack traces or internal DB errors back to the API client.

### 4. Security, Auth, & Middleware
- Authenticate requests using secure JWT bearer tokens processed via dependencies.
- Safely manage sensitive environment context via Pydantic-Settings (`BaseSettings`).
- Explicitly configure standard CORS policies and rate-limiting rules directly within initialization hooks.

## Code Style & Formatting
- Adhere to explicit PEP 8 formatting rules, favoring modern practices (such as using `list[]` and `dict[]` over typing module equivalents).
- Implement useful docstrings documenting architectural parameters, complex business scenarios, and expected anomalies.
- Organize logical segments systematically with meaningful comments explaining edge conditions rather than standard syntax actions.

Why this template matters

FastAPI applications can easily degrade into blocking codebases or messy monolithic layouts if not structured deliberately from the beginning. Generic AI tools regularly mix sync/async paradigms or generate outdated Pydantic v1 code patterns.

This template explicitly locks your workflow into SOTA FastAPI best practices, ensuring optimal performance, clear separation of layers, and robust enterprise readiness out of the box.

Recommended additions

• Integrate a pre-configured Alembic async migration workflow instruction.
• Add targeted test configuration blocks using `httpx.AsyncClient` and pytest-asyncio.
• Include production deployment definitions utilizing Uvicorn/Gunicorn multi-worker orchestration structures.
• Define specific multi-tenant isolation patterns for enterprise SaaS backends.

FAQ

Can this template be used with SQLModel?

Yes. Because SQLModel integrates Pydantic and SQLAlchemy directly, this template's emphasis on clean schema boundaries and async database operations fits perfectly.

How does this template handle blocking synchronous libraries?

It instructs the assistant to isolate blocking code paths using FastAPI's standard threadpool executor patterns (`run_in_threadpool`) to prevent event loop starvation.

Is this template optimized for Pydantic v2?

Yes. It explicitly enforces Pydantic v2 mechanics, ensuring fast execution, updated validator definitions, and up-to-date validation logic.

Does this cover Docker and Kubernetes readiness?

It lays down the required software layer architecture (such as clean health checks and decoupled configs) to make containerization seamless.

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.