Estou acostumado a contribuir com pull requests e nunca gostei muito de abrir issues. Mesmo assim, considero usar o meu agente para escrever uma descrição detalhada do bug, acompanhada de um teste que permita reproduzi-lo, quando o mantenedor prefere implementar a correção com os próprios agentes.
Você continua investigando a falha, mas precisa deixar registrado o que descobriu para que o mantenedor consiga repetir o erro. Isso exige explicar o comportamento observado sem transformar uma suspeita sobre a causa em uma conclusão. No meu trabalho com IA, tenho descrito melhor as tarefas justamente para reduzir as tentativas seguidas de correção.
Direto ao ponto
Uma issue útil mostra como repetir a falha na versão utilizada, informa o resultado observado e explica o que você esperava. O agente pode auxiliar na preparação do exemplo, mas você precisa executá-lo e conferir o relato. O mantenedor deve conseguir investigar o problema a partir dessa descrição.
Mostre a entrada e o retorno que você recebeu
Imagine uma biblioteca de formatação numérica que recebe o número 12.5, com configuração de idioma pt-BR e duas casas decimais. Sua aplicação espera o texto 12,50, mas recebe 12.50. Neste exemplo fictício, a configuração de idioma faz parte da reprodução porque determina qual separador decimal você espera receber.
Uma mensagem dizendo que a formatação está errada não informa qual parte do comportamento precisa ser investigada. O relato ganha precisão quando você mostra o valor enviado, a configuração utilizada e o texto devolvido, preservando a diferença entre ponto e vírgula como separador decimal.
Você pode apresentar a reprodução assim, acompanhada da versão e do exemplo executável:
Com o idioma
pt-BRe duas casas decimais, a entrada numérica12.5retorna o texto12.50. Eu esperava12,50, com vírgula como separador. O comportamento continua no exemplo reduzido, usando a mesma configuração da aplicação.
A mensagem descreve o que foi observado sem concluir que uma função específica precisa ser reescrita. Com esse relato, o mantenedor pode conferir se a configuração foi aplicada e comparar o retorno com o formato documentado pela biblioteca.
Preserve o que faz o exemplo falhar
Um projeto completo pode conter configurações e dependências que dificultam encontrar a causa. Você pode reduzir a reprodução a uma chamada da biblioteca, mantendo o idioma, o número de casas decimais e a versão instalada.
Retirar a configuração de idioma para simplificar o exemplo pode mudar o resultado. Nesse caso, a reprodução já não representa a falha original. Execute o exemplo reduzido e compare o retorno com o que apareceu na aplicação, verificando se a diferença continua presente.
O repertório técnico no desenvolvimento com IA participa dessa investigação. Ao orientar o agente, você precisa reconhecer quais configurações podem interferir na resposta, em vez de aceitar uma simplificação que faz o problema desaparecer.
Uma versão diferente da biblioteca também pode produzir outro resultado. Informe qual versão foi testada e mantenha explícito o que não conseguiu conferir. Isso evita apresentar um comportamento observado numa instalação como se ele tivesse sido verificado em todas as versões.
O resultado esperado precisa de uma referência
A expectativa de receber 12,50 pode vir da documentação da biblioteca, de um teste existente ou do comportamento de uma versão anterior. Mostrar essa referência permite discutir por que o retorno recebido não atende ao que o projeto oferece.
A biblioteca talvez formate números com ponto independentemente do idioma usado pela aplicação. Nesse caso, a sua necessidade pode exigir uma configuração diferente ou uma funcionalidade nova. O fato de o resultado não atender à aplicação não comprova, sozinho, um defeito no projeto.
Discutir o retorno esperado na issue faz sentido para mim. Você pode descobrir que a biblioteca mantém aquele comportamento de propósito e discutir com o mantenedor uma alternativa para a sua aplicação.
No trabalho de revisão das contribuições, o mantenedor também precisa comparar o teste com o comportamento documentado. Um teste escrito para esperar uma vírgula não comprova que a biblioteca deveria retornar esse separador com a configuração utilizada.
O agente pode preparar o relato que você vai conferir
Você pode usar o agente para reduzir o exemplo e redigir os passos de reprodução. A descrição final precisa corresponder ao teste executado, incluindo mensagens de erro e limitações que apareceram durante a investigação.
Uma causa sugerida pela IA pode ser apresentada como possibilidade a investigar. Ela não deve substituir o retorno observado nem aparecer como explicação confirmada quando você ainda não verificou a relação entre a função e a falha.
Logs e capturas de tela complementam o exemplo quando mostram a configuração aplicada ou o erro recebido. Remova credenciais e informações pessoais antes do envio, preservando as mensagens necessárias para repetir e compreender o comportamento.
Na formação de Vibe Coding, o desenvolvimento com agentes é o assunto de estudo. O plano IA Makers reúne esse acesso. Ao aplicar a IA na preparação de uma issue, a execução do exemplo permite conferir a relação entre o relato e o comportamento da biblioteca.
A investigação continua nos comentários das issues
O mantenedor pode solicitar a execução com outra configuração ou informar que a falha já foi corrigida. Ao responder, acrescente a versão testada e o retorno da nova verificação, preservando o caso original para permitir a comparação.
O mantenedor pode identificar que a configuração de idioma não chegou à função, em vez de encontrar um defeito na formatação. O exemplo que você enviou continua permitindo conferir a chamada e orientar a correção na sua aplicação.
Para investigar uma falha do seu projeto com orientação técnica ao vivo, você pode usar o Desenvolvimento Colaborativo da Dev Side Studio. Você opera o editor e o terminal enquanto trabalhamos para compreender o comportamento e conduzir a correção.
Na próxima issue, execute novamente o exemplo que pretende compartilhar e compare o relato com o retorno recebido. Continuo a discussão sobre essas formas de colaborar no Diário do VibeCoder sobre pull requests e issues. Para acompanhar outros conteúdos sobre desenvolvimento, consulte o catálogo de vídeos da Promovaweb.
