Habr AI mostra como preparar uma entrada estruturada para um agente de IA em vez de um caderno de requisitos bruto

O Habr AI publicou uma análise detalhada sobre o que exatamente deve entrar em um agente de IA quando a tarefa é verificar requisitos técnicos, e não apenas resumi-los. A ideia central: em vez da especificação inteira, o agente recebe um conjunto de requisitos atômicos na forma de passaportes em JSON.

Por que só a especificação não basta

A autora começa por um problema conhecido de quase todo mundo que já tentou entregar um documento grande inteiro a uma rede neural. Quando o modelo recebe uma especificação de várias páginas sem preparação prévia, ele perde o foco, mistura requisitos de seções diferentes e devolve observações genéricas demais. No fim, o sistema pode até notar imprecisões isoladas, mas tem dificuldade para explicar qual item exatamente está ruim, por que está ruim e o que precisa ser corrigido.

Por isso, o documento é primeiro dividido em requisitos individuais: uma ação, uma regra ou uma restrição por fragmento. Para não perder o contexto nessa divisão, cada elemento ganha campos como `parent_section` e `parent_object`, e itens logicamente relacionados são marcados como `linked`. Isso é importante quando vários requisitos precisam ser verificados em conjunto: por exemplo, quando o sistema deve enviar uma notificação tanto por e-mail quanto pelo Telegram, e não apenas por um dos dois canais.

O passaporte do requisito

O passo seguinte é transformar a redação humana em um conjunto de atributos com os quais o classificador consegue trabalhar. Nesse esquema, o LLM não atua como juiz final nem tenta "entender tudo". Seu papel é bem mais restrito: ele extrai sinais estruturados do texto e os organiza em JSON. Isso dá controle ao processo: os atributos podem ser conferidos, comparados e, se necessário, corrigidos no pós-processamento. Nas palavras da autora,

"o agente não trabalha com texto, mas com estruturas como essas".

O artigo descreve seis atributos básicos que sustentam esse passaporte. Em vez de uma avaliação abstrata de qualidade, o modelo procura sinais concretos: números, palavras vagas, exceções, limites e participantes explícitos do cenário. Na prática, o passaporte transforma uma frase como "o usuário deve configurar o relatório de forma flexível" em um conjunto claro de flags, que mostra de imediato o que falta ao requisito. É essa interpretabilidade que diferencia o esquema de simplesmente pedir ao modelo que avalie o texto inteiro.

• `has_numbers` — se o requisito contém números, limites, datas e outros parâmetros concretos
• `stopword_score` — o quanto a redação é vaga por causa de palavras como "flexível", "prático" ou "rápido"
• `has_negative_keywords` — se exceções e erros estão descritos
• `boundary_conditions_mentioned` — se valores vazios, máximos, mínimos ou outros limites estão especificados
• `actor_count` — quantos participantes aparecem explicitamente no requisito

Os atributos são extraídos com JSON mode e exemplos few-shot, para que o modelo não fuja do formato. Se mesmo assim o LLM deixar passar algo óbvio, como números no texto, isso é completado no pós-processamento com expressões regulares.

Em seguida entra em cena uma árvore de decisão: ela recebe os atributos numéricos e atribui ao requisito um rótulo como `ok`, `unverifiable`, `no_negative`, `no_boundary` ou `ambiguity`. Para o treinamento, a autora anotou 90 especificações, dividiu-as em 270 requisitos e obteve cerca de 82% de accuracy no conjunto de teste.

O crítico e a escala

O pipeline não termina aí. Mesmo um bom classificador enxerga apenas um requisito por vez e, por isso, deixa passar facilmente contradições entre seções. Para esses casos, há um agente crítico separado, que recebe o texto completo da especificação, a lista de passaportes em JSON e os rótulos previstos.

A tarefa dele não é reavaliar cada frase do zero, mas olhar o documento de cima e procurar conflitos, lacunas nas permissões de acesso e erros no mapeamento de integrações. Esse crítico pode notar, por exemplo, que em um trecho o campo "Depósito" é obrigatório e, em outro, aceita valor vazio.

Para que o esquema funcione além de exemplos curtos, os requisitos são processados em paralelo via `ThreadPoolExecutor`, e os modelos locais rodam no Ollama. Segundo a autora, em um PC gamer comum o sistema aguenta tranquilamente de 4–6 requisições paralelas sem degradação perceptível, e em um lote de cem requisitos isso resulta em uma aceleração de cerca de 3–4 vezes. Requisitos relacionados, por sua vez, permanecem na mesma thread, para não quebrar a ordem e o contexto geral da verificação.

O que isso significa

A análise do Habr AI mostra bem para onde caminha o desenvolvimento prático de agentes de IA: das tentativas de "empurrar tudo de uma vez para o modelo" para pipelines estreitos e controláveis, com atributos explícitos, modelos locais e uma camada separada de arbitragem. Se uma equipe quer construir um agente aplicado para análise, QA ou trabalho com documentação, terá de pensar não só na escolha do modelo, mas também em como estruturar os dados de entrada, a anotação e a verificação final do resultado.