Claude Code + Python: Guia Completo para Devs Backend

Python e a linguagem mais popular do mundo por um motivo: serve para tudo. APIs, data science, automacao, machine learning, scripts de infraestrutura. Mas todo dev Python sabe que escrever boilerplate de API, configurar ORMs, criar testes e debugar codigo consome horas que poderiam ser usadas em logica de negocio.

O Claude Code muda isso. Ele nao gera snippets genericos copiados do Stack Overflow. Ele le o seu projeto inteiro -- entende se voce usa FastAPI com SQLAlchemy, Django com DRF, ou Flask com Marshmallow -- e gera codigo que segue exatamente os padroes da sua codebase. Ele entende suas models, seus schemas, suas convencoes de nomenclatura.

Neste guia, voce vai ver exemplos reais de como usar Claude Code para cada area do desenvolvimento Python backend: APIs REST, ORMs, data science, automacao, testes e refatoracao. Tudo com comandos que voce pode executar hoje no seu terminal.

1. Por que Claude Code e o melhor parceiro para Python

Python e uma linguagem expressiva, mas projetos backend crescem rapido. Uma API com 20 endpoints, cada um com validacao, autenticacao, tratamento de erros e testes, facilmente chega a milhares de linhas. O Claude Code acelera esse trabalho porque opera diretamente na sua codebase.

Diferente de chatbots que geram codigo isolado, o Claude Code:

• Le toda a estrutura do projeto -- entende onde ficam models, routers, schemas, utils, migrations
• Entende dependencias -- sabe se voce usa SQLAlchemy, Tortoise, Peewee, ou Django ORM
• Respeita convencoes -- se voce usa snake_case, type hints, docstrings Google style, ele segue
• Executa e valida -- roda pytest, verifica erros de importacao, testa endpoints
• Cria arquivos nos lugares certos -- sabe que models vao em app/models/, testes em tests/

O resultado: voce descreve o que precisa em linguagem natural e o Claude Code implementa, testa e valida. Sem copiar e colar, sem adaptar snippets, sem debugar codigo generico.

2. Criando APIs com FastAPI

FastAPI e o framework Python mais rapido para criar APIs REST. O Claude Code domina FastAPI porque entende o ecossistema completo: Pydantic para validacao, SQLAlchemy para ORM, Alembic para migrations, e a documentacao OpenAPI automatica.

Criando um CRUD completo

O Claude Code gera todos os arquivos necessarios:

# app/models/product.py
from sqlalchemy import Column, Integer, String, Numeric, Boolean
from sqlalchemy.orm import Mapped, mapped_column
from app.database import Base

class Product(Base):
    __tablename__ = "products"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(255), nullable=False)
    price: Mapped[float] = mapped_column(Numeric(10, 2), nullable=False)
    category: Mapped[str] = mapped_column(String(100), nullable=False)
    active: Mapped[bool] = mapped_column(Boolean, default=True)

# app/schemas/product.py
from pydantic import BaseModel, Field
from decimal import Decimal

class ProductBase(BaseModel):
    name: str = Field(..., min_length=1, max_length=255)
    price: Decimal = Field(..., gt=0, decimal_places=2)
    category: str = Field(..., min_length=1, max_length=100)
    active: bool = True

class ProductCreate(ProductBase):
    pass

class ProductUpdate(ProductBase):
    name: str | None = None
    price: Decimal | None = None
    category: str | None = None
    active: bool | None = None

class ProductResponse(ProductBase):
    id: int

    model_config = {"from_attributes": True}

# app/routers/products.py
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy.ext.asyncio import AsyncSession
from app.database import get_db
from app.models.product import Product
from app.schemas.product import ProductCreate, ProductUpdate, ProductResponse
from sqlalchemy import select, func

router = APIRouter(prefix="/products", tags=["products"])

@router.get("/", response_model=list[ProductResponse])
async def list_products(
    skip: int = Query(0, ge=0),
    limit: int = Query(20, ge=1, le=100),
    category: str | None = None,
    db: AsyncSession = Depends(get_db),
):
    query = select(Product).where(Product.active == True)
    if category:
        query = query.where(Product.category == category)
    query = query.offset(skip).limit(limit)
    result = await db.execute(query)
    return result.scalars().all()

@router.post("/", response_model=ProductResponse, status_code=201)
async def create_product(
    data: ProductCreate,
    db: AsyncSession = Depends(get_db),
):
    product = Product(**data.model_dump())
    db.add(product)
    await db.commit()
    await db.refresh(product)
    return product

@router.get("/{product_id}", response_model=ProductResponse)
async def get_product(product_id: int, db: AsyncSession = Depends(get_db)):
    product = await db.get(Product, product_id)
    if not product:
        raise HTTPException(status_code=404, detail="Product not found")
    return product

@router.patch("/{product_id}", response_model=ProductResponse)
async def update_product(
    product_id: int,
    data: ProductUpdate,
    db: AsyncSession = Depends(get_db),
):
    product = await db.get(Product, product_id)
    if not product:
        raise HTTPException(status_code=404, detail="Product not found")
    for key, value in data.model_dump(exclude_unset=True).items():
        setattr(product, key, value)
    await db.commit()
    await db.refresh(product)
    return product

Note como o Claude Code usou async/await porque detectou que o projeto usa SQLAlchemy async. Usou Mapped e mapped_column porque o projeto esta no SQLAlchemy 2.0+. E adicionou paginacao com Query validando limites. Tudo seguindo o padrao existente.

Autenticacao JWT

O Claude Code implementa o fluxo completo: hashing com passlib/bcrypt, tokens JWT com python-jose, dependency get_current_user para injetar nos endpoints protegidos, e testes que cobrem registro, login, token invalido e token expirado.

3. Django: models, views e migrations

Django e o framework mais completo para aplicacoes web Python. O Claude Code entende o ecossistema Django inteiro: models com ORM, views baseadas em classe e funcao, Django REST Framework, admin, signals, middleware e migrations.

Criando uma app Django completa

# orders/models.py
from django.db import models
from django.conf import settings

class Order(models.Model):
    class Status(models.TextChoices):
        PENDING = "pending", "Pendente"
        CONFIRMED = "confirmed", "Confirmado"
        SHIPPED = "shipped", "Enviado"
        DELIVERED = "delivered", "Entregue"
        CANCELLED = "cancelled", "Cancelado"

    user = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="orders",
    )
    status = models.CharField(
        max_length=20,
        choices=Status.choices,
        default=Status.PENDING,
    )
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    @property
    def total(self):
        return sum(item.subtotal for item in self.items.all())

    class Meta:
        ordering = ["-created_at"]

class OrderItem(models.Model):
    order = models.ForeignKey(Order, on_delete=models.CASCADE, related_name="items")
    product = models.ForeignKey("products.Product", on_delete=models.PROTECT)
    quantity = models.PositiveIntegerField(default=1)
    unit_price = models.DecimalField(max_digits=10, decimal_places=2)

    @property
    def subtotal(self):
        return self.quantity * self.unit_price

O Claude Code tambem gera a migration, registra no admin com inlines, cria serializers aninhados no DRF e adiciona permissions para que cada usuario so veja seus proprios pedidos.

Django signals e middleware

Precisa de logica automatica quando um pedido muda de status? O Claude Code cria signals Django que disparam notificacoes, atualizam estoque ou registram logs de auditoria. Ele entende o ciclo de vida completo dos models Django.

4. Flask: microservicos e APIs leves

Flask e ideal para microservicos e APIs leves. O Claude Code gera aplicacoes Flask organizadas com blueprints, extensoes e padroes de projetos profissionais.

# app/__init__.py
from flask import Flask
from app.extensions import db, ma, migrate
from app.webhooks import webhooks_bp
from app.transactions import transactions_bp

def create_app(config_name="default"):
    app = Flask(__name__)
    app.config.from_object(f"app.config.{config_name}")

    db.init_app(app)
    ma.init_app(app)
    migrate.init_app(app, db)

    app.register_blueprint(webhooks_bp, url_prefix="/webhooks")
    app.register_blueprint(transactions_bp, url_prefix="/api/transactions")

    @app.route("/health")
    def health():
        return {"status": "ok", "service": "payments"}, 200

    return app

O Claude Code cria a estrutura completa com factory pattern, configuracoes por ambiente (dev, staging, prod), blueprints separados e extensoes inicializadas corretamente. O mesmo padrao que voce veria em projetos Flask profissionais.

5. Data science e analise de dados

Python domina data science, e o Claude Code acelera drasticamente o trabalho com dados. Ele gera scripts de analise com pandas, visualizacoes com matplotlib/seaborn, e pipelines de processamento completos.

Analise exploratoria automatizada

import pandas as pd
import matplotlib.pyplot as plt
from pathlib import Path

df = pd.read_csv("vendas_2025.csv", parse_dates=["data"])

# Limpeza
df = df.dropna(subset=["valor", "produto"])
df = df[df["valor"] > 0]
df["mes"] = df["data"].dt.to_period("M")

# Tendencia mensal
mensal = df.groupby("mes").agg(
    receita=("valor", "sum"),
    pedidos=("id", "count"),
    ticket_medio=("valor", "mean"),
).reset_index()

# Top 10 produtos
top_produtos = (
    df.groupby("produto")["valor"]
    .sum()
    .sort_values(ascending=False)
    .head(10)
)

# Visualizacao
fig, axes = plt.subplots(2, 2, figsize=(14, 10))
mensal.plot(x="mes", y="receita", ax=axes[0, 0], title="Receita Mensal")
mensal.plot(x="mes", y="pedidos", ax=axes[0, 1], title="Pedidos por Mes")
top_produtos.plot(kind="barh", ax=axes[1, 0], title="Top 10 Produtos")
mensal.plot(x="mes", y="ticket_medio", ax=axes[1, 1], title="Ticket Medio")
plt.tight_layout()
plt.savefig("relatorio_vendas.png", dpi=150)

O Claude Code nao apenas gera o codigo -- ele executa, verifica se os graficos foram gerados corretamente e reporta os insights encontrados nos dados. Se encontrar problemas na qualidade dos dados (valores nulos, duplicatas, outliers), ele alerta e sugere tratamento.

Machine learning pipelines

Para projetos de ML, o Claude Code cria pipelines completos com scikit-learn: pre-processamento, feature engineering, treinamento, validacao cruzada e metricas. Ele entende a diferenca entre problemas de classificacao e regressao e escolhe as metricas corretas automaticamente.

6. Scripts e automacao

Python e a linguagem favorita para automacao, e o Claude Code cria scripts robustos que voce pode confiar para rodar em producao.

Automacao de tarefas repetitivas

# scripts/csv_monitor.py
import logging
import smtplib
from email.mime.text import MIMEText
from pathlib import Path
from watchdog.observers import Observer
from watchdog.events import FileCreatedEvent, FileSystemEventHandler
import pandas as pd

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s",
    handlers=[
        logging.FileHandler("monitor.log"),
        logging.StreamHandler(),
    ],
)
logger = logging.getLogger(__name__)

class CSVHandler(FileSystemEventHandler):
    def on_created(self, event):
        if not isinstance(event, FileCreatedEvent):
            return
        if not event.src_path.endswith(".csv"):
            return

        logger.info(f"Novo arquivo detectado: {event.src_path}")
        try:
            df = pd.read_csv(event.src_path)
            resumo = self._processar(df, event.src_path)
            self._enviar_email(resumo)
            logger.info(f"Processado com sucesso: {event.src_path}")
        except Exception as e:
            logger.error(f"Erro ao processar {event.src_path}: {e}")

    def _processar(self, df: pd.DataFrame, path: str) -> str:
        linhas_originais = len(df)
        df = df.dropna()
        linhas_limpas = len(df)

        return (
            f"Arquivo: {Path(path).name}\n"
            f"Linhas: {linhas_originais} (removidas: {linhas_originais - linhas_limpas})\n"
            f"Colunas: {', '.join(df.columns)}\n"
            f"Resumo:\n{df.describe().to_string()}"
        )

    def _enviar_email(self, corpo: str):
        msg = MIMEText(corpo)
        msg["Subject"] = "Novo CSV processado"
        msg["From"] = "monitor@empresa.com"
        msg["To"] = "equipe@empresa.com"
        with smtplib.SMTP("smtp.empresa.com", 587) as server:
            server.starttls()
            server.login("monitor@empresa.com", "senha")
            server.send_message(msg)

O Claude Code cria scripts com tratamento de erros robusto, logging profissional e estrutura que funciona em producao. Nao e codigo de tutorial -- e codigo de producao.

Web scraping etico

Para coleta de dados, o Claude Code gera scrapers com requests/httpx e BeautifulSoup ou Playwright, respeitando robots.txt, implementando rate limiting e salvando dados de forma estruturada. Ele tambem cria fallbacks para quando a estrutura do site muda.

7. Testes com pytest

Testes sao a area onde o Claude Code mais economiza tempo. Ele gera testes pytest completos, com fixtures, mocks, parametrize e cobertura de edge cases -- tudo seguindo as convencoes do seu projeto.

Testes para API FastAPI

# tests/test_products.py
import pytest
from httpx import AsyncClient, ASGITransport
from app.main import app
from app.database import get_db

@pytest.fixture
async def client(db_session):
    async def override_get_db():
        yield db_session

    app.dependency_overrides[get_db] = override_get_db
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as ac:
        yield ac
    app.dependency_overrides.clear()

@pytest.mark.asyncio
async def test_create_product(client):
    response = await client.post("/products/", json={
        "name": "Widget",
        "price": "29.99",
        "category": "electronics",
    })
    assert response.status_code == 201
    data = response.json()
    assert data["name"] == "Widget"
    assert data["id"] is not None

@pytest.mark.asyncio
async def test_create_product_invalid_price(client):
    response = await client.post("/products/", json={
        "name": "Widget",
        "price": "-5.00",
        "category": "electronics",
    })
    assert response.status_code == 422

@pytest.mark.asyncio
async def test_list_products_pagination(client, sample_products):
    response = await client.get("/products/?limit=5&skip=0")
    assert response.status_code == 200
    data = response.json()
    assert len(data) <= 5

@pytest.mark.asyncio
async def test_get_product_not_found(client):
    response = await client.get("/products/99999")
    assert response.status_code == 404

O Claude Code gera testes que cobrem o caminho feliz (happy path), validacao de entrada, erros esperados e paginacao. Ele tambem cria as fixtures necessarias no conftest.py: sessao de banco de dados de teste, dados de exemplo e cleanup automatico.

Cobertura em massa

O Claude Code analisa o relatorio de cobertura, identifica exatamente quais linhas e branches nao estao cobertas e gera testes especificos para elas. Aumentar cobertura de 60% para 90% pode levar dias manualmente -- com Claude Code, leva minutos.

8. Refatoracao e qualidade de codigo

Codigo Python legado com funcoes de 200 linhas, sem type hints e sem testes e realidade em muitos projetos. O Claude Code refatora codigo mantendo o comportamento identico.

O Claude Code tambem detecta e corrige:

• Code smells -- funcoes muito longas, classes com muitas responsabilidades, imports nao usados
• Problemas de seguranca -- SQL injection, secrets hardcoded, deserializacao insegura
• Performance -- queries N+1, loops ineficientes, uso excessivo de memoria
• Padroes modernos -- migrar de os.path para pathlib, format() para f-strings, dicts para dataclasses

Adicionar type hints em massa

O Claude Code analisa cada funcao, infere os tipos corretos baseado no uso e adiciona type hints precisos. Ele roda mypy --strict para verificar que nenhum erro de tipo foi introduzido.

9. Workflows completos de backend

O verdadeiro poder do Claude Code aparece quando voce combina multiplas tarefas em workflows completos. Esses sao os workflows mais comuns para devs Python backend:

Workflow 1: feature completa end-to-end

O Claude Code cria o model, migration, schemas, endpoints, integra com o checkout existente, adiciona validacoes de negocio (cupom expirado, uso maximo atingido, valor minimo do pedido) e gera testes para todos os cenarios. Uma feature que levaria um dia, entregue em minutos.

Workflow 2: debug e investigacao

Workflow 3: migracao de framework

O Claude Code faz a migracao arquivo por arquivo, validando com testes a cada etapa. Ele entende as diferencas entre frameworks e traduz padroes automaticamente: decorators de rota, middleware, injecao de dependencias e tratamento de erros.