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

O que é o Claude Code?

Claude Code é uma ferramenta que roda diretamente no seu terminal, entende sua base de código e ajuda com tarefas de desenvolvimento usando 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 orientadas por 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, a lógica e as dependências do seu código.
• Testes e linting automatizados: execute e corrija testes com falha, rode comandos de lint e melhore a qualidade do código.
• Integração com Git: pesquise o histórico do git, resolva conflitos de merge, crie commits e gere pull requests com facilidade.

Seja em um projeto open source ou gerenciando bases de código corporativas, o Claude Code ajuda com automação inteligente que se adapta ao seu estilo e às exigências do projeto. Atualizações recentes trouxeram o auto mode (menos interrupções de permissão), o plan mode (fluxos com foco no design) e Routines (agentes em nuvem agendados que rodam por gatilhos sem o seu computador ligado).

Alguns perfis ideais para este serviço:

• Desenvolvedores de software: melhorar 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 em 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 apresentou o Cowork para ajuda em estilo agente com tarefas do dia a dia envolvendo arquivos e documentos além de código. Ele está disponível para todos os assinantes de planos pagos (Pro, Max, Team, Enterprise) no app Claude Desktop.

Vamos começar nosso projeto hands-on.

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 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ê poderá escolher entre usar o Claude Code com uma assinatura paga ou com cobrança por uso da API.

Em seguida, você receberá um link de login que leva a 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 acompanhamento de uso e gestão de custos.

Agora o Claude Code está pronto para uso.

Passo 2: configurando o ambiente de desenvolvimento

Para este 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, armazenamento e APIs geradas automaticamente.

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

1. Abra o terminal, navegue até o diretório onde quer 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 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á configurado 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 no client.py relacionado à 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 organização.
• Adicionar docstrings e comentários inline que esclareçam a função dos componentes.
• Identificar e corrigir bugs analisando issues e outros possíveis erros.

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 execute o Claude Code:

cd supabase
claude

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

Refatorando código

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

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 as mudanças. Ao finalizar, o Claude Code atualizará o arquivo, mostrará as modificações no terminal e trará um resumo do que foi feito.

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

• Organização dos imports:  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 por 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 várias linhas ao combinar imports semelhantes 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 gera, atualiza e padroniza a documentação de código em todo o projeto. Ele identifica trechos sem documentação, cria docstrings e comentários estruturados e verifica a aderência aos padrões do projeto.

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

• Docstrings claros no nível do módulo explicando o propósito do arquivo.
• Comentários detalhados por seção 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.

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 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 para imports ausentes, erros em tempo de execução ou problemas de lógica, ele reduz o espaço de busca e propõe ajustes direcionados.

Veja como usar o Claude Code para depurar:

1. Identificar o problema:  compartilhe a mensagem de erro com o Claude.
2. Obter recomendações de correção: peça soluções possíveis ao Claude.
3. Aplicar e validar a correção:  implemente as sugestões do Claude e verifique se o problema foi resolvido.

O Claude Code adotou as seguintes medidas para resolver problemas de import no arquivo client.py: 

• Comentários type ignore: adicionado o comentário # type: ignore para suprimir alertas do IDE e do verificador de tipos sobre imports não resolvidos.
• Categorização consistente de erros: o Claude Code garantiu que imports de erros de autenticação, banco, storage e functions fiquem claramente agrupados.
• Legibilidade mantida: foram adicionados comentários indicando por que certos imports foram ignorados em vez de removidos.

Veja a comparação lado a lado do código original e do código corrigido.

Prompt: Estou vendo alguns bugs, como 'Import gotrue.errors' could not be resolved. Me ajude a corrigir todos os erros em client.py.

Comandos do Claude Code

Alguns comandos para você testar com o Claude:

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

Recursos avançados do Claude Code

Depois que você dominar o básico de refatoração e depuração, pode 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 automáticos 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, em que você define três coisas:

• O evento: quando o hook é acionado?

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

• O comando: o que é executado quando o hook dispara?

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

Casos de uso comuns de hooks incluem:

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

• Testes: executar suítes de teste após modificações para pegar 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: alertar seu time no Slack quando arquivos importantes mudarem

• Conformidade: exigir cabeçalhos de licença ou padrões de código 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 reunir 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 se conectar à sua infraestrutura interna de testes. Plugins respondem aos mesmos eventos que hooks, mas enviam dados para 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: acionar builds, testes e deploys quando arquivos mudarem

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

• 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 reviews no GitHub/GitLab

• Análises externas: chamar SonarQube, CodeClimate ou Snyk para varredura corporativa de código

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

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

Instale plugins de um registro ou desenvolva internamente para sua organização, depois 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 outros recursos importantes em 2026 que ampliam como e onde você pode usá-lo:

• Plan mode: um fluxo de trabalho design-first em que o Claude cria um plano detalhado antes de escrever qualquer código. Eu uso para qualquer tarefa não trivial.
• 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 gravação 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 IDEs: o Claude Code tem 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 com elas 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 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. Vale experimentar nos seus próprios projetos para ver como ele se encaixa no seu fluxo de trabalho.

Para dar o próximo passo, confira nosso tutorial de melhores 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, recomendo nosso tutorial sobre Spec-Driven Development com Claude Code.