O que um coding agent precisa que uma CLI informe quando falha

O debuff.jp mediu como 12 CLIs populares em JavaScript falham, usando o mesmo procedimento para todas. O teste rodou em Windows 11 com Node 24.15.0, cada ferramenta na versão atual de 28 de outubro de 2026. O agente só tem dois sinais: o código de saída e o stdout. Dez das 12 rejeitam uma opção inexistente (--frobnicate), mas só ESLint e webpack usam o código 2 para erro de uso e 1 para falha real. Nas outras 8, tsc --noEmit --frobnicate good.ts e tsc --noEmit bad.ts saem ambos com 1, então o agente pode confundir flag errada com erro de tipo.

No modo JSON, 6 das 7 ferramentas entregam um documento parseável quando a execução falha. Quando a ferramenta nem inicia (config inexistente), 5 das 7 não imprimem nada no stdout e jogam texto no stderr. Só o npm responde em JSON, com código como E404. Prettier e Rollup rodam mesmo com opção inválida e só avisam. Vitest e Vite mostram stack trace do parser de argumentos, e o launcher do esbuild no Windows também. Nenhuma ferramenta informa se tentar de novo adiantaria. O próprio debuff, desde a 0.20, adota um contrato com code estável e transient: true para indicar retentativa. A 0.21 acrescentou o código nothing_to_run. O estudo cobre uma plataforma, um comando por ferramenta e só config ausente como falha de inicialização.

A cobertura anterior do CEVIU tratava o tema em nível mais geral. Em 25 de agosto de 2026, a matéria "A Usabilidade do Agente: Sinalizando Falhas em Sistemas de IA" defendia um canal de exceção para melhorar a experiência do agente. Agora há medição concreta em CLIs reais, com números de exit code e JSON.

Para quem mantém uma CLI que agentes executam, a leitura é prática: código de saída separado para erro de uso, um documento JSON único mesmo quando a ferramenta não sobe e um campo dizendo se vale tentar de novo. Isso poupa o agente de caçar bug em código sano ou de entrar em loop com config ausente.