Tutorial Claude Code: configuração, refatoração e debugging na prática

O que é o Claude Code?

O Claude Code é uma ferramenta que roda diretamente no seu terminal, entende sua base de código e ajuda nas tarefas de desenvolvimento com comandos em linguagem natural. Ele se integra ao seu ambiente de desenvolvimento com configuração mínima, para você focar em escrever e melhorar código.

Algumas capacidades importantes do Claude Code:

• Edição e refatoração: modifique, otimize e melhore seu código com sugestões de IA.
• Correção de bugs: identifique e resolva erros, dependências ausentes e gargalos de performance.
• Compreensão de código: faça perguntas sobre a arquitetura, lógica e dependências do seu código.
• Testes e linting automatizados: execute e corrija testes com falha, rode linters e eleve a qualidade do código.
• Integração com Git: pesquise o histórico, resolva conflitos, crie commits e gere pull requests com facilidade.

Seja em um projeto open source ou em bases de código corporativas, o Claude Code ajuda com automação inteligente que se adapta ao seu estilo e às necessidades do projeto. Atualizações recentes trouxeram o auto mode (menos interrupções de permissão), o plan mode (workflows com design primeiro) e Routines (agentes em nuvem agendados que rodam por gatilhos sem depender da sua máquina).

Alguns perfis ideais para este serviço:

• Desenvolvedores de software: melhoria de qualidade e manutenibilidade.
• Contribuidores open source: entender e aprimorar bases de código desconhecidas.
• Engenheiros DevOps: automação de code review e tarefas de linting.

O Claude Code agora usa por padrão o Claude Opus 4.7 nos planos Max e Team Premium. Usuários Pro iniciam com o Sonnet 4.6, mas podem alternar para modelos Opus em tarefas mais exigentes. É possível mudar de modelo no meio da sessão com o comando /model ou ajustar a profundidade de raciocínio com o controle /effort. Você também pode criar agentes de IA independentes usando o Claude Agents SDK.

A Anthropic também lançou o Cowork para ajuda no estilo de agentes com arquivos e documentos do dia a dia, além de código. Disponível para todos os assinantes pagos (Pro, Max, Team, Enterprise) no app Claude Desktop.

Se você está comparando o Claude Code com o agente de terminal da xAI, nosso Grok Build vs. Claude Code testa ambos na mesma tarefa.

Vamos começar com o projeto mão na massa.

Passo 1: configurando o Claude Code

Para começar com o Claude Code, você precisa de um terminal, um projeto de código para trabalhar e uma assinatura do Claude (Pro/Max/Teams/Enterprise) ou uma conta no Claude Console com cobrança ativa.

Instale o Claude Code executando um dos comandos abaixo no seu terminal, de acordo com seu sistema operacional e terminal.

macOS / Linux / WSL: 

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell: 

irm https://claude.ai/install.ps1 | iex

Windows CMD:  

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Observação: a instalação via npm install -g @anthropic-ai/claude-code ainda existe, mas está obsoleta. Prefira o instalador nativo acima. Se você instalou via npm anteriormente, migre com claude install.

Depois de instalar, navegue até o diretório do seu projeto e inicie o Claude executando:

cd your-project-directory
claude

Na autenticação, você escolhe entre usar o Claude Code com assinatura paga ou com cobrança por uso da API.

Em seguida, você receberá um link de login com um código de verificação para inserir no terminal onde o Claude Code está rodando. Pronto, a workspace dedicada “Claude Code” é criada automaticamente para acompanhar uso e custos.

Pronto: o Claude Code está pronto para uso.

Passo 2: preparando o ambiente de desenvolvimento

Para esta demo, vou usar a biblioteca Supabase para Python supabase-py, um cliente open source em Python para interagir com o Supabase, um backend como serviço construído sobre o PostgreSQL. O Supabase oferece um conjunto de ferramentas, incluindo autenticação, inscrições em tempo real, storage e APIs geradas automaticamente.

Vamos começar clonando o repositório e configurando o ambiente de desenvolvimento.

1. Abra o terminal, navegue até o diretório onde deseja clonar o repositório Supabase-py (ex.: cd Desktop) e rode o comando:

git clone https://github.com/supabase/supabase-py.git
cd  supabase-py

2. Depois, crie um ambiente virtual e instale as dependências necessárias executando estes comandos, um por vez:

python3 -m venv env
source env/bin/activate  # No Windows, use ./env/Scripts/activate
pip install -e .

Seu ambiente Python está pronto com todas as dependências para rodar a biblioteca do Supabase, e o repositório está pronto para exploração. 

Passo 3: identificando áreas para contribuir

Uma ótima forma de contribuir é explorar a aba Issues no GitHub. No repositório do Supabase, identifiquei um problema em client.py relacionado a legibilidade, estrutura e falta de comentários úteis.

O que vamos fazer com o Claude Code:

• Refatorar o código para melhorar legibilidade, manutenibilidade e estrutura.
• Adicionar docstrings e comentários inline para esclarecer o propósito dos componentes.
• Identificar e corrigir bugs analisando issues e outros erros potenciais.

Passo 4: experimentando com o Claude Code

Como já estamos na pasta supabase-py, navegue até o diretório supabase que contém o arquivo client.py e rode o Claude Code:

cd supabase
claude

O Claude Code agora tem acesso a todos os arquivos e pastas dentro de supabase-py. Vamos experimentar.

Refatorando código

Como parte da melhoria do SDK do Supabase em Python, vamos refatorar o arquivo client.py para aumentar a legibilidade, a manutenibilidade e a organização. Basta inserir o seguinte prompt no terminal:

Prompt: Refatore o código no arquivo client.py localizado na pasta Supabase.

O Claude vai pedir confirmação antes de prosseguir. Pressione Enter para aprovar. Ao concluir, o Claude Code atualiza o arquivo, mostra as modificações no terminal e gera um resumo do que foi feito.

Usando o Claude Code, aplicamos as seguintes melhorias em client.py:

• Imports organizados:  o Claude Code agrupou imports relacionados em seções lógicas (erros de auth, tipos de API, erros de functions), renomeou imports para clareza e removeu aliases redundantes para consistência.
• Mais legibilidade: foram adicionados comentários de seção para classificar imports e removida duplicação na lista __all__ para uma organização mais limpa.
• Opções do client simplificadas: também reduzimos múltiplas linhas combinando imports similares em uma única instrução.

Aqui está uma comparação lado a lado do código original e do refatorado.

Documentando código

Além de refatorar, o Claude Code pode gerar, atualizar e padronizar a documentação do código em todo o projeto. Ele identifica trechos sem documentação, gera docstrings e comentários estruturados e verifica conformidade com os padrões do projeto.

Usamos o Claude Code para melhorar a documentação em client.py, resultando em:

• Docstrings claros no nível do módulo explicando o propósito do arquivo.
• Comentários de seção detalhados categorizando imports (tipos de erro, implementações de client, serviços de storage).
• Comentários inline descrevendo tipos de erro, funções do client e componentes importantes.

Aqui está uma comparação lado a lado do código refatorado e documentado.

Prompt: Documente o código de client.py adicionando comentários para facilitar o entendimento.

Depois de adicionar a documentação, você pode verificar a conformidade com os padrões do projeto pedindo ao Claude:

Prompt: Verifique se a documentação segue nossos padrões de projeto.

Corrigindo bugs

Depurar pode consumir tempo, mas o Claude Code encurta o ciclo analisando mensagens de erro, identificando causas raiz e sugerindo correções. Seja por imports ausentes, erros de runtime ou problemas de lógica, ele reduz o escopo da busca e propõe correções direcionadas.

Veja como usar o Claude Code para debugging:

1. Identifique o problema:  compartilhe a mensagem de erro com o Claude.
2. Peça recomendações de correção: solicite possíveis soluções ao Claude.
3. Aplique e valide a correção:  implemente as sugestões e verifique se o problema foi resolvido.

O Claude Code fez os seguintes ajustes para resolver problemas de import no arquivo client.py: 

• Comentários type ignore: adicionou # type: ignore para suprimir alertas do IDE e do verificador de tipos em imports não resolvidos.
• Categorização consistente de erros: garantiu que os imports de erros de autenticação, banco, storage e functions estejam claramente agrupados.
• Leitura do código preservada: foram adicionados comentários explicando por que certos imports foram ignorados em vez de removidos.

Aqui está uma comparação lado a lado do código original e do corrigido.

Prompt: Estou vendo alguns bugs, como 'Import gotrue.errors' não pôde ser resolvido. Me ajude a corrigir todos os erros em client.py.

Comandos do Claude Code

Aqui vão alguns comandos para você testar com o Claude.

Para se aprofundar, confira nosso guia de comandos com barra do Claude Code.

Recursos avançados do Claude Code

Depois que você estiver confortável com o básico de refatoração e debugging, dá para ampliar as capacidades do Claude Code personalizando seu comportamento. Hooks e plugins permitem automatizar tarefas repetitivas e integrar sistemas externos.

Hooks do Claude Code

Hooks do Claude Code são gatilhos automatizados que executam comandos de shell quando eventos específicos ocorrem durante sua sessão. Eles automatizam tarefas repetitivas como formatação de código, execução de testes e checagens de segurança que o Claude poderia pular.

Hooks usam um sistema de evento-ação, no qual você define três coisas:

• O evento: quando o hook é disparado?

• O matcher: quais ações são afetadas?

• O comando: o que roda quando o hook dispara?

Por exemplo, um hook pode disparar após o Claude escrever um arquivo Python e rodar automaticamente o black para formatar o código. Hooks recebem contexto em JSON sobre o que aconteceu, permitindo decisões inteligentes com base em tipos ou caminhos de arquivos. Eles podem imprimir no transcript do Claude ou enviar mensagens de erro diretamente ao Claude para bloquear operações.

Casos de uso comuns para hooks incluem:

• Formatação de código: rodar linters e formatadores automaticamente após escritas

• Testes: executar suítes de teste após modificações para detectar bugs cedo

• Segurança: bloquear modificações em arquivos sensíveis, como configs de produção ou chaves de API

• Documentação: gerar documentação de API quando arquivos-fonte mudarem

• Automação com Git: criar commits inteligentes e validar políticas de proteção de branch

• Notificações: avisar seu time no Slack quando arquivos importantes mudarem

• Compliance: aplicar cabeçalhos de licença ou padrões de código antes de permitir mudanças

Configure hooks com o comando /hooks no Claude Code ou edite ~/.claude/settings.json diretamente.

Plugins do Claude Code

Plugins são extensões que conectam o Claude Code a ferramentas, serviços e APIs externos. Enquanto hooks automatizam comandos locais, plugins integram seu ecossistema de desenvolvimento mais amplo, como pipelines de CI/CD, ferramentas de gestão de projetos e plataformas de comunicação.

Plugins podem agrupar múltiplos componentes — subagentes (assistentes Claude especializados), servidores MCP (integrações padronizadas) e hooks — em um único pacote que orquestra tudo junto.

Um plugin pode analisar mudanças de código e abrir issues no Jira automaticamente, ou conectar à sua infraestrutura interna de testes. Plugins respondem aos mesmos eventos dos hooks, mas enviam dados a serviços externos e processam respostas para influenciar o fluxo do Claude.

Algumas tarefas em que plugins do Claude Code são ótimos:

• Integração com CI/CD: disparar builds, testes e deploys quando arquivos mudarem

• Gestão de projetos: criar/atualizar issues no Jira, GitHub ou Linear

• Comunicação do time: postar atualizações no Slack ou Teams quando houver mudanças

• Code review: abrir pull requests e gerenciar revisões no GitHub/GitLab

• Análises externas: chamar SonarQube, CodeClimate ou Snyk para varreduras corporativas

• Ferramentas customizadas: integrar sistemas e fluxos proprietários da empresa

• Extensões de IDE: adicionar comandos customizados e atalhos de navegação

Instale plugins de um registry ou desenvolva internamente para sua organização e configure os eventos aos quais eles respondem. Juntos, hooks e plugins criam uma plataforma extensível que adapta o Claude Code à sua infraestrutura.

Outros recursos avançados

O Claude Code ganhou outros recursos importantes em 2026 que ampliam como e onde você pode usá-lo:

• Plan mode: um workflow com design primeiro, no qual o Claude cria um plano detalhado antes de escrever código. Ideal para tarefas não triviais.
• Auto mode: um classificador de permissões que permite ao Claude trabalhar com menos interrupções, útil para tarefas longas em que você não quer aprovar cada escrita.
• Routines: agentes em nuvem agendados que disparam por cron, evento do GitHub (como PR aberto) ou webhook. Sua máquina não precisa estar ligada.
• Integração com IDE: extensões oficiais para VS Code, Cursor e IDEs JetBrains com diffs inline, checkpoints e suporte a múltiplas sessões.
• Controle remoto e Channels: rode sessões do Claude Code e interaja a partir do celular ou de outros dispositivos.

Considerações finais

Neste tutorial, usei o Claude Code para refatorar, documentar e depurar um arquivo no SDK do Supabase para Python. Melhoramos a legibilidade, adicionamos documentação estruturada e resolvemos problemas de import.

O Claude Code está evoluindo rapidamente com recursos como plan mode, auto mode e Routines — vale experimentar nos seus projetos para ver como ele se encaixa no seu fluxo.

Para dar o próximo passo, recomendo o tutorial Boas práticas do Claude Code, que ensina a aproveitar ao máximo a janela de contexto do Claude. Se você quiser construir um projeto do zero, confira nosso tutorial sobre Spec-Driven Development com Claude Code.