Criando novas funcionalidades com o Claude Code

Neste capítulo você vai acompanhar o fluxo completo para implementar uma funcionalidade nova em um projeto que já existe: partir de um pedido vago, transformá-lo em uma especificação, obter e revisar um plano, implementar em etapas pequenas e verificar o resultado com a aplicação rodando. Vamos aplicar o que você já aprendeu sobre instruções eficientes, modo de planejamento e CLAUDE.md a um caso concreto, do início ao fim.

O exemplo é uma API em Node.js com Express, banco de dados acessado pelo Prisma e validação de entrada feita com a biblioteca Zod. A API já tem cadastro de tarefas. O pedido que chegou do time de produto foi curto: “as tarefas precisam ter prazo”. Só isso.

Do requisito vago à especificação

Um pedido como esse admite dezenas de interpretações. O prazo é obrigatório? Pode ficar no passado? A listagem deve destacar tarefas atrasadas? Se você mandar o Claude Code implementar direto, ele vai escolher uma interpretação, e você só descobrirá se foi a certa depois de ler o código. É muito mais barato descobrir antes.

A primeira etapa, portanto, é usar o próprio Claude Code para fechar a especificação. Entre no modo de planejamento pressionando Shift Tab quantas vezes for necessário: o atalho alterna entre os modos disponíveis, então repita até o indicador de plan mode aparecer na barra inferior — cuidado para não parar no modo de aceite automático de edições. Com o plan mode ativo, peça algo assim:

Quero adicionar um campo de prazo às tarefas. Antes de propor qualquer código, leia @src/routes/tarefas.js e @prisma/schema.prisma e me faça as perguntas que você precisaria responder para implementar isso sem ambiguidade. Não edite nada.

Ele devolve perguntas parecidas com as que listei, e provavelmente outras em que você não pensou, como o fuso horário da data e o formato aceito no corpo da requisição. Responda uma a uma. Ao final, peça que ele resuma tudo em uma especificação curta, com o comportamento esperado, as regras de validação e o que fica fora do escopo. No nosso caso, ficou assim: o campo chama-se prazo, é opcional, aceita uma data no formato ISO 8601, não pode estar no passado no momento da criação ou da edição, e a listagem de tarefas ganha um filtro opcional para retornar apenas as atrasadas. Ordenação por prazo fica fora do escopo.

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

Guarde esse texto. Ele será a referência para julgar cada resultado, e você poderá colá-lo de volta se precisar iniciar uma sessão nova.

Plano antes de qualquer alteração

Ainda no modo de planejamento, peça o plano de implementação com base na especificação. Diga explicitamente que quer a lista de arquivos que serão criados ou alterados, a ordem das etapas e como cada uma será verificada. Um bom plano para essa funcionalidade tem cerca de cinco passos: alterar o modelo no schema do Prisma e gerar a migração; atualizar o esquema de validação; ajustar as rotas de criação e edição; adicionar o filtro na listagem; atualizar a documentação da API.

Leia o plano com atenção e critique. É comum encontrar um passo que toca arquivos fora do escopo ou uma migração que apagaria dados. Corrija com feedback específico, como no capítulo quatro: “o passo três está mexendo no middleware de autenticação, isso não faz parte do escopo, remova”. Só quando o plano estiver do seu jeito, volte ao modo de execução.

Implementação em etapas pequenas

Não peça “implemente o plano inteiro”. Peça o passo um. Revise o diff. Rode a verificação daquele passo. Só então peça o passo dois. Isso mantém cada diff pequeno o suficiente para ser lido de verdade, e, quando algo dá errado, você sabe exatamente onde foi.

Execute apenas o passo 1 do plano: adicione o campo prazo, do tipo DateTime opcional, ao modelo Tarefa e crie a migração com o nome adiciona-prazo-tarefa. Depois rode a migração no banco de desenvolvimento e me mostre a saída.

Ele edita o schema, pede aprovação para executar o comando do Prisma e mostra a saída. Antes de aprovar, confirme que a variável DATABASE_URL aponta mesmo para o banco de desenvolvimento e tenha um backup se houver dados que importam: o comando de migração usado em desenvolvimento pode recriar o banco do zero e apagar tudo quando encontra divergência no histórico de migrações, e ele nunca deve ser executado contra produção, onde se usa o comando de deploy de migrações já revisadas. Confira se o arquivo de migração gerado faz apenas o que deveria. Depois peça o passo dois, e assim por diante.

Seguindo os padrões do projeto

Um risco real é o Claude Code introduzir um estilo estranho: uma biblioteca de validação diferente da que o projeto já usa, tratamento de erro fora do padrão, nomes em inglês onde o projeto usa português. Duas defesas funcionam juntas. A primeira é o CLAUDE.md do projeto, que já deve dizer que a validação é feita com Zod e que erros de entrada retornam código quatrocentos no formato padrão da API. A segunda é apontar um exemplo existente dentro do pedido: “siga exatamente o padrão de validação de @src/validators/tarefa.js e o formato de resposta de erro de @src/routes/usuarios.js”. Quando o Claude tem um modelo concreto para copiar, ele copia.

Decisões de design: peça opções

Em algum momento surge uma decisão que o plano não cobriu. No nosso exemplo: o filtro de tarefas atrasadas deve ser um parâmetro de consulta na rota de listagem existente ou uma rota nova? Não deixe a ferramenta decidir em silêncio. Peça duas ou três opções com os trade-offs de cada uma e escolha. Aqui o Claude apontou que o parâmetro de consulta mantém a API menor e segue o que o projeto já faz com outros filtros, enquanto uma rota separada facilitaria cache independente. Como não há cache, ficou o parâmetro. A decisão é sua; o Claude apenas organiza as informações para que você decida bem.

Tudo o que muda junto

Uma funcionalidade raramente vive em um único arquivo. Modelo, migração, validação, rota, tipos e documentação precisam mudar de forma coerente. O plano ajuda porque lista tudo, mas vale, ao final, pedir uma verificação de completude: “liste todos os lugares do projeto que descrevem a estrutura de Tarefa e confira se algum ficou sem o campo prazo”. É comum ele encontrar um exemplo de resposta em um arquivo Markdown ou uma coleção de requisições que ficou defasada. Peça para atualizar na mesma sessão, enquanto o contexto ainda está carregado.

Ao criar arquivos novos, seja explícito sobre caminho e nome, e peça que ele siga a organização de pastas existente. Se o projeto separa validadores em uma pasta própria, o novo validador de prazo deve nascer ali, e não dentro da rota.

Verificando com a aplicação rodando

Código que compila não é código que funciona. Peça ao Claude que inicie a aplicação e execute as requisições descritas na especificação: criar uma tarefa com prazo válido, criar uma com prazo no passado e confirmar o erro quatrocentos, listar com o filtro de atrasadas. Ele pode usar curl e mostrar cada resposta. Compare com a especificação que você guardou. Esse é o critério de pronto do capítulo quatro aplicado à funcionalidade inteira. A criação de testes automatizados para consolidar esse comportamento fica para o capítulo nove; aqui o objetivo é confirmar que funciona de ponta a ponta.

Quando o resultado diverge do esperado

Em algum passo o diff virá diferente do que você queria. Talvez ele tenha tornado o campo obrigatório, ou colocado a validação de data dentro da rota em vez do validador. A tentação é aceitar e consertar na mão, ou aceitar e pedir um remendo por cima. Resista. Recuse o diff e corrija a instrução, dizendo o que saiu diferente e o que você esperava, apontando para a especificação:

O campo ficou obrigatório; a especificação diz opcional. Refaça o passo 2 mantendo prazo opcional, sem alterar os demais campos e sem tocar em outros arquivos.

Por que isso importa? Remendos se acumulam: a lógica fica meio em um lugar, meio em outro, e o Claude passa a copiar esse padrão torto nos passos seguintes. Corrigir a instrução produz um diff limpo e ainda ensina você a escrever pedidos melhores. Se a mesma divergência se repetir em projetos diferentes, ela provavelmente merece uma linha no CLAUDE.md.

Se, depois de duas tentativas, ele continuar errando o mesmo ponto, o problema costuma ser contexto insuficiente ou contexto demais. Use /compact ou inicie uma sessão nova, cole a especificação e o plano, e peça apenas o passo problemático.

Recapitulando

• Transforme o pedido vago em especificação pedindo ao próprio Claude Code as perguntas necessárias, no modo de planejamento e sem editar nada.
• Obtenha um plano com arquivos, ordem e verificações, critique-o e só então mude para o modo de execução.
• Implemente um passo por vez, revisando cada diff e verificando antes de seguir.
• Garanta consistência com o CLAUDE.md e apontando exemplos existentes do projeto para copiar.
• Em decisões de design, peça opções com trade-offs e decida você.
• Confira que modelo, migração, validação, rota e documentação mudaram juntos, e valide executando a aplicação contra a especificação.
• Quando o resultado divergir, recuse o diff e corrija a instrução em vez de aceitar e remendar.