Como escrever requisitos funcionais para agentes de IA

Por que requisitos importam mais em projetos de IA do que em software tradicional

Em software determinístico, um bug tem comportamento reprodutível. Você consegue debugar, encontrar a linha, corrigir. Em agentes de IA, o comportamento é probabilístico — o mesmo input pode gerar outputs diferentes dependendo do modelo, da versão, do contexto acumulado e até da ordem das mensagens.

Isso significa que "funciona" e "não funciona" não são binários em agentes de IA. Existe um espectro. E sem requisitos claros que definam onde está a linha entre aceitável e inaceitável, o projeto vive em perpétua discussão sobre se o comportamento é correto.

Vou ser direto: em 2026, o principal motivo de retrabalho que vejo em projetos de agentes de IA não é falha técnica — é ambiguidade de requisito. O desenvolvedor implementou o que entendeu; o stakeholder esperava outra coisa; e ninguém descobriu até o go-live.

O que é diferente em requisitos para agentes de IA

Requisitos tradicionais seguem o padrão: "dado X, o sistema deve fazer Y." Funciona bem para software determinístico. Para agentes de IA, esse padrão precisa de extensões:

• Critérios de aceite observáveis — não "o agente deve ser útil", mas "o agente deve retornar uma resposta com ao menos um item concreto e acionável em até 3 segundos"
• Casos de borda e recusa explícitos — quando o agente deve dizer "não sei" ou escalar para humano?
• Escopo negativo — o que o agente explicitamente NÃO deve fazer (tão importante quanto o que deve fazer)
• Comportamento sob incerteza — o que o agente faz quando os dados estão incompletos ou conflitantes?
• Limites de ferramenta — quais ações o agente pode executar autonomamente vs. quais exigem confirmação humana?

A estrutura do requisito funcional para agente

Abaixo está a estrutura que uso em projetos. Cada campo tem um motivo de existir — vou explicar cada um.

Template de Requisito Funcional para Agente de IA

Este é o artefato central deste artigo. Copie, adapte ao seu projeto e versione junto com o código.

Por que cada campo existe — sem enrolação

ID — rastreabilidade não é burocracia

Quando um teste falha, quando um stakeholder reclama, quando você precisa revisar o que foi decidido em março — o ID é o que conecta o requisito ao código, ao teste, ao log e à conversa. Sem ID, você caça contexto por horas. Com ID, leva 30 segundos.

Pré-condições — o contrato de entrada

Agentes falham quando recebem inputs que não estavam previstos. Pré-condições explícitas permitem que o sistema valide antes de chamar o agente, evitando desperdiçar tokens e gerar respostas sem sentido. São também a base para testes de borda.

Pós-condições — o contrato de saída

Sem pós-condições definidas, não existe critério objetivo para dizer que o agente "terminou" a tarefa. Pós-condições são verificáveis automaticamente em testes e em monitoramento de produção.

Critérios de aceite com percentuais — testabilidade real

"O agente deve classificar corretamente" não é testável. "O agente deve classificar como Crítico em ≥ 95% dos casos do dataset de teste" é testável. A diferença parece pequena no papel, mas é enorme na prática: com critérios quantitativos, qualquer desenvolvedor consegue rodar os testes e saber se o requisito passa ou falha.

Casos de erro — o que mais diferencia bons requisitos de IA

Em software convencional, casos de erro são tratados com exceções. Em agentes de IA, o modelo pode "tentar" continuar mesmo quando deveria parar — e aí a coisa fica feia. Casos de erro explícitos definem o comportamento de fallback de forma inequívoca, evitando que o agente improvise em situações para as quais não foi projetado.

Escopo negativo — o que livra de surpresas

Um dos erros mais comuns: o desenvolvedor implementa algo além do escopo porque "parecia lógico". Com escopo negativo explícito, fica claro que a responsabilidade é de outro requisito — e o desenvolvedor não "inventa" funcionalidades que não foram especificadas.

Ferramentas permitidas e proibidas — princípio do menor privilégio

Agentes com acesso irrestrito a ferramentas são agentes de risco. Definir explicitamente quais ferramentas cada requisito pode usar é a implementação do princípio do menor privilégio em nível de requisito. Se o agente tiver acesso apenas ao que precisa para aquela tarefa, o raio de impacto de um erro é controlado.

Exemplo real: agente de qualificação de lead

Para tornar concreto, veja como o template se aplica a um caso B2B comum — um agente que qualifica leads recebidos por formulário antes de passá-los ao CRM:

Os 4 erros mais comuns ao escrever requisitos para IA

1. Requisitos subjetivos sem métrica

"O agente deve ser educado e prestativo." Como você testa isso? Quem decide se foi educado o suficiente? Substitua por: "O agente não deve usar linguagem negativa ou acusatória — avaliado por checklist de 10 itens com score mínimo de 8/10 em amostragem mensal de 50 respostas."

2. Ignorar os casos em que o agente deve recusar

Todo agente precisa saber quando dizer "não consigo" ou "isso está fora do meu escopo". Se você não especifica esses casos, o agente vai tentar resolver de qualquer forma — e vai inventar. Especifique explicitamente: "Quando a pergunta não se relacionar ao domínio X, o agente deve responder: 'Esta questão está fora do meu escopo. Você pode contatar [canal Y].'"

3. Misturar requisito funcional com requisito técnico

"O agente deve usar o modelo GPT-4o com temperatura 0.2." Isso é decisão técnica, não requisito funcional. O requisito funcional define o comportamento observável; a decisão técnica sobre como implementar vai em ADR (veja como escrever ADRs para IA).

4. Não envolver a área de negócio na aprovação dos critérios de aceite

Critérios de aceite escritos apenas por engenheiros costumam refletir o que é fácil de medir, não o que importa para o negócio. A aprovação do stakeholder de negócio nos critérios de aceite é o contrato que evita "mas eu esperava outra coisa" depois do go-live.

A relação com a abordagem SPEC-driven

Requisitos funcionais são um dos três documentos centrais da arquitetura SPEC-driven para projetos de IA. O SPEC-driven coloca documentação como código — versionada, revisada, parte do processo de desenvolvimento.

Na prática: os requisitos funcionais vivem no repositório junto com o código. Cada mudança de comportamento do agente implica uma atualização no requisito correspondente. O DoD (Definition of Done) do projeto inclui "requisito atualizado e aprovado" como critério obrigatório antes de qualquer merge.

O TASKS.md referencia os IDs dos requisitos em cada tarefa — assim qualquer desenvolvedor sabe exatamente qual comportamento está sendo implementado, sem precisar adivinhar.

Conclusão: ambiguidade é o inimigo do agente

Agentes de IA amplificam ambiguidade. Uma instrução vaga para um humano produz uma pergunta de esclarecimento. A mesma instrução vaga para um agente produz um comportamento inventado que pode ter efeito externo — e que vai ser descoberto em produção, no pior momento.

Requisitos funcionais bem escritos não são burocracia. São o contrato que permite que a equipe técnica, o time de negócio e a própria IA programadora estejam na mesma página sobre o que "correto" significa. Sem esse contrato, cada um vai trabalhar com sua própria definição — e o resultado é o projeto que nunca termina porque nunca está "certo o suficiente".