Claude Code: desenvolvimento orientado por contexto

TL;DR

O Claude Code da Anthropic é um harness em que o agente trabalha diretamente sobre o repositório, explorando a base de código conforme necessário. Em projetos grandes, gerar código é a parte fácil. Entender as consequências de cada alteração é o verdadeiro problema.

• O Claude Code lê a árvore de arquivos, instruções do projeto e código relacionado antes de propor qualquer mudança.
• A exploração automática do repositório substitui o prompt vazio: o agente descobre o que precisa saber em vez de depender do que você lembra de contar.
• Alterações em múltiplos arquivos são coordenadas com contexto compartilhado, não como patches isolados.
• Terminal, Git, testes e refatorações funcionam dentro do mesmo loop: ler, modificar, validar, commitar.
• O contexto persistente via `CLAUDE.md` mantem instruções do projeto entre sessões, sem reinventar a configuração a cada conversa.
• Permissões configuráveis definem onde o agente pode agir sozinho e onde precisa de confirmação.
• Em bases legadas grandes, o valor não está em gerar código novo, mas em navegar e compreender o que já existe.
• ~ 7 min de leitura · ~ 1.400 palavras

~ 7 min de leitura · 1187 palavras

O problema não é gerar código, é encontrar contexto

Quando um agente de IA recebe um pedido para corrigir um bug num sistema complexo sem acesso ao repositório, o resultado comum é código perfeito para um problema que não existe. O agente alucina uma causa porque o prompt não tem espaço para o contexto real: regras de negócio escondidas em stored procedures, campos calculados que dependem de outros módulos, comportamentos que só fazem sentido com a história do projeto.

Isso não é falha do modelo. É falha do isolamento. Quando o agente vive numa janela de chat separada do projeto, ele depende de você — humano falho, com memória limitada — para resumir o que importa. E você nunca lembra de tudo.

O Claude Code resolve isso de uma forma simples: ele entra no repositório.

Como o Claude Code entende um projeto de verdade

Em vez de colar trechos de código no chat, o Claude Code trabalha sobre o diretório do projeto. Ele lê a árvore de arquivos, identifica a estrutura de diretórios, reconhece padrões de organização e busca código relacionado à tarefa que você descreveu.

Isso significa que quando você pede “refatore a função de cálculo de ICMS”, o agente não precisa que você cole a função. Ele encontra. Depois, segue as referências: onde essa função é chamada, quais módulos dependem dela, se há testes que cobrem os casos de borda.

Para projetos legados, isso é a diferença entre útil e inútil. Numa base de código com dez anos de história, ninguém lembra de todos os cantos onde uma regra foi reutilizada. O agente que explora sozinho economiza horas de grep manual.

O entendimento não é total — o agente não “compreende” o projeto como um arquiteto sênior. Mas ele acessa o contexto relevante sem depender da sua memória. Isso já é uma mudança de categoria.

Exploração automática e planejamento antes de executar

Antes de tocar em qualquer arquivo, o Claude Code costuma propor um plano. Ele lista o que pretende fazer, quais arquivos vai alterar e por quê. Você pode aprovar, rejeitar ou pedir ajustes.

Esse planejamento é mais importante do que parece. Em bases grandes, a diferença entre um refactor seguro e um desastre é saber quais arquivos serão afetados antes de começar. O agente que planeja em voz alta — mostrando o que vai mudar e onde — permite que você intercepte erros de contexto antes que eles virem commits.

A exploração automática funciona assim: o agente busca arquivos relevantes, lê os que parecem conectados, e refina o plano conforme descobre dependências. Não é magia. É uma busca sistemática com critério, executada numa velocidade que um humano não alcançaria sem perder o fio.

Alterações em múltiplos arquivos

Quando uma mudança afeta mais de um arquivo — o que é a regra, não a exceção, em software real — o Claude Code propõe alterações coordenadas. Ele mantém o contexto entre arquivos: se você renomeia uma função num módulo, ele atualiza as chamadas nos outros.

Isso soa óbvio, mas não é. A maioria das ferramentas de IA gera código arquivo por arquivo. O humano fica responsável por garantir coerência. O Claude Code trata o repositório como unidade de trabalho, não o arquivo individual.

O resultado é que refatorações de médio porte — renomear uma entidade, extrair um serviço, migrar um padrão — saem mais consistentes. Não perfeitas. Mas consistentes.

Terminal, Git, testes e refatorações

O Claude Code roda dentro do terminal. Ele executa comandos, roda testes, lê outputs e ajusta o plano conforme os resultados. Se um teste falha, ele vê o erro e pode propor correção.

A integração com Git é natural: commits, branches, diff — tudo acessível ao agente. Isso significa que o loop “modificar → testar → commitar” acontece sem você ter que copiar e colar entre janelas.

Testes são especialmente importantes. O agente que pode rodar a suite de testes antes de propor um refactor tem uma chance muito maior de não introduzir regressões. Não é garantia — testes também têm limites — mas é uma camada de segurança que prompt isolado nunca oferece.

Contexto persistente: CLAUDE.md e permissões

O arquivo `CLAUDE.md` funciona como instruções persistentes do projeto. Você define convenções, padrões de código, arquitetura, regras de negócio — e o agente carrega isso em cada sessão. Não precisa repetir as mesmas instruções a cada conversa.

Isso é útil, mas tem limites. O `CLAUDE.md` não é memória. É documentação que o agente lê no início de cada sessão. Se você não mantém atualizado, ele trabalha com regras desatualizadas. Se você escreve mal, ele interpreta mal.

As permissões são outra camada importante. Você configura o que o agente pode fazer sozinho e onde precisa de confirmação. Em produção, eu recomendo confirmar alterações em arquivos críticos. Autonomia total é para quando você já confia no agente — e confiança vem de uso controlado.

Uso em bases legadas grandes

Aqui está onde o Claude Code muda de interessante para essencial. Em bases legadas grandes — o tipo de sistema que cresceu durante anos sem documentação — o valor do agente não está em gerar código novo. Está em navegar e compreender o que já existe.

Quando você precisa alterar uma regra de negócio num sistema com dez anos de história, o problema não é escrever o novo código. É descobrir onde a regra está implementada, quais módulos dependem dela, e o que vai quebrar se você mudar. O Claude Code não resolve isso sozinho, mas acelera a descoberta.

Em bases legadas grandes, traçar o caminho de um campo calculado pode levar dias. Um agente que lê a árvore de arquivos, busca referências e propõe onde olhar não substitui o engenheiro — mas pode cortar o tempo de descoberta de dias para horas.

A reflexão que importa: código é fácil, consequências são difíceis

Em projetos grandes, gerar código é a parte fácil. Entender as consequências de cada alteração é o verdadeiro problema. O Claude Code não resolve o problema sozinho — nenhuma ferramenta resolve. Mas ele muda o local do problema: de “como faço o agente entender o contexto?” para “como eu valido o que o agente descobriu?”.

Essa é uma mudança de categoria. Quando o agente tem acesso ao contexto real do projeto, a conversa muda de adivinhação para validação. De “escreve código para mim” para “leu o repositório, propôs um plano, executou testes — e agora eu verifico se faz sentido”.

A ferramenta é a parte fácil. Cultura, processo e governança continuam sendo o que separa o uso produtivo do uso perigoso.

Leitura relacionada

• OpenAI Codex: o terminal virou um ambiente de desenvolvimento — outro harness agêntico no ecossistema de IA para desenvolvimento, com foco em terminal e execução.
• Google Antigravity: quando a IDE deixa de ser o centro do desenvolvimento — a visão macro sobre por que as ferramentas de desenvolvimento estão mudando de lugar.
• Programar ficou mais fácil ou apenas trocamos dificuldades? — a reflexão sobre o que realmente mudou na produtividade do desenvolvedor.

—

*Roberto Brandini — Código em Produção*