Como pedi pra IA construir minha ferramenta de diagnóstico (e o que aprendi)

O mapeamento.expertintegrado.com.br foi construído com Claude Code em 3 semanas. Eu não escrevi uma linha de código. Mas desperdicei 2 dias na primeira semana porque comecei sem spec. Esse post é o making-of honesto — incluindo as 3 iterações que foram pro lixo.

Vou ser direto: isso não foi um processo linear de “pedi pra IA, funcionou, acabei”. Teve retrabalho, teve código descartado, teve momento em que eu quase voltava pra uma solução com formulário estático. O que me manteve no caminho foi entender — no meio do processo — onde eu estava errando na comunicação com a IA. Esse post é sobre isso.

O que é o mapeamento e por que precisava construir?

O mapeamento é uma ferramenta de diagnóstico que a gente usa antes de toda venda da Expert Integrado. O cliente responde perguntas sobre o estágio atual de IA na empresa dele, a gente processa as respostas e entrega um relatório personalizado com gaps e recomendações.

Antes, isso era feito no Google Forms + planilha + template de relatório no Notion. Funcionava, mas escalava mal. Cada relatório levava 40 minutos pra ser gerado manualmente. Com 3 a 5 diagnósticos por semana, virou um gargalo real no processo comercial.

A alternativa era contratar uma agência pra construir a ferramenta. O orçamento que recebi foi R$18.000, com prazo de 8 semanas. Resolvi tentar com Claude Code primeiro. Fiz em 3 semanas e o custo foi basicamente meu tempo.

Qual foi o erro da primeira semana (a spec não escrita)?

A primeira semana foi um desperdício quase total. Eu abri o Claude Code e comecei a pedir coisas diretamente: “cria um formulário com essas perguntas”, “agora conecta com o banco de dados”, “gera o relatório em PDF”. O Claude gerava código, eu testava, algo quebrava, eu pedia pra corrigir.

Ao final de 2 dias eu tinha um formulário funcional que não se integrava com nada que eu ia precisar. O problema não era o código — era que eu não tinha explicado o sistema inteiro antes de começar. Cada pedido estava desconectado do próximo. A IA não tem como adivinhar onde você quer chegar se você não mostrou o destino.

O insight que mudou tudo: a IA é ótima em executar etapas. Ela é ruim em deduzir a arquitetura geral se você não der. Você precisa trazer a visão de sistema — ela traz a execução.

Como escrevi a spec que funcionou?

Joguei fora o que tinha e passei meio dia escrevendo uma spec antes de escrever uma linha de código. O prompt que usei pra me ajudar a estruturar a spec foi esse:

Você é um arquiteto de software sênior. Vou te descrever um sistema que quero construir.
Sua tarefa é me fazer perguntas até entender o suficiente pra escrever uma spec técnica
completa — stack, fluxo de dados, componentes, integrações e critérios de aceitação
por feature. Não escreva código ainda. Só pergunte.

O Claude fez 14 perguntas. Algumas eu não sabia responder na hora — o que por si só já foi útil, porque me forçou a pensar em decisões que eu estava adiando. Depois de responder tudo, pedi pra ele redigir a spec. Ficou um documento de 8 páginas cobrindo stack (Astro + Cloudflare Workers + D1), fluxo do formulário, lógica de scoring, geração de relatório e critérios de aceite por feature.

A partir daí o processo mudou completamente. Cada pedido de código tinha contexto. A IA sabia onde estava no sistema.

Por que a regra do 1 feature por vez importa tanto?

Na segunda semana eu cometi um erro diferente. Com a spec pronta, fiquei animado e mandei tudo de uma vez: “implementa o formulário, o sistema de scoring, a geração de relatório e o envio por email”. O Claude tentou fazer tudo junto. O código que saiu era confuso, misturava responsabilidades e tinha bugs em 3 lugares diferentes ao mesmo tempo.

A regra que aprendi: uma feature por sessão, revisão completa antes de seguir pra próxima.

O motivo é técnico e cognitivo ao mesmo tempo. Técnico: quando a IA tenta implementar muita coisa de uma vez, ela perde o rastreamento de dependências entre componentes. Cognitivo: quando você revisa código de 5 features de uma vez, você não revisa nada — você aprova na pressa.

O fluxo que funcionou foi: pedir uma feature, testar no browser, verificar que funcionava como esperado na spec, commitar, e só então pedir a próxima. Parece lento, mas é mais rápido que depurar código embaralhado.

Quais foram as 3 iterações descartadas?

Iteração 1 (dias 1-2): O formulário sem spec, já descrito acima. Descartado porque não tinha arquitetura definida — cada componente era uma ilha.

Iteração 2 (dia 6): A primeira versão com spec, mas ainda usando Next.js como stack. O problema foi o deploy. Cloudflare Workers tem limitações com o runtime do Next que eu não tinha mapeado. Passei um dia inteiro tentando fazer o build funcionar no edge. Desisti e migrei pra Astro + Hono, que tem suporte nativo ao Cloudflare. Perda de 1 dia. Lição: pesquisar as limitações da stack antes de começar, não no meio.

Iteração 3 (dia 11): A lógica de scoring estava hardcoded dentro do worker. Quando precisei ajustar os pesos das respostas, tive que mexer direto no código. Descartei essa abordagem e refiz com a configuração de scoring em JSON separado, carregado como binding no Cloudflare. A partir daí qualquer ajuste nos critérios é editar um JSON, não código.

Três iterações descartadas num processo de 3 semanas é muito? Não acho. Cada descarte ensinou algo que foi incorporado na versão seguinte. O problema seria se eu tivesse continuado empurrando código ruim pra frente em vez de reconhecer o erro e reiniciar.

O que ficou no ar e o que não ficou?

Ficou: formulário com 22 perguntas, lógica de scoring por dimensão (processos, cultura, ferramentas, dados), geração automática de relatório em PDF, envio por email com template personalizado, dashboard interno pra acompanhar respostas.

Não ficou: comparativo por setor (precisaria de dados históricos que ainda não temos), integração automática com o Pipedrive (ficou manual por enquanto — o webhook estava gerando duplicatas), versão em inglês (priorizamos o mercado brasileiro).

O que ficou de fora não é fracasso — é priorização. A versão que está no ar resolve 90% do problema original. As features descartadas ficaram documentadas na spec pra uma próxima iteração.

Tempo total: 3 semanas de trabalho esparso, talvez 30 horas efetivas. Custo: $0 de desenvolvimento externo + ~$40 de uso de API do Claude. A ferramenta está em produção e processou mais de 80 diagnósticos desde o lançamento.

Perguntas frequentes

Preciso saber programar pra fazer o que você fez?

Não precisei escrever código, mas precisei entender o suficiente pra revisar o que a IA gerou e identificar quando algo estava errado. Isso não é o mesmo que saber programar, mas também não é zero. Se você não consegue ler um arquivo de configuração ou entender a diferença entre frontend e backend, vai ter dificuldade. Dá pra aprender o mínimo necessário em algumas semanas focadas — é esse nível que o Vibe Coding pressupõe.

Por que usou Claude Code e não ChatGPT ou Cursor?

Eu uso Claude Code porque ele opera direto no terminal com acesso ao filesystem e consegue executar comandos. Pra um projeto de 3 semanas com múltiplos arquivos e dependências, ter o agente operando no contexto real do projeto faz diferença. ChatGPT via chat é bom pra perguntas e rascunhos; Claude Code é bom pra construção real. Cursor é uma alternativa válida se você prefere interface gráfica.

A spec que você escreveu foi técnica ou em linguagem comum?

Em linguagem comum com alguns termos técnicos que aprendi no processo. A spec descrevia comportamentos esperados (“quando o usuário termina o formulário, o sistema calcula o score e gera o PDF em menos de 5 segundos”) mais do que detalhes de implementação. A IA traduz comportamento esperado em código — você não precisa ditar a implementação.

Quanto tempo você gasta mantendo a ferramenta depois do lançamento?

Pouco. Em 3 meses desde o lançamento, fiz 4 atualizações: dois ajustes de copy no relatório, um ajuste na lógica de scoring e uma correção de bug no envio de email. Cada uma levou menos de 1 hora com Claude Code. O modelo de Vibe Coding não para no lançamento — você continua com o mesmo fluxo pra manutenção e evoluções.

Valeu a pena comparado a contratar uma agência?

R$18.000 e 8 semanas vs. 30 horas do meu tempo e $40. A conta parece obvia, mas tem um componente que não está no preço: eu entendo cada parte do sistema porque fiz junto com a IA. Quando preciso mudar algo, não dependo de terceiro. Isso vale mais do que a economia em dinheiro.

Bora testar? Se você tem um processo manual que se repete toda semana e poderia virar uma ferramenta, o caminho é esse: spec primeiro, uma feature por vez, revisar antes de avançar. O resto a IA faz.