CLAUDE.md for a FastAPI project

When to use this

Use it on a FastAPI service. The conventions keep routes thin and push logic into a service layer, which is the split that keeps a FastAPI app testable as it grows. Fill in the project name and set your database and dependency tool.

# [Project] — agent guide

## Stack
FastAPI, Python 3.12, PostgreSQL, Pydantic v2. Dependencies with uv.

## Commands
- Install: `uv sync`
- Run: `uvicorn app.main:app --reload`
- Test: `pytest`
- Lint and format: `ruff check .` then `ruff format .`

## Conventions
- Validate every request and response with a Pydantic model.
- Keep routes thin. Put logic in service functions the routes call.
- Use async handlers for I/O-bound work. Keep blocking calls out of them.
- One router per resource, mounted in app.main.

## How to work here
- Run pytest and ruff before you call a task done.
- Keep each change scoped to one task.

## Do not
- Do not put database queries in route functions; use the service layer.
- Do not commit `.env` or real credentials.
- Do not add a dependency without saying why in the pull request.

Why each section is there

• Stack names FastAPI, the Python version and Pydantic v2 so the agent writes current code.
• Commands give the real uv, uvicorn, test and lint lines.
• Conventions carry the thin-route, service-layer and async rules.
• Do not keeps queries out of routes and secrets out of the repo.

Build one from a form with the CLAUDE.md generator. For how an agent uses the file, see working with agents.