Claude Code 2.1: Um guia com exemplos práticos

O Claude Code é uma ferramenta de codificação desenvolvida pela Anthropic que funciona direto no seu terminal e também pode ser usada por uma interface web conectada. Em vez de trabalhar com comandos isolados, o Claude Code entende todo o repositório, consegue raciocinar entre arquivos, editar código e usar ferramentas. 

Comparado com versões anteriores, que focavam principalmente na assistência interativa ao código, o Claude Code 2.1 oferece suporte adicional para agentes, ganchos e habilidades reutilizáveis que podem moldar ativamente como e quando as alterações no código ocorrem.

O Claude Code foi feito pra desenvolvedores que querem a ajuda da IA direto nos fluxos de trabalho reais, em vez de ficar pulando entre um editor e uma interface de bate-papo. Mesmo ainda sendo uma prévia de pesquisa, já mostra uma utilidade prática incrível em fluxos de trabalho de desenvolvimento reais. 

Se você quiser saber mais sobre os modelos Claude, recomendo fazer o curso curso Introdução aos Modelos Claude. 

O que há de novo no Claude Code 2.1?

O Claude Code 2.1 melhora a experiência do terminal principal com um monte de atualizações que deixam os fluxos de trabalho dos agentes mais flexíveis. Essas mudanças mudam a forma como o Claude Code pensa sobre uma base de código e como os desenvolvedores interagem com ela durante tarefas reais de desenvolvimento.

Algumas das novidades mais legais do Claude Code 2.1 são:

• Agente e ganchos de habilidade no frontmatter, permitindo que os desenvolvedores apliquem verificações e restrições antes que qualquer edição de código seja feita.
• Suporte ampliado para habilidades com contexto bifurcado, recarga a quente e definições personalizadas de habilidades, tornando os fluxos de trabalho reutilizáveis mais flexíveis e poderosos.
• A invocação da habilidade Slash (/) permite acessar rapidinho as ações que você usa sempre durante as sessões interativas.
• Os agentes no Claude Code 2.1 não param mais de raciocinar quando uma invocação de ferramenta é negada, permitindo que os fluxos de trabalho continuem sem interrupção.
• A ferramenta suporta respostas controladas por idioma, que são especialmente úteis para documentação multilíngue, revisões e colaboração em equipe.
• As permissões de ferramentas curinga, como Bash(*-h*), oferecem controles de automação mais detalhados.
• A CLI agora suporta Shift+Enter para entrada multilinha, melhorando a experiência de criação interativa sem precisar de configuração extra.

Neste guia, vamos focar em um conjunto de experimentos práticos que mostram como essas novas funcionalidades são usadas em projetos reais.

Configurando a experiência web baseada em nuvem do Claude Code

O Claude Code 2.1 está disponível como uma experiência baseada na web que funciona totalmente na nuvem. Esse modo é super útil para fluxos de trabalho colaborativos, revisões de solicitações pull e automação no nível do repositório sem precisar de uma configuração local.

Passo 1: Faça login e acesse o Claude Code

Para começar, vá até https://claude.ai/code e você vai chegar na interface do Claude Code (Pré-visualização de pesquisa). 

Passo 2: Conecte o Claude Code ao GitHub

Pra trabalhar com repositórios reais, o Claude Code precisa acessar o GitHub. Clique em Conectar ao GitHub, que instala o aplicativo Claude GitHub. 

Durante a autorização, o GitHub vai pedir permissão para se conectar aos repositórios por:

• Verificando sua identidade no GitHub
• Veja quais repositórios o Claude pode acessar
• Aja em seu nome (por exemplo, criando ramificações ou commits)

Você pode escolher entre:

• Todos os repositórios, ou
• Selecione apenas repositórios (recomendado para um controle mais rigoroso)

As permissões típicas incluem:

• Acesso de leitura aos metadados e verificações do repositório
• Acesso de leitura e escrita a código, problemas, solicitações de pull e fluxos de trabalho

Clique em Instalar e autorizar, e você poderá modificar ou revogar o acesso posteriormente diretamente nas configurações do aplicativo do GitHub. Essa etapa é necessária para que o Claude Code leia repositórios, abra solicitações de pull e envie commits ao trabalhar no ambiente web.

Passo 3: Crie um ambiente em nuvem

Antes de começar sua primeira sessão, o Claude Code te pede pra criar um ambiente na nuvem. Esse ambiente controla o acesso à rede e os limites de execução do Claude.

As opções disponíveis são:

• Nenhum: Essa opção não tem acesso à Internet, sendo útil principalmente para segurança máxima.
• Confiável (recomendado): Ele dá acesso a fontes de pacotes verificadas.
• Completo: Essa configuração dá acesso livre à internet.

Na maioria dos casos, a opção “ Trusted ” oferece o melhor equilíbrio entre segurança e flexibilidade.

Passo 5: Comece uma sessão na web

Depois que a configuração estiver pronta, você vai ser levado para o editor web Claude Code, como mostra a captura de tela abaixo.

A partir daqui, você pode:

• Escolha um repositório e um branch
• Executar refatorações e revisões
• Crie novos branches e commits
• Retomar sessões anteriores (se houver)
• Trocar entre repositórios sem mudar de ambiente

Configurando a experiência CLI baseada no terminal Claude Code

A CLI é a maneira mais direta de trabalhar com o Claude Code 2.1. É ideal para desenvolvimento local, refatorações passo a passo e situações em que você deseja um controle refinado sobre o que o Claude faz no seu repositório.

Passo 1: Instalação

O Claude Code pode ser instalado direto do terminal usando um instalador específico para cada plataforma.

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

Quando a instalação terminar, você deve ver uma mensagem de confirmação mostrando a versão do Claude Code junto com o caminho de instalação. Para mais opções de configuração, dá uma olhada no guia oficial de configuração.

Passo 2: Começando

Depois de instalar, vá até a raiz do seu projeto e comece o Claude Code:

cd your-project-directory
Claude Code

Quando o Claude Code começa, ele imediatamente verifica o repositório e cria uma compreensão inicial da base de código. 

Esse contexto inicial permite que Claude Code raciocine de forma mais eficaz nas etapas posteriores.

Experimentando com o Claude Code 2.1

Pra essa demonstração, usei um dos meus projetos do GPT 5.2. Aqui vai uma visão geral rápida do projeto.

Assim que o Claude Code tiver acesso a todos os arquivos e pastas dentro da pasta, podemos começar a experimentar.

Refactor usando habilidades de contexto bifurcadas 

Como parte da avaliação do Claude Code 2.1, fiz uma refatoração em todo o repositório para melhorar o pipeline. Essa experiência mostra como o Claude consegue lidar com contextos bifurcados, ou seja, ele consegue pensar em vários arquivos ao mesmo tempo, em vez de fazer edições isoladas em um único arquivo.

Sugestão:

Refactor the CSV parsing and slide generation logic across the repository.
Improve readability, split responsibilities, and avoid duplicated logic.

Claude primeiro faz um plano detalhado de refatoração, incluindo a estrutura proposta para os módulos, pontos de duplicação e uma sequência de implementação, e depois pede aprovação antes de mudar qualquer coisa. 

Depois que você aprovar, o Claude vai aplicar a refatoração aos poucos, mostrando as diferenças e o progresso conforme avança.

Usando o Claude Code, consegui as seguintes melhorias:

• Divida as responsabilidades entre os módulos: Claude separou o carregamento de CSV, as transformações, a criação do Excel, a geração do PowerPoint e o planejamento do LLM (basicamente todos os módulos) em componentes dedicados.
• Lógica duplicada reduzida: Ele centralizou utilitários repetidos (como detecção e formatação de colunas) e moveu constantes compartilhadas para uma camada de configuração comum.
• Manutenção mais fácil: Claude também diminuiu o tamanho do aplicativo ( app.py ) sem mexer no comportamento externo dele.

Aqui tá uma comparação da estrutura do projeto e do resultado da refatoração antes e depois das mudanças.

Antes:

Depois:

Por fim, tentei a mesma refatoração no Claude Code Web. A principal diferença é o fluxo de trabalho:

• CLI avança passo a passo com aprovações explícitas.
• A Web pode enviar a refatoração diretamente para um novo branch, o que é conveniente para colaboração e fluxos de trabalho baseados em PR.

Por fim, Claude refatorou e enviou o código para um branch.

Gancho de validação pré-edição

Os pipelines de dados muitas vezes falham por um motivo simples: o esquema CSV de entrada não combina com o que o código espera. No Claude Code 2.1, você pode reduzir esse tipo de falha usando ganchos de pré-edição. Essa nova funcionalidade permite que um agente faça verificações de validação antes que o Claude possa mexer no código.

Neste exemplo, pedi ao Claude Code para criar um agente que valida a estrutura CSV antes de qualquer edição ser aplicada.

Prompt:

Create a Claude Code agent that validates the CSV schema before modifying any code. The agent should reject edits if the CSV schema is unclear.

Claude Code primeiro criou um agente de validação de esquema CSV e o conectou ao fluxo de trabalho para que ele pudesse funcionar como um gatekeeper. A saída da CLI mostra que Claude não criou só um script, mas montou um pequeno sistema de validação que inclui:

• Um módulo validador de esquema central que verifica as colunas necessárias, valores ausentes e consistência básica.
• Um gancho gatekeeper pré-edição faz a validação automaticamente antes de continuar com as edições.
• Por fim, um conjunto de testes e alguns exemplos de uso para verificar o validador em casos CSV válidos/inválidos.

Na prática, o fluxo de trabalho fica bem simples:

• O Claude faz automaticamente verificações de esquema antes de fazer qualquer alteração no código, garantindo que tudo esteja em ordem.
• Se o esquema não estiver claro ou for inválido, o agente bloqueia as edições e mostra mensagens de erro úteis para ajudar a resolver o problema.
• Depois que a validação é aprovada, Claude faz as modificações, mantendo as alterações dentro dos limites e previsíveis.

A saída da web mostra um resultado parecido, mas com uma diferença importante. O Claude Code Web pode enviar as alterações diretamente para um novo branch, incluindo o módulo de validação, integração de hook, documentação e testes. 

No geral, o Claude Code 2.1 coloca proteções antes das edições acontecerem, colocando ganchos direto nos agentes e nas habilidades. Isso torna os ganchos especialmente valiosos em projetos com muitos dados, onde a precisão das entradas costuma ser uma fonte maior de erros do que o próprio código.

Habilidades de comandos de barra para tarefas repetidas

O Claude Code 2.1 trouxe habilidades reutilizáveis de comando de barra, que são fluxos de trabalho independentes que podem ser chamados de forma interativa dentro de uma sessão do Claude ou executados direto da linha de comando. 

Neste exemplo, criamos uma habilidade reutilizável do /generate-slides que transforma um arquivo CSV em uma apresentação profissional do PowerPoint.

Prompt:

Create a reusable skill called /generate-slides that converts a CSV into a PPT.

Dica: Use /statusline para configurar uma linha de status personalizada que aparece abaixo do prompt de entrada (útil para mostrar repositório, ramificação ou modo).

O Claude Code cria uma definição completa de habilidade em .claude/skills/, incluindo documentação, lógica de validação e um ponto de entrada Python que dá pra rodar.

• Criação de habilidades: Claude escreve uma habilidade generate-slides totalmente documentada, descrevendo sua finalidade, entradas, etapas de validação e fluxo de execução.
• Validação do esquema: A habilidade verifica o esquema CSV antes de qualquer processamento, garantindo a qualidade dos dados e mensagens de erro claras.
• Execução: A habilidade pode ser executada diretamente do terminal, funcionando como uma ferramenta de linha de comando independente.
• Tratamento de erros: Arquivos que faltam, esquemas inválidos ou chaves API que não estão funcionando causam erros claros e fáceis de resolver.
• Automação: Um único comando gera artefatos do Excel, gráficos e uma apresentação do PowerPoint.

Você pode testar a habilidade localmente com:

python .claude/skills/generate-slides.py --csv-file kpis.csv

Nota: Não esquece de colocar sua chave API antes de rodar isso. 

As habilidades de comando de barra transformam o Claude Code em um mecanismo de fluxo de trabalho, não só um assistente. Em vez de repetir a mesma tarefa várias vezes, você define ela uma vez e usa de novo em projetos, sessões e ambientes diferentes. Você pode ver a estrutura atualizada do repositório abaixo, que mostra a adição da nova habilidade.

Esse exemplo mostra como:

• As habilidades podem ser chamadas de forma interativa a partir da CLI.
• As habilidades geradas pelo Claude se integram perfeitamente às bases de código existentes.

Saída controlada por idioma 

O Claude Code 2.1 pode ser configurado para responder em um idioma específico, o que é útil para equipes multilíngues, documentação localizada e orientações de código em outros idiomas além do inglês. Neste exemplo, pedimos ao Claude para explicar todo o processo de geração de slides do repositório em japonês.

Prompt:

Explain the slide generation logic in Japanese.

Claude respondeu em japonês e apresentou uma explicação detalhada sobre o fluxo de ponta a ponta. Como dá pra ver no resultado, ele não só traduziu um resumo, mas também dividiu o pipeline em fases claras e mencionou os módulos relevantes envolvidos em cada etapa. A saída da CLI mostra:

• Japonês de ponta a ponta: A resposta continua toda em japonês, incluindo títulos e marcadores.
• Fluxo passo a passo: Claude divide o pipeline em etapas distintas (validação de CSV, processamento de dados, pasta de trabalho do Excel, planejamento de LLM e criação de slides).
• Referências que reconhecem o código-fonte: Ele aponta para arquivos e diretórios relevantes enquanto explica o que cada componente faz.
• Formatação no estilo de documentação: A saída parece documentos internos, o que facilita reutilizá-la em um README ou guia de integração.

Observação: Eu só testei esse comportamento na CLI para este exemplo, mas a mesma capacidade de controle de idioma faz parte do Claude Code 2.1 como um todo.

É um recurso pequeno no papel, mas, na prática, é uma grande vantagem de produtividade quando a documentação e as revisões precisam ser feitas em outros idiomas além do inglês.

Comandos do Claude Code 2.1

Aqui estão alguns comandos para você experimentar com o Claude Code.

Conclusão

Neste guia, a gente explorou o Claude Code 2.1 fazendo experimentos práticos tanto na CLI quanto nos fluxos de trabalho da web. Usamos o Claude Code pra refatorar um repositório que já existia usando habilidades de contexto bifurcadas, garantir a validade dos dados com ganchos de validação pré-edição, criar habilidades de comando de barra reutilizáveis e gerar explicações controladas por linguagem direto da base de código.

Esses exemplos mostram como o Claude Code 2.1 vai além da simples edição assistida por IA, indo em direção a fluxos de trabalho de desenvolvimento mais orientados por agentes. Embora o Claude Code 2.1 ainda esteja em fase de pré-visualização de pesquisa, ele já mostra um grande valor prático em projetos reais.