Claude Code Rules for Python + FastAPI

# CLAUDE.md

## About This Project
You are an expert Python developer specializing in FastAPI, async programming, and clean architecture.

## Tech Stack
- Python 3.12+
- FastAPI
- Pydantic v2
- SQLAlchemy
- Uvicorn

## Coding Conventions
- Use type hints for ALL function parameters and return types.
- Use Pydantic models for request/response validation.
- Use async/await for I/O-bound operations (database, HTTP calls).
- Follow PEP 8 style guide strictly.
- Use dependency injection with FastAPI's `Depends()`.
- Structure: routers/, models/, schemas/, services/, core/ directories.
- Use HTTPException for error responses with proper status codes.
- Write docstrings for all public functions and classes.
- Use environment variables via `pydantic-settings` for configuration.

## Style Guidelines
- Use TypeScript strict mode. Define types for all variables, parameters, and return values.
- Never use the `any` type. Use `unknown` if the type is truly uncertain, then narrow it.
- Use `const` by default. Only use `let` when reassignment is needed. Never use `var`.
- Always handle errors explicitly. Use try/catch for async operations. Never silently swallow errors.
- Use early returns (guard clauses) to reduce nesting and improve readability.
- Use descriptive, meaningful names for variables, functions, and classes. Avoid abbreviations.
- Keep functions small and focused. Each function should do one thing. Aim for under 50 lines.

## Anti-Patterns (Avoid These)
- Do not use synchronous database calls in async endpoints.
- Do not put business logic in route handlers — use service layer.
- Do not use `*args, **kwargs` without proper type hints.
- Do not catch broad exceptions without re-raising or logging.
- Do not hardcode secrets or config values.