Claude Code – #5 Planejamento antes do código

A armadilha do código gerado sem plano

A velocidade com que assistentes de IA produzem código é tentadora. Em poucos segundos, um prompt pode gerar dezenas de linhas que resolvem um problema, mas essa agilidade frequentemente esconde uma armadilha. Sem um direcionamento prévio, o Claude Code tende a assumir decisões arquiteturais, namespaces e estruturas que podem não se integrar bem ao restante da base de código existente. O resultado mais comum é a geração de um bloco funcional, porém desconexo, que não segue os padrões do projeto e exige um esforço extra de refatoração. O episódio aborda justamente esse ponto de atrito, mostrando como pular a etapa de planejamento leva a um ciclo ineficiente de geração e correção.

Plan Mode como arquiteto consultivo

A solução apresentada é o Plan Mode, uma funcionalidade do Claude Code que separa a ideação da implementação. Em vez de partir diretamente para a escrita do código, o modo de planejamento atua como um arquiteto consultivo. Ele analisa a solicitação do desenvolvedor e propõe uma estratégia estruturada, detalhando a arquitetura da solução, os padrões de projeto a serem adotados e a sequência lógica de arquivos a serem criados ou modificados. Essa abordagem é especialmente valiosa em frameworks opinativos como o Laravel, onde a localização correta de uma classe ou trait define a manutenibilidade do sistema. O Claude Code, neste modo, sugere contratos de interface, nomes de métodos e fluxos de dados antes que qualquer caractere de código seja efetivamente escrito.

Como funciona a síntese de requisitos

Na demonstração prática, Tiago Matos ilustra como um pedido vago de feature se transforma em um plano de ação concreto. O Plan Mode sintetiza os requisitos, explora ambiguidades e consolida uma específicação técnica antes de prosseguir. Esse processo inclui a definição de classes de serviço, a separação de responsabilidades em ações ou commands e a previsão de cenários de borda que o desenvolvedor pode não ter considerado inicialmente. A ferramenta não apenas ouve, mas questiona, esclarecendo se uma operação deve ser síncrona ou assíncrona, se é necessário um evento de domínio ou se um determinado dado merece um Value Object dedicado. O resultado da fase de planejamento é um documento de design leve, mas suficiente para alinhar expectativas antes da execução.

Controlando o escopo e evitando alucinações

Um risco constante no uso de IA para programação é a alucinação de dependências e a invenção de bibliotecas inexistentes. Ao delimitar o escopo no plano, reduz-se drasticamente a superfície de contato onde esses erros podem ocorrer. O episódio enfatiza que, com um blueprint claro, o Claude Code mantém-se aderente ao que foi acordado, utilizando apenas os namespaces e pacotes listados no planejamento. Tiago demonstra como o plano atua como uma restrição criativa, forçando a ferramenta a resolver o problema dentro dos contornos estabelecidos, em vez de divagar por soluções criativas, porém incompatíveis com o ecossistema do projeto. Essa previsibilidade é o que torna o código gerado verdadeiramente integrável.

Integração com repositórios e contexto externo

O poder do planejamento se amplifica quando o Claude Code tem acesso ao repositório. O Plan Mode pode ser instruído a ler diretórios existentes, analisar models, controllers e services para garantir que o novo código respeitará a topologia atual da aplicação. O vídeo destaca brevemente como a ferramenta utiliza esse contexto para sugerir modificações em arquivos já existentes, em vez de duplicar lógicas. Se um Form Request já trata determinada validação, o plano indicará seu reaproveitamento. Esse nível de consciência contextual elimina o retrabalho de apagar ou reescrever trechos gerados que colidem com o código legado, um dos principais gargalos do desenvolvimento assistido.

Aplicação prática na rotina de desenvolvimento

Tiago contextualiza o uso do Plan Mode dentro de um fluxo de trabalho realista, não como um experimento laboratorial, mas como uma ferramenta diária para desenvolvedores PHP e JavaScript. A abordagem é apresentada como uma ponte entre a ideação do desenvolvedor sênior, que conhece as regras de negócio, e a capacidade de execução rápida da IA. Em vez de digitar longas instruções tentando prever todos os detalhes de uma só vez, o profissional pode iterar sobre o plano de forma barata. Ajustar um diagrama textual de arquitetura é muito mais rápido do que refatorar centenas de linhas de código gerado, e essa diferença de custo temporal é o argumento central para a adoção imediata da funcionalidade.

A maturidade do desenvolvimento com IA

O vídeo conclui com uma reflexão implícita sobre a maturidade na adoção de ferramentas de IA. Não se trata mais de gerar código por gerar, mas de gerar o código certo. A integração do Plan Mode simboliza uma transição de um modelo puramente reativo da IA para um modelo colaborativo e deliberativo. A mensagem final reforça a necessidade de tratar o código como consequência de um bom design, e não como um fim em si mesmo. Com a popularização de agentes autônomos de codificação, saber orquestrar e revisar planos torna-se tão crucial quanto saber programar, e este episódio oferece um guia prático para iniciar essa transição.