A Saída de uma Ferramenta É o Próximo Prompt: Desenhando Interfaces para Agentes Leitores

Uma ferramenta roda. Imprime algo. Um humano olha a saída, decide o próximo passo, e segue em frente. Esse foi o contrato implícito da caixa de ferramentas Unix por meio século. A estrutura era conveniência. Prosa, cor, emoji, linha de resumo no rodapé: tudo bem, porque o leitor do outro lado era você.

Esse contrato se rompeu em silêncio no momento em que começamos a colocar agentes dentro de pipelines. O leitor deixou de ser uma pessoa que pode apertar os olhos. É um modelo cuja próxima ação será condicionada quase inteiramente pelos bytes que você acabou de emitir. A saída da ferramenta não é um relatório. É o prompt para o próximo turno.

Aprendemos isso no susto reconstruindo um auditor de acentos em português que tínhamos escrito um ano atrás. O conserto demorou mais do que esperávamos, não porque a linguística fosse difícil, mas porque tivemos que mudar a unidade de correção. A unidade antiga era “a palavra foi corrigida”. A unidade nova é “o agente recebeu a decisão certa”.

O Que Quebra Quando o Leitor Muda

O auditor original era um mapa de substituições dirigido por dicionário. Varria texto em português, encontrava formas não acentuadas de palavras acentuadas comuns, e reescrevia in loco. Para um autor humano, isso é ganho de produtividade. Você digitou voce e quis dizer você, a ferramenta corrigiu, você seguiu. Os poucos falsos positivos, como a forma imperativa de um verbo que coincide com um substantivo, eram capturados pelos seus olhos na releitura.

Três incidentes em produção em seis semanas nos contaram que esse loop não era mais o loop que estávamos rodando. O autor não era mais humano. Era um pipeline de conteúdo. Um agente de redação escrevia o texto, o auditor reescrevia pedaços em silêncio, e o próximo agente da cadeia recebia a versão modificada como prompt para a próxima etapa. A reescrita ruim virava entrada da próxima decisão. Ninguém relia o diff porque não havia humano na cadeira em que o diff seria relido.

As falhas se concentravam em três palavras. Esta, o pronome demonstrativo, vinha sendo auto-corrigido para Está, o verbo. Continua, o verbo na terceira pessoa, era promovido a uma forma de empréstimo latino que não existe no português moderno. Secretaria, substantivo, virava Secretária, outro substantivo. Cada correção estava errada para aquele contexto, mas o dicionário não conhecia contexto. Conhecia apenas formas de palavra.

Você pode remendar um dicionário. Você não pode remendar a suposição de que o leitor vai capturar seus erros.

A Nova Unidade de Correção

A reconstrução mudou exatamente uma coisa: o que a ferramenta diz sobre si mesma. O dicionário ficou. As regras ortográficas ficaram. A nova ferramenta produz uma classificação de três vias para cada candidata a mudança.

FIX. Correção inequívoca. Uma palavra que tem exatamente uma forma canônica, sem alternativas dependentes de contexto, sem uso legítimo plausível da versão não acentuada. A ferramenta aplica essas correções em silêncio e registra. voce para você. nao para não. Território clássico de Hunspell.

REVIEW. Ambígua. A candidata tem mais de uma forma alvo plausível, ou a heurística livre de contexto não consegue decidir. A ferramenta não corrige. Ela traz à tona a palavra original, as correções candidatas, e contexto suficiente em volta para o agente que lê o relatório tomar a decisão. Esta no meio da frase sem verbo antecedente é provavelmente o demonstrativo. Esta depois de uma vírgula numa oração que já tem sujeito é provavelmente o verbo. Mostre as duas opções, devolva a decisão.

SKIP. Não é problema nosso. Empréstimos do inglês, nomes próprios, marcas, termos técnicos que não têm equivalente acentuado em português. A ferramenta ignora de propósito e diz que ignorou, para o próximo agente não desperdiçar um turno perguntando por que medium ou dashboard não foi sinalizado.

A taxonomia não é nova como linguística. É nova como desenho de interface. As três categorias mapeiam diretamente para as três coisas que um agente pode fazer com um veredicto: agir sobre ele, raciocinar a partir dele, ou seguir em frente. Uma ferramenta de duas categorias (“corrigido” versus “não corrigido”) força o próximo agente a interpretar prosa para descobrir que tipo de “não corrigido” está olhando. Uma ferramenta de três categorias responde essa pergunta no próprio schema.

Códigos de Saída Carregam a Meta-Decisão

A outra peça da reconstrução foi o contrato de saída. A ferramenta antiga saía com zero em sucesso e não-zero em falha de parse. Isso não deixava espaço para “rodou bem, mas você precisa olhar isso”.

O novo contrato usa três códigos.

0 significa siga. Tudo que a ferramenta quis corrigir foi corrigido, e não há entradas de REVIEW. O pipeline continua.

10 significa leia o relatório e decida. A ferramenta rodou, aplicou as entradas FIX, e produziu uma ou mais entradas REVIEW sobre as quais o próximo agente precisa agir antes do pipeline continuar. O orquestrador para no 10, mostra o relatório, e espera a decisão.

2 está reservado para condições reais de erro: entrada quebrada, configuração ausente, dicionário não encontrado.

Três códigos, uma meta-decisão por código. O orquestrador não precisa interpretar o stdout da ferramenta para saber o que fazer em seguida. O número de saída é o sinal de roteamento. A prosa fica para os humanos que eventualmente lerão o log. A decisão de máquina vive no inteiro.

Esse é o mesmo padrão que torna o grep composável. grep sai com zero quando encontrou correspondência, um quando não encontrou, dois em erro. Pipelines ramificam no inteiro. O texto é para você. O inteiro é para o shell.

O Que Encontramos ao Rodar a Nova Ferramenta no Arquivo

Auditamos 425 artigos existentes em português com o auditor reconstruído. A primeira passada sinalizou 266 arquivos. Esse número nos assustou até lermos os relatórios. A maior parte das sinalizações eram entradas de REVIEW sobre palavras TitleCase no meio da frase, que a heurística estava conservadoramente levando para revisão em vez de auto-corrigir.

Apertamos três proteções. Uma lista de stopwords para termos em inglês inequívocos que tínhamos tratado como candidatos a português. Uma lista de palavras ambíguas para empréstimos como medium e dashboard que têm tanto leitura em inglês quanto em português. Uma heurística de TitleCase que envia palavras capitalizadas no meio da frase para REVIEW em vez de auto-FIX, na teoria de que capitalização no meio de uma frase é quase sempre sinal de ênfase intencional, marca ou nome próprio.

Depois das três proteções, a taxa de falsos positivos numa amostra de 22 arquivos com erros reais confirmados foi a zero. Não baixa. Zero. A ferramenta agora corrige apenas o que tem certeza, e traz à tona tudo o mais para decisão.

Esse número importa menos do que a forma do trabalho que o produziu. Não escrevemos mais regras. Escrevemos menos regras com mais honestidade sobre quais regras pertenciam ao balde FIX e quais pertenciam ao REVIEW.

Por Que Isso Generaliza Além do Português

O auditor de acentos é um exemplo pequeno de uma categoria. Qualquer ferramenta cujo consumidor primário é um agente dentro de um pipeline enfrenta as mesmas três pressões.

Auto-correções silenciosas se acumulam. Se sua ferramenta muda algo e não traz à tona a mudança numa estrutura que a próxima etapa pode ler, a próxima etapa trabalha a partir da entrada errada. Um corretor ortográfico que reescreve palavras válidas dentro de um rascunho é o mesmo formato de falha que um linter que auto-formata e apaga uma diferença significativa de espaço em branco, ou um sanitizador de conteúdo que remove uma atribuição porque ela parecia um placeholder.

Ambiguidade precisa de endereço. Ferramentas que colapsam “talvez” em “sim” ou “não” forçam o consumidor a duvidar de toda saída. Um agente que não confia numa ferramenta deixa de usá-la. Uma categoria REVIEW não é confissão de fraqueza. É a única resposta honesta para os casos em que a ferramenta não consegue decidir sozinha.

Códigos de saída são baratos, prosa é cara. Um inteiro em $? custa nada para ler. Um parágrafo de explicação custa tokens, tempo, e uma chance não trivial de leitura errada. Mova toda decisão que o orquestrador precisa tomar para o código de saída. Reserve a prosa para os humanos que eventualmente auditarão o que as máquinas fizeram.

Faça Isso Agora

Escolha uma ferramenta do seu pipeline cujo consumidor primário hoje é um agente. Abra o código fonte. Encontre cada lugar em que a ferramenta produz saída que uma etapa seguinte vai ler.

Faça três perguntas, nesta ordem.

O que essa ferramenta muda em silêncio que um humano teria pegado na releitura? Faça uma lista. Cada entrada é candidata a promoção de FIX para REVIEW.

O que essa ferramenta colapsa de ambíguo numa resposta binária? Cada colapso é candidato à categoria REVIEW. O custo de adicionar a categoria é pequeno. O custo da resposta binária errada fluindo para a próxima etapa é grande.

Que decisão seu orquestrador toma hoje interpretando o stdout da ferramenta? Mova essa decisão para o código de saída. Uma mudança de duas linhas na ferramenta remove um match frágil de string de cada pipeline que a chama.

Os times que vencerão a próxima fase de operação de agentes não serão os com mais ferramentas. Serão aqueles cujas ferramentas falam de forma honesta com os agentes que as leem.

Fontes

LibreOffice / Raimundo Moura. “Dicionário pt_BR Hunspell.” Mantido desde 2006.
zverok / GitHub. “spylls, Hunspell em Python puro.” 2020-2024.
A Victorino. “Cinco Níveis de Contenção do Bash.” Maio de 2026.

A Victorino ajuda lideranças de engenharia a desenhar ferramentas que conversam de forma limpa com os agentes que as operam: contato@victorino.com.br | www.victorino.com.br