🏗️ Project Overview do Backend
Para um backend Python com FastAPI, o overview deve focar na API e seus consumidores. Diferente de um frontend, o contexto aqui e sobre endpoints, integracao e processamento de dados.
💡 Exemplo Completo
# Project Overview
DataPipe is a REST API backend for a data analytics platform.
It handles user authentication, data ingestion from multiple
sources (CSV, APIs, databases), transformation pipelines,
and serves processed data to a React frontend and mobile app.
The API serves ~2k requests/minute and processes batch jobs
of up to 10GB via background workers (Celery). All endpoints
are versioned under /api/v1/.
⚡ Dica Pratica
Mencione os consumidores da API (frontend React, mobile app) para que o Claude entenda o contexto completo. Isso influencia decisoes como formato de resposta e versionamento de endpoints.
⚙️ Tech Stack com FastAPI e SQLAlchemy
A stack Python tem suas particularidades. E essencial especificar se voce usa SQLAlchemy 1.x ou 2.x, se usa Pydantic v1 ou v2, e qual gerenciador de pacotes (pip, poetry ou uv).
💡 Exemplo Completo
# Tech Stack
- Language: Python 3.12
- Framework: FastAPI 0.109+
- ORM: SQLAlchemy 2.0 (async, new-style mapped_column)
- Validation: Pydantic v2 (model_validator, not validator)
- Database: PostgreSQL 16 + Redis 7 (caching/sessions)
- Migrations: Alembic
- Task Queue: Celery with Redis broker
- Auth: python-jose for JWT + passlib for password hashing
- Package Manager: uv (NOT pip, NOT poetry)
- Linting: ruff (replaces flake8, isort, black)
- Testing: pytest + pytest-asyncio + httpx (async test client)
- Containerization: Docker + docker-compose for local dev
- Deploy: AWS ECS with ECR
⚡ Dica Pratica
O detalhe "SQLAlchemy 2.0 (async, new-style mapped_column)" e crucial. O Claude frequentemente gera codigo SQLAlchemy 1.x se nao for instruido. O mesmo vale para "Pydantic v2 (model_validator, not validator)" - as APIs mudaram significativamente entre v1 e v2.
🖥️ Comandos com uv
O uv e o gerenciador de pacotes Python moderno e ultra-rapido. Se voce usa uv, e essencial documentar os comandos porque o Claude por padrao sugere pip ou poetry.
💡 Exemplo Completo
# Commands
- `uv sync` - install/sync all dependencies from pyproject.toml
- `uv run uvicorn app.main:app --reload` - start dev server
- `uv run pytest` - run all tests
- `uv run pytest tests/path/to/test_file.py::test_name` - run single test
- `uv run pytest -x -v` - run tests, stop on first failure
- `uv run ruff check .` - lint check
- `uv run ruff format .` - auto-format code
- `uv run alembic upgrade head` - apply all migrations
- `uv run alembic revision --autogenerate -m "description"` - create migration
- `uv run alembic downgrade -1` - rollback last migration
- `docker-compose up -d` - start local PostgreSQL + Redis
- `uv add package-name` - add a new dependency
⚡ Dica Pratica
Note que todos os comandos usam uv run como prefixo. Sem essa documentacao, o Claude usaria python -m pytest ou pip install e quebraria o ambiente virtual.
📐 Convencoes do FastAPI
As convencoes de um backend FastAPI incluem estrutura de rotas, schemas Pydantic, modelos SQLAlchemy e padroes de tratamento de erros. Cada uma impacta diretamente a qualidade do codigo gerado.
💡 Exemplo Completo
# Code Conventions
## API Structure
- Routers in app/api/v1/endpoints/ (one file per resource)
- Schemas (Pydantic) in app/schemas/ (Create, Update, Response)
- Models (SQLAlchemy) in app/models/ (one class per file)
- Business logic in app/services/ (never in routers)
- Database queries in app/crud/ (repository pattern)
## Pydantic v2 Patterns
- Use model_validator instead of validator decorator
- Use model_config = ConfigDict(...) instead of class Config
- Schema names: UserCreate, UserUpdate, UserResponse
## SQLAlchemy 2.0 Patterns
- Use Mapped[type] and mapped_column() (new style)
- Async sessions via async_sessionmaker
- Relationships with lazy="selectin" for async compat
## General
- All functions with type hints (params + return)
- Docstrings in Google format for all public functions
- snake_case everywhere (PEP 8)
⚡ Dica Pratica
A regra "Business logic in app/services/ (never in routers)" e fundamental. Sem ela, o Claude tende a colocar toda a logica direto nas rotas, criando controllers gordos e dificeis de testar.
🚫 O que Evitar no FastAPI
O ecossistema Python tem armadilhas especificas que o Claude pode cair, especialmente na diferenca entre APIs sincronas e assincronas, e entre versoes antigas e novas de SQLAlchemy e Pydantic.
💡 Exemplo Completo
# Things To Avoid
- NEVER use SQLAlchemy 1.x patterns (Column(), declarative_base())
→ Use Mapped[], mapped_column(), DeclarativeBase
- NEVER use Pydantic v1 patterns (validator, class Config)
→ Use model_validator, ConfigDict
- DO NOT use sync database sessions (use async throughout)
- NEVER use pip install or poetry → always use uv
- DO NOT put business logic in route handlers
→ Create a service function in app/services/
- NEVER use print() for logging → use structlog
- DO NOT use datetime.utcnow() → use datetime.now(UTC)
- AVOID raw SQL queries → use SQLAlchemy ORM
- NEVER modify existing Alembic migrations
- DO NOT use wildcard imports (from module import *)
⚡ Dica Pratica
A regra "DO NOT use datetime.utcnow()" e um classico. Essa funcao esta deprecated no Python 3.12, mas o Claude ainda a sugere por habito. Incluir a alternativa correta (datetime.now(UTC)) e essencial.
⚖️ Comparando com Next.js
Comparar os dois exemplos (Next.js e FastAPI) revela padroes universais que se aplicam a qualquer CLAUDE.md, independente da linguagem ou framework.
💡 Conceito Principal
Apesar das diferencas tecnologicas, a estrutura do CLAUDE.md e sempre a mesma. As 6 secoes funcionam para qualquer stack.
| Aspecto | Next.js SaaS | FastAPI Backend |
|---|---|---|
| Pkg Manager | pnpm | uv |
| ORM | Prisma | SQLAlchemy 2.0 |
| Validation | TypeScript + Zod | Pydantic v2 |
| Testing | Vitest + Playwright | pytest + httpx |
| Linting | ESLint | ruff |
| Migrations | Prisma Migrate | Alembic |
- •A estrutura das 6 secoes funciona para qualquer linguagem
- •O nivel de detalhe deve ser o mesmo - especifico e sem ambiguidade
- •As secoes "Things To Avoid" sao as mais especificas por stack
⚡ Dica Pratica
Se voce trabalha com multiplas stacks, crie um CLAUDE.md template para cada uma. Assim, quando iniciar um novo projeto, so precisa personalizar o overview e os comandos. As convencoes e anti-patterns podem ser reutilizados.
📋 Resumo do Modulo
Proximo Modulo:
2.6 - O Comando /init