Como revisar dependências sugeridas por agentes de código

Quando um agente de código sugere uma biblioteca, a revisão não deve perguntar apenas se o pull request ficou menor ou se os testes locais passaram. Dependências de código gerado por inteligência artificial precisam ser tratadas como decisão de arquitetura, manutenção e risco. A inclusão só deve avançar quando a equipe consegue justificar por que o pacote precisa entrar agora e como ele será verificado depois.

A entrada de uma dependência muda a superfície técnica

Uma dependência raramente entra sozinha. Ela traz uma origem, uma licença, um histórico de versões, uma forma de manutenção, possíveis dependências indiretas e uma superfície nova dentro do produto. Há hipóteses plausíveis para a sugestão do agente, como conveniência local ou aderência ao contexto de código recebido. Mas a revisão não deve assumir que isso torna a escolha adequada para o sistema.

A diferença parece pequena no pull request. Uma linha no arquivo de configuração. Um import no começo do arquivo. Algumas chamadas prontas no lugar de uma implementação interna. Só que essa linha passa a participar do build, dos testes, do deploy, da política de segurança e da rotina de atualização.

Esse é o ponto que lideranças de engenharia, qualidade e produto precisam deixar explícito: revisar bibliotecas sugeridas por IA não é desconfiança genérica contra automação. É governança de código gerado por IA aplicada ao lugar onde o custo futuro costuma ficar escondido.

A pergunta prática é simples: se o agente não tivesse sugerido essa biblioteca, a equipe ainda escolheria incluí-la?

Se a resposta for “não sabemos”, o pull request ainda não está pronto.

Esse cuidado conversa com uma discussão mais ampla sobre qualidade de software com IA, mas aqui o foco é mais estreito: decidir se uma dependência específica merece entrar no produto.

Primeiro critério: a dependência precisa resolver algo necessário

A primeira revisão não é de segurança. É de necessidade.

Antes de verificar procedência, licença ou compatibilidade, a equipe deve perguntar se aquele pacote precisa existir no sistema. Uma biblioteca pode ser tecnicamente correta e, ainda assim, ser uma escolha ruim porque resolve um problema pequeno demais para justificar manutenção recorrente.

A revisão deve comparar pelo menos quatro alternativas:

recurso nativo da linguagem ou do framework;
biblioteca já aprovada e presente no projeto;
pequena implementação interna, com escopo claro;
remoção ou simplificação da funcionalidade acessória.

A dependência tende a fazer sentido quando reduz complexidade real, evita uma implementação delicada ou concentra um comportamento que seria caro manter internamente. Ela tende a ser fraca quando apenas economiza poucas linhas, mascara uma decisão de produto mal definida ou importa uma solução ampla para uma necessidade estreita.

Um critério operacional ajuda: se a justificativa do pull request só diz “o agente sugeriu” ou “ficou mais simples”, a revisão deve pedir uma comparação. Não precisa virar um documento longo. Pode ser um parágrafo:

“A biblioteca foi proposta para resolver X. Avaliamos Y, que já existe no projeto, mas não cobre Z. Implementação interna exigiria manter A e B. Por isso, a inclusão é aceitável se a procedência e os testes forem aprovados.”

Esse parágrafo muda a conversa. A equipe deixa de aprovar uma sugestão e passa a aprovar uma decisão.

Segundo critério: a procedência do pacote precisa ser verificável

A orientação da OWASP para a cadeia de suprimentos de software recomenda avaliar componentes e fornecedores antes da inclusão. Entre os critérios estão manutenção ativa, tratamento de vulnerabilidades e compatibilidade do uso pretendido com a licença. A orientação também inclui inventário de dependências, monitoramento de vulnerabilidades e controle de versões.

Procedência não elimina risco, mas permite revisar a escolha com evidências mínimas.

Na revisão de dependências de código gerado por IA, o pacote precisa ter origem identificável. A equipe deve conseguir verificar o repositório, os mantenedores, a licença, o histórico de versões e sinais mínimos de manutenção. Também vale observar nomes muito parecidos com pacotes conhecidos, mudanças recentes de propriedade e dependências indiretas difíceis de entender.

Nada disso garante segurança absoluta. Para fins desta revisão, trate componentes, ferramentas e fornecedores envolvidos no build como itens que exigem verificação de procedência. O objetivo é impedir que uma biblioteca entre apenas porque apareceu em uma resposta convincente do agente.

Um bom comentário de revisão pode pedir evidências específicas:

qual é a origem oficial do pacote;
onde está o código fonte, quando aplicável;
qual licença rege o uso;
quando ocorreram as versões recentes;
quais dependências indiretas serão adicionadas;
se existe pacote interno ou já aprovado com função parecida.

Se essas perguntas parecem burocráticas para uma mudança pequena, talvez a dependência seja pequena demais para justificar a inclusão. Conveniência local não deve criar obrigação permanente para a equipe.

A revisão também precisa evitar um erro comum: confundir presença em exemplos públicos com procedência confiável. Não presuma que nomes, combinações e APIs sugeridos pelo agente estão corretos sem verificação. O pacote deve existir, ser o pacote certo e fazer sentido para aquele produto.

Terceiro critério: o encaixe técnico não pode criar dívida invisível

Mesmo quando a biblioteca é necessária e verificável, ainda falta avaliar encaixe técnico.

A pergunta aqui não é “funciona na máquina de quem abriu o pull request?”. A pergunta é: funciona no ambiente do produto, com as versões, políticas e restrições que a equipe realmente opera?

A revisão deve observar compatibilidade com runtime, linguagem, framework, empacotamento, política de licenças, padrões internos, build, testes e deploy. Também deve considerar o tamanho da superfície importada. Na revisão, vale tratar como risco a importação de uma cadeia extensa para uma necessidade simples.

Na revisão, trate como dívida invisível o que não aparece na história de usuário, mas pode afetar atualização, versões, alertas, ambiente de execução ou remoção futura do pacote.

Esse ponto é especialmente relevante em revisão de pull request com IA, porque a sugestão do agente depende do contexto que recebeu. Se esse contexto não inclui a política de dependências do time, a estratégia de versionamento ou as restrições de deploy, a sugestão pode ser coerente no código e errada na operação.

Uma forma objetiva de revisar o encaixe é pedir que o pull request declare o limite de uso:

onde a biblioteca será chamada;
quais funções dela serão usadas;
quais partes não devem ser usadas;
qual versão será fixada ou controlada;
qual módulo interno ficará responsável por isolar o pacote.

Isolar a dependência por trás de uma função ou módulo interno costuma ser mais prudente do que espalhar chamadas diretas pelo produto. Se a equipe precisar substituir a biblioteca depois, a troca fica menos espalhada. Não é uma regra universal, mas é um bom padrão quando a dependência entra para resolver um comportamento específico.

Quarto critério: o comportamento relevante precisa ser testável

Testar a dependência não significa testar a biblioteca inteira. Significa testar o comportamento do produto que passa a depender dela.

Se o pacote formata dados, os testes devem cobrir os formatos que importam para o produto. Se valida entrada de usuário, os testes devem cobrir entradas aceitas, rejeitadas e casos ambíguos. Se altera serialização, autenticação, leitura de arquivo ou integração com outro serviço, os testes devem verificar o efeito no fluxo real.

O DORA recomenda testes ao longo do desenvolvimento, combinando automação e atividades manuais, como exploração e usabilidade, além de manter e revisar as suítes de teste. Essa recomendação não resolve a decisão sobre dependências, mas reforça uma disciplina útil: qualidade não deve ser empurrada para uma etapa posterior.

No caso de bibliotecas sugeridas por IA, a equipe deve desconfiar de duas evidências fracas:

“o agente disse que terminou”;
“passou uma vez no teste local”.

A Anthropic distingue a trajetória de execução do agente do resultado efetivo no ambiente. Uma mensagem dizendo que a tarefa terminou não basta para comprovar o resultado. Essa distinção é valiosa aqui: o agente pode ter concluído a alteração, mas a equipe ainda precisa verificar o efeito da dependência no produto.

O critério de aceite deve ser escrito em termos de comportamento observável. Por exemplo: “ao receber entradas com pontuação, espaços e variações comuns, o formulário deve normalizar o valor antes de salvar”. Esse critério é melhor do que “usar a biblioteca X para normalização”. A biblioteca é meio. O comportamento é o compromisso.

Para aprofundar a parte de teste sem misturar assuntos, vale conectar essa revisão ao processo descrito em como testar código gerado por IA. A pergunta deste artigo, porém, continua sendo uma só: a dependência proposta permite verificar o que realmente importa?

Quinto critério: precisa existir caminho de remoção ou substituição

A aprovação de uma dependência deve prever cenários em que ela deixe de servir ao produto, como mudança de licença, quebra de compatibilidade, abandono de manutenção, comportamento indesejado ou simplificação futura da funcionalidade.

Por isso, a aprovação deve incluir um plano simples de reversão ou substituição. Não precisa ser um plano extenso. Precisa responder:

quem acompanha atualizações e alertas relevantes;
como a versão será controlada;
onde a biblioteca está encapsulada;
que testes indicam quebra de comportamento;
qual alternativa existe se for necessário remover o pacote.

O capítulo do Google SRE sobre lançamentos graduais trata da avaliação de uma mudança em uma parcela do tráfego antes de ampliar a exposição e distingue disponibilizar código de ativar funcionalidades. Para dependências, a aplicação é cuidadosa: quando a mudança afeta comportamento visível ou risco operacional, pode fazer sentido separar inclusão técnica, ativação e ampliação de uso por configuração.

Isso não será necessário para toda biblioteca pequena. Mas a distinção é útil. Fazer merge do código não precisa significar expor imediatamente todo o produto ao novo comportamento.

O ponto central é responsabilidade. Dependência sem dono técnico tende a ficar fora da rotina de revisão até gerar manutenção não planejada.

Checklist de revisão de dependência sugerida por agente de código

Use este checklist como filtro antes de aprovar a inclusão. Ele não promete eliminar riscos. Ele torna a decisão mais explícita e verificável.

Necessidade

A dependência resolve um problema que não pode ser atendido por código nativo, biblioteca já aprovada ou pequena implementação interna?

Aprovar quando há justificativa explícita para não usar alternativa existente. Recusar quando a dependência apenas reduz algumas linhas de código sem reduzir risco ou complexidade.

Procedência

A origem do pacote, os mantenedores, a licença, o repositório e o histórico de versões são verificáveis?

Aprovar quando a equipe consegue identificar fonte, licença e sinais mínimos de manutenção. Recusar quando o pacote tem origem confusa, nome parecido com pacote conhecido ou manutenção incerta.

Escopo

A biblioteca faz apenas o que o produto precisa ou traz funcionalidades e dependências indiretas desproporcionais?

Aprovar quando o escopo importado é compatível com o problema resolvido. Recusar quando uma necessidade pequena passa a depender de uma cadeia ampla e difícil de auditar.

Teste

O comportamento crítico da dependência pode ser verificado por testes automatizados e revisão manual quando necessário?

Aprovar quando há casos de teste para os fluxos que podem quebrar o produto. Recusar quando a equipe aceita a biblioteca porque o agente disse que a tarefa terminou ou porque o teste local passou uma vez.

Manutenção

Está claro quem acompanha atualizações, alertas, quebra de compatibilidade e possível remoção?

Aprovar quando a dependência tem dono técnico e regra de revisão. Recusar quando a biblioteca entra sem responsável, sem versão controlada ou sem caminho de substituição.

Esse checklist também ajuda a separar esta pauta de uma revisão geral de código. Para discutir legibilidade, intenção, cobertura e coerência do pull request como um todo, o artigo sobre como revisar código gerado por IA é o caminho mais adequado.

Exemplo fictício: quando recusar uma biblioteca sugerida pelo agente

Imagine um caso fictício. Um agente recebe a tarefa de ajustar um formulário de cadastro para aceitar CPF e CNPJ digitados com ou sem pontuação. Ele sugere uma biblioteca externa de formatação e validação. O pull request fica curto. Os testes locais passam. A mudança parece inofensiva.

Na revisão, a equipe aplica os critérios.

Primeiro, necessidade. O projeto já tem um utilitário interno para normalizar documentos, usado em outros formulários. Ele não cobre uma variação específica de espaços antes e depois do valor, mas o ajuste seria pequeno e testável. A nova biblioteca, portanto, não resolve um problema que o código existente seja incapaz de resolver.

Segundo, procedência. A origem do pacote é verificável, mas a revisão encontra dependências indiretas que não seriam usadas pelo produto. Não há evidência de que esse escopo adicional traga benefício para a tarefa.

Terceiro, encaixe técnico. A biblioteca oferece formatação, validação e máscaras de entrada. O produto precisa apenas normalizar o valor antes de salvar. Importar o pacote inteiro aumentaria a superfície de manutenção para uma necessidade estreita.

Quarto, teste. Os cenários relevantes podem ser cobertos com testes automatizados sobre o utilitário interno: entrada com pontuação, sem pontuação, com espaços, com caracteres inválidos e com campos vazios. Não é necessário depender da biblioteca para tornar o comportamento verificável.

Quinto, manutenção. Como já existe módulo interno responsável por normalização, incluir uma nova biblioteca criaria dois caminhos para resolver o mesmo problema.

A decisão, nesse exemplo fictício, é recusar a dependência sugerida pelo agente, ajustar o utilitário existente e registrar no pull request a regra de aceite: o formulário deve normalizar documentos nos formatos previstos antes de salvar, sem introduzir nova dependência externa. O efeito esperado é reduzir superfície de manutenção, mas isso deve ser acompanhado nos testes e nas revisões seguintes, não presumido como resultado automático.

Essa recusa não é resistência à IA. É uma equipe usando IA sem transferir a ela a autoridade de mudar a arquitetura do produto.

Antes de incluir uma dependência sugerida por agente de código, exija uma justificativa curta com quatro respostas: qual problema ela resolve, por que o código existente não resolve, qual é a procedência do pacote e quem ficará responsável por atualização, remoção ou substituição.

Se quiser discutir essa decisão no contexto da sua empresa, converse com a dooop.

Leituras para continuar

Fontes

Para continuar esta leitura

Como investigar queda de qualidade após mudar um modelo

PRÓXIMA DECISÃO

Conversar sobre a aplicação na empresa

Conversa sobre o contexto da empresa de software

Conteúdo de dooop. O cadastro permite relacionar esta pauta à jornada do leitor e acompanhar o interesse pelo tema.