Depurar com hipóteses que se podem testar

Descreva a falha antes de propor uma correção

Um pedido de depuração útil indica o comportamento esperado, o comportamento observado e o âmbito afetado. Inclua a versão, os dados de entrada relevantes e o erro. Remova credenciais e registos privados dos logs antes de os fornecer a uma ferramenta de IA.

«O export não funciona» dá pouca orientação. Uma descrição melhor é: «O export funciona localmente. Em staging, o mesmo pedido do gestor devolve 403 após o último deployment. As outras rotas continuam a funcionar.»

Esta descrição não estabelece a causa. Identifica diferenças que podem orientar a investigação.

Mantenha várias explicações em aberto

Peça ao agente um pequeno conjunto de causas plausíveis e as evidências de cada uma. Não lhe peça que se comprometa com a primeira explicação convincente.

Na falha fictícia do export, as causas possíveis incluem a falta de uma permissão da identidade de serviço, uma alteração do mapeamento de funções ou um pedido enviado para o ambiente errado. Cada explicação prevê evidências diferentes.

A tabela é um ponto de partida. Uma resposta 403 pode ter origem em diferentes camadas. Identifique o componente que a produziu antes de presumir que a autorização da aplicação falhou.

Escolha uma observação segura

Comece por uma observação que permita distinguir explicações com pouco custo. Compare a versão instalada e a configuração que não contém segredos. Examine o erro relevante e o identificador do pedido. Sempre que possível, reproduza o problema num ambiente de teste autorizado.

Não conceda permissões amplas apenas para ver se o erro desaparece. Essa ação altera a fronteira de segurança e pode ocultar a permissão que realmente falta. Não cole um log de produção completo no modelo quando basta o erro com os dados sensíveis removidos e o percurso do pedido.

Indique o que tornaria cada hipótese menos provável. Isto ajuda o agente a rever a explicação em vez de defender a primeira resposta.

Altere uma causa de cada vez

Depois de as evidências identificarem uma causa provável, faça uma correção específica. Evite juntar uma alteração de permissões, a atualização de uma biblioteca e a reescrita do componente que processa o pedido. Se o sintoma desaparecer, não saberá qual das alterações teve efeito.

Verifique a condição que causou a falha original. Verifique também o limite adjacente. Se corrigir o acesso de um gestor, confirme que um utilizador não autorizado continua a receber uma recusa.

Para um defeito recorrente, acrescente uma verificação de regressão na camada que o pode detetar. Um teste unitário não consegue detetar todos os erros de configuração do deployment. Algumas falhas exigem uma verificação de integração ou uma verificação controlada após o deployment.

Pare as tentativas repetidas sem novas evidências

Um agente pode gerar muitas variantes de uma correção. Mais tentativas não melhoram necessariamente o diagnóstico. Se a mesma falha se repetir, pergunte que nova observação a próxima tentativa irá fornecer.

Defina um limite de tempo ou de tentativas para uma investigação incerta. Ao atingir esse limite, apresente as evidências atuais, as hipóteses rejeitadas e a questão por resolver. Este registo permite que outra pessoa continue sem repetir as mesmas experiências.

Após a recuperação, registe a causa e a condição que permitiu que o defeito chegasse ao ambiente afetado. Uma correção elimina o defeito imediato. Um seguimento útil reduz a probabilidade de a mesma falha voltar a ocorrer.