Depuração Assistida por IA
Nesta página
Encontre e corrija erros mais rapidamente
A depuração continua a ser uma arte: compreenda o sintoma, rastreie-o até à causa raiz e corrija-o sem quebrar nada mais. O Codex ajuda nestas três etapas, mas de forma desigual. Na primeira etapa, pouco acrescenta, uma vez que é você quem observa o sintoma e sabe como o sistema deve funcionar. Na segunda, destaca-se, porque rastrear um fluxo de dados através de dez ficheiros é um trabalho de leitura sistemática — exatamente aquilo que uma máquina faz melhor do que um humano cansado. Na terceira, fornece verificação imediata através de testes.
Depure a partir de um erro
O caso mais direto: passe o erro tal como está, sem o reformular ou resumir.
"The test src/api/routes/orders.test.ts fails with:
TypeError: Cannot read properties of undefined
(reading 'id')
at createOrder (src/services/order.service.ts:42)
Find the cause and fix the bug."
O agente encadeia então seis operações: lê o ficheiro de teste para compreender o cenário, abre order.service.ts na linha 42, rastreia o fluxo de dados para encontrar onde o undefined foi introduzido, identifica a causa raiz — parâmetro em falta, erro de tipagem ou outra coisa —, propõe e aplica a correção e, finalmente, volta a executar o teste para verificar. A terceira operação é aquela que lhe teria custado vinte minutos de leitura silenciosa.
Depure comportamentos inesperados
Muitas vezes não há erro algum: o programa faz algo errado silenciosamente. Estes são os erros mais dispendiosos e aqueles em que a forma como formula o seu pedido mais importa.
"The POST /api/orders route creates the order in the
database, but the total is always 0. Product prices are
correct in the products table. Find why the total
calculation fails."
Esta instrução funciona porque define o âmbito: o que funciona, o que não funciona e uma hipótese já excluída, uma vez que os preços na base de dados estão corretos. O Codex rastreia então o fluxo desde o pedido HTTP até à inserção, isola onde o cálculo falha e propõe uma correção. Sem a frase sobre a tabela products, o mais provável é que começasse por verificar exatamente aquilo que você acabou de verificar.
Analise registos de produção
Pode também começar a partir de registos de produção, bastando colar o excerto relevante.
"Here's an excerpt from production logs. The application
intermittently returns 500 on /api/checkout:
[2026-04-01 14:23:01] ERROR: Connection pool exhausted
[2026-04-01 14:23:01] WARN: Query timeout after 30s
[2026-04-01 14:23:02] ERROR: Transaction rollback
Analyze the checkout route code and identify the connection
leak."
O Codex liga as três linhas — pool esgotado, tempo limite da consulta excedido, transação revertida —, conclui que existe uma fuga de ligações à base de dados e procura depois no código os locais onde uma ligação é aberta mas não fechada corretamente. Este é tipicamente um erro que nenhum teste revela, uma vez que só aparece sob carga e desaparece assim que tenta reproduzi-lo localmente.
Depuração por bisseção
Quando o problema é difuso em vez de pontual, peça uma investigação metódica em vez de uma correção rápida.
"The TypeScript build fails with 23 type errors since the
last dependency update. Analyze each error, identify whether
it's an API change in a dependency, and fix the code to be
compatible with the new versions."
O valor desta formulação é que força um diagnóstico erro a erro. Sem a instrução para identificar a origem, a tentação para um agente — tal como para um programador no final do dia — é adicionar any até o compilador se calar, o que transforma vinte e três erros visíveis em vinte e três erros futuros.
Padrões de depuração eficazes
O material que fornece condiciona todo o resto. Cada tipo de sintoma exige evidências específicas a incluir, e omiti-las é como pedir um diagnóstico sem exame.
| Sintoma | Instrução para o Codex |
|---|---|
| Teste falhado | Forneça a mensagem de erro completa + o ficheiro de teste |
| Erro de tipo | Forneça o resultado de tsc --noEmit |
| Erro de execução | Forneça o stack trace + os passos para reproduzir |
| Comportamento incorreto | Descreva o resultado esperado vs. o observado |
| Problema de desempenho | Forneça métricas (tempo de resposta, consultas lentas) |
Previna erros futuros
Um erro corrigido está apenas meio tratado se nada impedir que reapareça noutro local. Portanto, siga sistematicamente a correção com uma tarefa de consolidação, formulada a partir do que acabou de aprender.
"The bug came from an unchecked null userId. Add type
guards in all functions in src/services/ that receive a
userId. Also add a regression test for this case."
Esta segunda tarefa generaliza a lição onde a correção permaneceu local: as guardas cobrem todos os serviços e o teste de regressão garante que este caso específico permanece monitorizado depois de sair do projeto. É esta jogada que distingue uma equipa que corrige erros de uma equipa que reduz o seu backlog.
Pontos-chave
- Forneça ao Codex o máximo de contexto: mensagens de erro, stack traces, registos
- O Codex rastreia o fluxo de dados para encontrar a causa raiz
- Verifica a sua correção voltando a executar os testes automaticamente
- Após corrigir, peça proteções e testes de regressão
- Quanto mais precisas forem as suas instruções, mais rápida será a depuração