CLAUDE.md for FastAPI

Blocking calls inside async routes freeze FastAPI's event loop — the single most common agent-introduced performance bug in this stack. Below is a complete, committable example for a typical FastAPI project. To get one tailored to your dependencies and scripts, paste your manifest into the free generator (client-side, nothing uploaded) or run npx getagentready in your repo.

Complete example

# CLAUDE.md

This file guides Claude Code when working in this repository.

## Project

**example-api** — Stack: Python, FastAPI, uv, pytest, Ruff.

## Commands

- Install dependencies: `uv sync`
- Run all tests: `uv run pytest`
- Run a single test: `uv run pytest tests/test_file.py::test_name`
- Lint: `uv run ruff check .`
- Format: `uv run ruff format .`
- Type-check: `uv run mypy .`

## Testing

Tests use pytest. Write or update tests alongside behavior changes; run the single-test command during iteration and the full suite before finishing.

## Conventions

- Define request/response shapes as Pydantic models; set `response_model` on routes.
- Use dependency injection (`Depends`) for auth, DB sessions, and shared resources.
- Async route handlers must not call blocking IO — use async libraries or `run_in_threadpool`.
- Prefer small, focused changes; do not refactor unrelated code in the same change.
- Match the existing code style of the file you are editing over any global preference.
- Never commit secrets. `.env*` files are local-only.
- After making changes, run the test and lint commands above before considering work done.

## Gotchas

- A sync call inside an `async def` route blocks the entire event loop — the most common FastAPI performance bug.
- Pydantic v2 syntax differs from v1 (`model_validate`, `model_dump`) — check which major version the project pins.

<!-- generated with https://getagentready.dev -->

Going further

This is the generated baseline. The Agent-Ready Pro Pack includes a hand-tuned, deeper FastAPI configuration — architecture guidance, testing strategy, common-task recipes — plus 12 workflow skills and enforcement hooks. See also the CLAUDE.md guide and AGENTS.md guide.