FastAPI — Claude Code rules

Tooling

• Python 3.12+. uv or pdm for env/lock. No system pip.
• Type hints everywhere — mypy --strict should pass.
• Pydantic v2 (NOT v1). model_dump(), not .dict().

Endpoints

• Async by default. Use async def for handlers unless the dependency is sync-only and short.
• Pydantic models for request bodies AND response bodies. Use response_model so OpenAPI is accurate.
• Path parameters via Annotated[str, Path(...)]. Query params via Annotated[T, Query(...)]. No bare default-value style.
• HTTP errors via HTTPException with explicit status_code and detail. No bare raise Exception(...).

Project shape

app/
├── main.py           # FastAPI() instance + routers
├── routers/
│   └── *.py
├── schemas/          # pydantic models
├── services/         # business logic, framework-agnostic
└── deps.py           # FastAPI Depends() providers

Don't

• Block the event loop with sync I/O inside an async handler. Use asyncio.to_thread() or move the call to a sync route.
• Mutate global state across requests. Inject dependencies.
• Skip response models — OpenAPI clients depend on them.