Como Depurar uma Aplicação Criada com IA: Um Método Prático

Para depurar uma aplicação criada com IA, primeiro faça o erro acontecer outra vez de propósito, depois recolha provas — os passos exatos, a mensagem de erro e o que a consola e o separador de rede do navegador mostram — e entregue isso à IA como “fiz X, esperava Y, aconteceu Z”. Se uma correção piorar as coisas, reverta para a última versão que funcionava em vez de empilhar correções por cima. Não precisa de ler o código para fazer tudo isto bem.

Este guia cobre o ciclo completo, incluindo uma visita rápida às ferramentas de programador do navegador para quem não é programador.

O ciclo de depuração

Cada correção de erro, seja feita por uma pessoa ou por uma IA, segue o mesmo ciclo:

1. Reproduzir — faça o erro acontecer de forma fiável.
2. Observar — recolha a mensagem de erro e o que a aplicação estava a fazer.
3. Descrever — dê à IA passos precisos, o resultado esperado e o resultado real.
4. Corrigir — deixe a IA alterar uma coisa de cada vez.
5. Verificar — repita os passos exatos e confirme que está resolvido, e que nada ao lado se partiu.
6. Reverter se necessário — se ficou pior, desfaça e tente de novo com melhor informação.

A maior parte do tempo desperdiçado em aplicações criadas com IA vem de saltar os passos 1, 2 e 5: dizer “está avariado”, aceitar uma alteração sem a testar e depois pedir outra correção por cima de uma alteração partida.

Passo 1: Reproduzir o erro

Um erro que consegue provocar quando quer está meio resolvido. Tente encontrar o conjunto mais curto de passos que o causa.

Pergunte a si mesmo:

• Acontece sempre? Se só acontecer às vezes, o que é diferente quando acontece — um registo específico, uma ligação lenta, ter a sessão terminada?
• Acontece para todos os utilizadores? Inicie sessão com outra conta. Muitos erros só aparecem para novos utilizadores sem dados, ou para um utilizador com outra função.
• Acontece em todos os dispositivos? Experimente um ecrã com a largura de um telemóvel e outro navegador.
• Começou depois de uma alteração específica? Se funcionava ontem, as últimas alterações são os principais suspeitos.

Escreva os passos numa lista numerada curta. Vai colá-la no prompt mais tarde.

Passo 2: Ler a mensagem de erro

As mensagens de erro intimidam, mas só precisa de algumas partes delas.

Não precisa de a perceber; precisa de a copiar exatamente. “Cannot read properties of undefined (reading 'name')” diz à IA que o código esperava alguns dados (provavelmente uma reserva ou um utilizador) que não estavam lá. Uma paráfrase como “um erro undefined qualquer” perde essa informação.

Alguns erros comuns, traduzidos de forma aproximada:

• Erros undefined / null — o código esperava dados que não chegaram. Muitas vezes, um estado de carregamento ou uma lista vazia que o código não tratou.
• 404 Not Found — a página ou o endereço da API não existe. Muitas vezes, um erro de escrita numa rota ou uma ligação para uma página que foi renomeada.
• 401 Unauthorized / 403 Forbidden — o pedido não tinha sessão iniciada, ou o utilizador não tem permissão para essa ação.
• 500 Internal Server Error — o código do servidor falhou. A razão real está nos registos do servidor, e não no navegador.
• Erros de CORS — o navegador bloqueou um pedido a outro domínio. Normalmente é um problema de configuração do lado do servidor.

Passo 3: Usar as ferramentas de programador do navegador

Todos os navegadores de computador têm ferramentas de programador incorporadas (“devtools”). Mostram o que a página está a fazer por trás das cenas. No Chrome, Edge e Firefox, clique com o botão direito em qualquer ponto da página e escolha Inspecionar, ou prima F12 (Cmd+Option+I num Mac). No Safari, ative primeiro o menu Desenvolver nas definições do Safari.

Só precisa de três separadores.

Consola

O separador Consola lista os erros e as mensagens do código da página. Os erros aparecem a vermelho. Se um botão não fizer nada quando clica nele, a consola mostrará muitas vezes um erro vermelho no momento exato do clique. Copie o texto completo do erro (clique com o botão direito para ver a opção de copiar, na maioria dos navegadores).

Rede

O separador Rede lista cada pedido que a página faz — carregar dados, guardar um formulário, iniciar sessão. Abra-o e depois repita os passos que causam o erro.

• Procure linhas a vermelho ou com um estado de 400 ou superior.
• Clique numa linha que falhou para ver a sua Resposta. Um erro do servidor costuma incluir ali uma mensagem mais útil do que qualquer coisa no ecrã.
• Anote o URL do pedido e o código de estado — “o POST para /api/bookings devolveu 500” é uma frase muito útil para dar à IA.

Ative Preserve log (Manter registo) se o erro envolver um recarregamento ou um redirecionamento da página, para que os pedidos não desapareçam.

Elementos

O separador Elementos (ou Inspetor) mostra a estrutura e os estilos da página. É mais útil para erros de layout: passe o rato sobre um elemento para ver o seu tamanho e espaçamento destacados. Não precisa de editar nada aqui; basta dizer “o rodapé tem 2.000 pixels de largura no telemóvel e empurra a página para o lado”.

Passo 4: Verificar os registos do servidor

Alguns erros acontecem no servidor, onde o navegador não os vê. Um erro 500 no separador de rede é o sinal clássico. Os registos do servidor — o texto que o seu backend produz enquanto está a correr — normalmente contêm o erro real com um rasto de pilha (uma lista das funções que estavam a correr quando falhou).

Onde os encontrar depende da ferramenta. Na maioria dos criadores de aplicações com IA, pode abrir um terminal ou uma vista de registos do projeto, ou simplesmente pedir à IA: “Verifique os registos do servidor para erros do último pedido e diga-me o que falhou.”

Passo 5: Descrever o erro à IA

Coloque o que recolheu nesta forma:

Na página de Reservas, com sessão iniciada como membro: cliquei em Cancelar na aula das 9:00 de amanhã. Esperado: a reserva desaparece e a aula mostra mais um lugar livre. Real: nada muda no ecrã. A consola mostra TypeError: Cannot read properties of undefined (reading 'id') em BookingCard.tsx:31, e o separador de rede mostra que DELETE /api/bookings/123 devolveu 500. Encontre a causa, corrija-a e verifique se cancelar funciona para um membro com uma reserva e com várias.

Porque é que cada parte importa:

• Onde e como quem reduz o problema a um ecrã e a uma função.
• Os passos exatos permitem à IA reproduzi-lo.
• Esperado vs real define o que significa “resolvido”.
• O texto do erro e o pedido que falhou apontam diretamente para a causa.
• “Verifique que…” pede à IA que confirme, e não apenas que edite.

Se a IA já tentou uma correção duas vezes sem sucesso, peça-lhe para explicar antes de alterar seja o que for:

Ainda não altere o código. O que acha que causa isto, e que provas sustentam essa ideia?

Uma teoria errada é fácil de detetar quando está escrita, e muito mais barata de corrigir do que uma correção errada.

Passo 6: Verificar e depois examinar o que está à volta

Quando a IA disser que está corrigido, repita os passos exatos do Passo 1. Depois verifique o que está à volta:

• A mesma ação para outra função de utilizador
• A mesma ação sem dados, e com muitos dados
• Páginas que partilham componentes com a que corrigiu
• Um ecrã com a largura de um telemóvel, se a correção mexeu no layout

As alterações feitas por IA às vezes corrigem um caminho e partem outro discretamente. Dois minutos de verificação agora poupam uma hora confusa mais tarde.

Passo 7: Reverter em vez de acumular

Se uma correção piorou as coisas, ou se já passou três rondas sem progresso, volte atrás. Reverter para a última versão que funcionava e reformular com melhores provas quase sempre é melhor do que pedir uma quarta correção por cima de três erradas. Cada tentativa falhada deixa código para trás, e esse código confunde a tentativa seguinte.

Bons hábitos que tornam a reversão fácil:

• Teste depois de cada alteração, para saber qual alteração partiu alguma coisa.
• Mantenha as alterações pequenas — uma funcionalidade ou correção por mensagem.
• Anote a última versão boa antes de começar algo arriscado.
• Se o código estiver no Git, faça commit das versões que funcionam para poder voltar a elas.

Padrões comuns de erros em aplicações criadas com IA

Quando o problema não é um erro

Alguns “erros” são a IA a construir exatamente o que lhe foi pedido, e a descrição era ambígua. Se a correção que pede é realmente uma mudança de comportamento, diga-o claramente: “Altere para que…”. Se perceber que não tem certeza de qual é o comportamento correto, decida isso primeiro. O nosso guia sobre como escrever prompts para criadores de aplicações com IA explica como especificar regras com clareza. E se estiver a preparar uma aplicação para utilizadores reais, como levar um protótipo de IA para produção cobre as verificações que valem a pena antes do lançamento.

Depurar na Mythex

A Mythex tem ferramentas para cada passo do ciclo:

• Pré-visualização para reproduzir o erro, incluindo uma moldura com tamanho de telemóvel.
• /test faz com que o agente clique pela sua pré-visualização em produção como um utilizador e reporte os fluxos partidos.
• /fix aponta o agente especificamente para as falhas.
• O modo Plano permite ao agente investigar e explicar antes de editar seja o que for.
• Código → terminal mostra os registos do servidor da sua aplicação.
• Reverter para este ponto em qualquer resposta devolve o projeto a esse checkpoint.

Se uma publicação falhar, o diálogo de publicação costuma oferecer Corrigir com IA, que lê o resultado da compilação ou os registos da aplicação. Veja Depurar a sua aplicação e Resolução de problemas de publicação na documentação.

Perguntas