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

O que é o Claude Code?

O Claude Code é uma ferramenta que roda direto no seu terminal, entende sua base de código e ajuda em 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-chave do Claude Code:

• Edição e refatoração: modifique, otimize e aprimore sua base de 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 melhore a qualidade do código.
• Integração com Git: pesquise no histórico, resolva conflitos de merge, crie commits e gere pull requests sem esforço.

Seja em um projeto open source ou gerenciando bases corporativas, o Claude Code ajuda com automação inteligente que se adapta ao seu estilo e às demandas do projeto. Atualizações recentes adicionaram o auto mode (menos interrupções de permissão), o plan mode (fluxos design-first) e Routines (agentes em nuvem agendados que rodam por gatilhos sem sua máquina ligada).

Usuários ideais para este serviço:

• Desenvolvedores de software: melhoria de qualidade e manutenibilidade do código.
• Contribuidores open source: entender e aprimorar bases de código desconhecidas.
• Engenheiros DevOps: automatizar revisão de código 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 começam com o Sonnet 4.6, mas podem alternar para modelos Opus para tarefas mais exigentes. Você pode trocar de modelo no meio da sessão com o comando /model ou ajustar a profundidade de raciocínio com o controle /effort. Também é possível criar agentes de IA independentes usando o Claude Agents SDK.

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

Vamos começar nosso 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, conforme o sistema operacional e o 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 processo nativo acima. Se você instalou via npm anteriormente, pode migrar com claude install.

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

cd your-project-directory
claude

Para autenticação, você deverá escolher entre usar o Claude Code com assinatura paga ou com cobrança por uso de 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 — um workspace dedicado “Claude Code” é criado automaticamente para rastrear uso e gerenciar custos.

Agora 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 Python open source 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, assinaturas em tempo real, storage e APIs geradas automaticamente.

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

1. Abra o terminal, vá até o diretório onde quer clonar o repositório Supabase-py (ex.: cd Desktop) e execute:

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 os comandos abaixo, um por vez:

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

Seu ambiente Python agora 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 é explorando 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 significativos.

Veja 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 testar.

Refatorando código

Como parte da melhoria do SDK do Supabase em Python, vamos refatorar o arquivo client.py para aprimorar legibilidade, manutenibilidade e organização. Basta inserir o seguinte prompt na linha de comando:

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

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

Com o Claude Code, aplicamos as seguintes melhorias ao 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 por consistência.
• Mais legibilidade: foram adicionados comentários de seção para classificar imports e removida duplicação na lista __all__ para organização mais limpa.
• Opções do client simplificadas: também reduziu várias linhas combinando imports similares em uma única instrução.

Veja 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 documentação de 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 de documentação 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 de client e componentes importantes.

Veja a comparação lado a lado do código refatorado e documentado.

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

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

Prompt: Verifique se a documentação segue os padrões do nosso 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 um import ausente, erro de runtime ou problema de lógica, ele reduz o escopo da busca e propõe correções pontuais.

Como usar o Claude Code para depuração:

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.
3. Aplique e verifique a correção:  implemente as sugestões do Claude e confira 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 o comentário # type: ignore para suprimir avisos do IDE e do verificador de tipos para imports não resolvidos.
• Categorização consistente de erros: garantiu que imports de erros de autenticação, banco de dados, storage e functions ficassem claramente agrupados.
• Leitura do código preservada: foram adicionados comentários explicando por que certos imports foram ignorados, em vez de removê-los.

Veja a 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. Ajude-me a corrigir todos os erros em client.py.

Comandos do Claude Code

Alguns comandos para você testar com o Claude:

Também recomendo conferir os tutoriais oficiais da Anthropic e nosso guia de boas práticas do Claude Code.

Recursos avançados do Claude Code

Depois que você estiver confortável com o básico de refatoração e depuração, 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 não executar sozinho.

Hooks usam um sistema 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 executar 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 para bloquear operações.

Casos de uso comuns de hooks incluem:

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

• 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 automaticamente 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 via Slack quando arquivos importantes mudarem

• Conformidade: aplicar cabeçalhos de licença ou padrões de codificação antes de permitir modificações

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

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 de shell, plugins integram seu ecossistema de desenvolvimento mais amplo, como pipelines de CI/CD, ferramentas de gestão de projetos e plataformas de comunicação da equipe.

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

Um plugin pode analisar mudanças de código e abrir issues automaticamente no Jira, ou conectar à sua infraestrutura interna de testes. Plugins respondem aos mesmos eventos que 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 se destacam:

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

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

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

• Revisão de código: criar pull requests e gerenciar revisões no GitHub/GitLab

• Análise externa: chamar SonarQube, CodeClimate ou Snyk para varreduras corporativas de código

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

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

Instale plugins de um registry ou desenvolva internamente para sua organização e configure a quais eventos 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 em 2026 vários recursos que ampliam como e onde você pode usá-lo:

• Plan mode: um fluxo design-first em que o Claude cria um plano detalhado antes de escrever qualquer código. Uso para tarefas não triviais.
• Auto mode: um classificador de permissões que deixa o Claude trabalhar com menos interrupções, útil em tarefas longas quando você não quer aprovar cada escrita de arquivo.
• 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 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 do código, adicionamos documentação estruturada e resolvemos problemas de import.

O Claude Code está evoluindo ativamente com recursos como plan mode, auto mode e Routines, então vale a pena experimentar nos seus projetos para ver como ele se encaixa no seu fluxo.

Para avançar, recomendo ler nosso tutorial de boas práticas do Claude Code, que ensina a aproveitar ao máximo a janela de contexto do Claude. Se você quer construir um projeto do zero, veja nosso tutorial sobre Spec-Driven Development com Claude Code.