CLAUDE.md for a Python Backend Team

# CLAUDE.md — {{service_name}} ## What this service does {{one_paragraph_description}} ## Commands (use these, don't guess) - Install deps: `uv sync` - Run locally: `uv run fastapi dev src/{{package}}/main.py` - Tests: `uv run pytest` (fast unit) / `uv run pytest -m integration` (needs Docker) - Lint + format: `uv run ruff check --fix . && uv run ruff format .` - Types: `uv run mypy src/` All four of tests/lint/format/types must pass before any task is complete. ## Architecture - `src/{{package}}/api/` — FastAPI routers, thin: parse request, call service, shape response. No business logic. - `src/{{package}}/services/` — business logic, pure where possible, no FastAPI imports. - `src/{{package}}/repositories/` — all DB access (SQLAlchemy 2.0 style, async). Nothing else touches the session. - `src/{{package}}/models/` — Pydantic schemas (API) and ORM models kept separate. Never return ORM objects from endpoints. ## Conventions - Python 3.12+. Full type hints everywhere; `mypy --strict` is CI-enforced. - Errors: raise domain exceptions from `exceptions.py`; the global handler maps them to HTTP. Never `except Exception: pass`. Never return None to signal failure. - Logging: structlog, key-value style — `logger.info("order_created", order_id=order.id)`. No f-string log messages, no print(). - Config via `Settings` (pydantic-settings) only. Any new env var gets a default for local dev and a line in `.env.example`. - DB changes require an Alembic migration in the same PR. Autogenerate, then review the diff by hand. ## Testing rules - New endpoints: integration test through the HTTP layer (httpx AsyncClient) against a real Postgres via testcontainers. - Pure logic: plain unit tests, no mocks of our own code — mock only external services. - Factories in `tests/factories.py`; don't hand-build ORM objects in tests. ## Do not - Add dependencies without asking. Touch `alembic/versions/*` of merged migrations. Widen any endpoint's response model. Commit secrets (pre-commit will catch, but still).