MÓDULO 5.3

🔨 Projetos Práticos

Exemplos reais: criando scripts, debugando código, gerando testes e documentando projetos com Claude Code — com prompts que funcionam.

6
Tópicos
35
Minutos
Inter.
Nível
Prático
Tipo
1

🐍 Criando um Script Python do Zero

Criar um script do zero é onde o CC mais brilha. O segredo está no prompt estruturado: descreva inputs, outputs, comportamentos esperados e peça os testes junto. Quanto mais específico, mais preciso o resultado.

Prompt ideal para criar script

Crie um script Python chamado csv_processor.py que:
1. Lê um arquivo CSV com colunas: nome, email, valor
2. Valida que todos os emails são válidos (regex RFC 5322 simplificado)
3. Converte a coluna valor de string para float
4. Soma todos os valores válidos
5. Gera um relatório em JSON com:
   - total de registros
   - registros válidos
   - registros inválidos (com motivo)
   - soma total dos valores
6. Salva o relatório em report.json

Inclua testes pytest para cada função pública.
Use type hints e docstrings Google Style.

Este prompt é completo: define inputs, outputs, validações, formato de saída e requisitos de qualidade.

Fluxo de iteração após o primeiro draft

1

Revise o código — leia o que foi gerado antes de pedir modificações

2

Ajuste específico — "altere a função validate_email para também rejeitar emails com + no local part"

3

Rode os testes — "rode pytest e corrija as falhas"

4

Refine — "adicione tratamento de erro para arquivo CSV não encontrado"

Dica de produtividade

Não reescreva o prompt do zero para ajustes. Use mensagens incrementais como "altere X para Y" ou "adicione Z à função W". O CC mantém o contexto e aplica apenas a mudança pedida.

2

🔧 Refatorando Código Existente

A abordagem certa para refatoração é sempre analisar antes de mudar. Pedir ao CC para refatorar diretamente sem análise prévia pode resultar em mudanças que quebram dependências não óbvias.

✓ Fluxo correto

> Analise database.py e identifique problemas de performance

→ CC analisa e lista: N+1 queries, falta de índices, conexões não fechadas

> Corrija o problema de N+1 na função get_users_with_orders

→ CC refatora apenas a função indicada, com explicação da mudança

✗ O que evitar

> Refatore database.py para ser mais eficiente

→ CC faz mudanças amplas sem prioridade clara, pode quebrar código dependente

> Melhore este arquivo inteiro de uma vez

→ Mudanças em lote sem análise = risco alto de regressões

💡 Prompts de análise úteis

"Analise utils.py e liste problemas de código (não corrija ainda)"
"Identifique funções duplicadas entre models.py e helpers.py"
"Verifique se há imports não usados neste arquivo"
"Quais funções em services.py violam o princípio de responsabilidade única?"
3

🐛 Debugando com Claude Code

CC é excelente para debugging porque reconhece padrões de erro de todas as linguagens. A chave é fornecer contexto máximo: erro completo, stack trace e código relevante. Quanto mais contexto, mais rápida a solução.

🐛 Template de prompt para debug

Estou recebendo este erro ao rodar app.py:

TypeError: 'NoneType' object is not subscriptable
  File "database.py", line 45, in get_user
    return result['id']

O código relevante é:

def get_user(user_id: int):
    conn = get_connection()
    result = conn.execute(
        "SELECT id, name FROM users WHERE id = ?", (user_id,)
    ).fetchone()
    return result['id']  # linha 45

Já tentei: verificar se user_id é válido (é 1, existe no banco).

Por favor, identifique e corrija o problema.

Por que este template funciona

Mensagem de erro completa — inclui o tipo do erro e a mensagem exata

Stack trace com arquivo e linha — CC sabe exatamente onde está o problema

Código do trecho problemático — contexto suficiente para entender a causa

O que já foi tentado — evita que CC sugira o que você já fez

💡 Para erros intermitentes

Se o erro não é reproduzível, inclua: "Este erro acontece 1 vez em 10 execuções, especialmente quando há alta concorrência". CC pode identificar race conditions e problemas de estado que não são óbvios em código linear.

4

🧪 Gerando Testes Automaticamente

CC é excepcional na geração de testes porque analisa o código e identifica edge cases que o desenvolvedor poderia ignorar. O resultado geralmente tem cobertura maior e mais abrangente do que o desenvolvedor escreveria manualmente.

Prompt básico (casos felizes)

Gere testes pytest para todas as
funções públicas de validators.py.
Cubra os casos de sucesso.

Prompt completo (alta cobertura)

Gere testes pytest para validators.py:
- Casos de sucesso (input válido)
- Casos de falha (input inválido)
- Edge cases (string vazia, None,
  caracteres especiais, overflow)
- Use fixtures para dados comuns.
Alvo: 100% de cobertura.

O que CC gera automaticamente

# Para uma função validate_email(email: str) -> bool
# CC gera automaticamente:

class TestValidateEmail:
    def test_valid_email(self):
        assert validate_email("user@example.com") is True

    def test_valid_email_with_subdomain(self):
        assert validate_email("user@mail.example.com") is True

    def test_invalid_missing_at(self):
        assert validate_email("userexample.com") is False

    def test_invalid_missing_domain(self):
        assert validate_email("user@") is False

    def test_empty_string(self):  # edge case
        assert validate_email("") is False

    def test_none_input(self):  # edge case
        with pytest.raises(TypeError):
            validate_email(None)

📊 Cobertura típica com CC vs manual

Desenvolvedor manual (média):

65-75%

de cobertura de código

Claude Code com prompt completo:

90-100%

de cobertura de código

5

📚 Documentando Código

CC pode documentar um projeto inteiro em minutos. Desde docstrings em todas as funções até um README completo — basta especificar o formato e o nível de detalhe desejado.

Docstrings em Google Style

> Adicione docstrings no formato Google Style a todas as funções
  públicas de utils.py que ainda não têm documentação

README completo do projeto

> Crie um README.md para este projeto com seções:
  Descrição, Instalação, Uso com exemplos, Configuração,
  Estrutura do projeto, Como contribuir, Licença

Comentários em código complexo

> Adicione comentários explicando a lógica em process_data(),
  especialmente os algoritmos de filtragem e agregação

💡 Dica: especifique o formato no CLAUDE.md

Se seu projeto usa um padrão específico (Google, NumPy, reStructuredText), coloque no CLAUDE.md: "Docstrings sempre no formato Google Style". Assim o CC sempre usa o formato correto sem precisar especificar em cada pedido.

6

🗂️ Trabalhando com Múltiplos Arquivos

Refatorações que cruzam arquivos são as mais propensas a erros humanos. CC pode rastrear todas as referências e fazer as mudanças de forma consistente — renomeando funções em 10 arquivos sem perder nenhuma.

🗂️ Exemplos de tarefas multi-arquivo

> Renomeie a função get_user para fetch_user em todos os arquivos que a usam

CC encontra todas as chamadas, verifica imports e faz as substituições consistentemente

> Mova a classe UserValidator de utils.py para validators.py e atualize os imports

CC move o código, cria o import no arquivo destino e atualiza todos os arquivos que importavam de utils.py

> Adicione o parâmetro timeout=30 a todas as chamadas da função make_request no projeto

CC busca todas as ocorrências e adiciona o parâmetro em cada chamada

💡 Use /add-dir para projetos grandes

Por padrão, CC tem acesso ao diretório atual. Para trabalhar com pasta externa:

/add-dir ../outro-projeto/src

Após adicionar, CC pode ler e modificar arquivos naquele diretório também.

⚠️ Sempre peça lista antes de executar

Para mudanças em múltiplos arquivos, peça ao CC para listar o que vai ser alterado antes de executar: "Liste os arquivos que seriam afetados antes de fazer as mudanças". Isso evita surpresas em projetos grandes.

Resumo do Módulo 5.3

Scripts do zero — prompt estruturado com inputs, outputs e testes em um único pedido
Refatoração segura — analisar primeiro, depois executar mudanças específicas
Debug eficaz — erro completo + stack trace + código + o que já tentou
Testes de alta cobertura — pedir casos felizes, de falha e edge cases separadamente
Multi-arquivo — pedir lista de arquivos afetados antes de executar mudanças globais

Próximo Módulo:

5.4 — 🧠 Gerenciando o Contexto: tokens, /compact e autoCompact para sessões longas