Depure com hipóteses testáveis

Descreva a falha antes de propor uma correção

Um pedido útil de depuração informa o comportamento esperado, o observado e o escopo afetado. Inclua a versão, a entrada relevante e o erro. Remova credenciais e registros privados dos logs antes de fornecê-los a uma ferramenta de IA.

“A exportação está quebrada” orienta pouco. Uma descrição melhor é: “A exportação funciona localmente. Em staging, a mesma requisição de um gerente retorna 403 após o último deployment. Outras rotas continuam funcionando.”

Essa descrição não estabelece a causa. Ela identifica diferenças que podem orientar a investigação.

Mantenha várias explicações em consideração

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

Para a falha fictícia de exportação, causas possíveis incluem uma permissão ausente na identidade do serviço, uma alteração no mapeamento de papéis ou uma requisição enviada ao ambiente errado. Cada explicação prevê evidências diferentes.

A tabela é um ponto de partida. Uma resposta 403 pode vir de camadas diferentes. Identifique qual componente a produziu antes de presumir uma falha na autorização da aplicação.

Escolha uma observação segura

Comece com uma observação de baixo custo que possa separar as explicações. Compare a versão implantada e a configuração que não contém segredos. Inspecione o erro relevante e o identificador da requisição. Reproduza o problema em um ambiente de teste autorizado quando possível.

Não conceda permissões amplas apenas para ver se o erro desaparece. Essa ação muda o limite de segurança e pode esconder a permissão específica que falta. Não cole um log inteiro de produção no modelo quando bastarem o erro com os dados sensíveis removidos e o caminho da requisição.

Diga o que enfraqueceria cada hipótese. Isso ajuda o agente a revisar a explicação em vez de defender a primeira resposta.

Altere uma causa de cada vez

Depois que as evidências identificarem uma causa provável, faça uma correção focada. Evite combinar uma alteração de permissão, uma atualização de biblioteca e uma reescrita do handler. Se o sintoma desaparecer, você não saberá qual alteração fez diferença.

Verifique a condição original da falha. Confira também o limite relacionado. Se corrigir o acesso de um gerente, confirme que um usuário não autorizado continua recebendo uma recusa.

Para um defeito recorrente, acrescente uma verificação de regressão na camada capaz de detectá-lo. Um teste unitário não detecta todo erro de configuração de deployment. Algumas falhas exigem uma verificação de integração ou uma verificação controlada após o deployment.

Interrompa tentativas repetidas sem novas evidências

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

Defina um limite de tempo ou de tentativas para investigações incertas. Ao atingir esse limite, informe as evidências atuais, as hipóteses rejeitadas e a questão não resolvida. Esse registro permite que outra pessoa continue sem repetir os mesmos experimentos.

Após a recuperação, registre a causa e a condição que permitiu que ela chegasse ao ambiente afetado. Uma correção remove o defeito imediato. Uma ação posterior útil reduz a chance de a mesma falha voltar.