Arquiteto de sistemas de IA cria um «Cânone» para analistas: 17 documentos de requisitos de negócio em 8 dias

A maioria das histórias sobre agentes de IA no trabalho termina na produtividade pessoal: um entusiasta configurou os prompts e para ele tudo funciona às mil maravilhas. Nikolai Karpov, arquiteto de sistemas de IA, contou no Habr o que acontece depois, quando é preciso entregar o mesmo resultado a todo um departamento de analistas sem obrigar cada um a fazer um curso de engenharia de prompts.

Teste de fogo em vez de apresentação

O primeiro teste de verdade não aconteceu em um ambiente de testes. Um analista precisava entregar ao cliente um conjunto de requisitos de negócio para um novo produto de pagamentos, justamente quando as fontes regulatórias foram atualizadas. Fazer à mão, pela estimativa do próprio analista, levaria mais de duas semanas. Um conjunto mínimo de modelo, papéis, habilidades e ferramentas foi montado na hora, e por uma semana o autor trabalhou como copiloto do analista, ajustando o cânone diretamente para a tarefa.

A conclusão principal: a maior parte do tempo não foi gasta na geração, mas nas condições de confiança. Por qual modelo montar o documento, de onde tirar os dados, como procurar colisões, o que fazer quando faltam dados. Quando o agente começou a inventar, ajudou não só reduzir a temperatura para 0,2 e o top-p para 0,85, mas também as regras de tratamento de dados ausentes. Aliás, os parâmetros eram diferentes para outros especialistas: para eles bastava uma temperatura de 0,6. Resultado: 14 documentos em 8 dias úteis; depois o conjunto cresceu para 17, cada um revisado por uma pessoa e publicado no Confluence.

Como o cânone é estruturado

O autor separou quatro entidades. O papel responde pelos limites de autoridade e pelo trabalho com a incerteza. A habilidade descreve uma metodologia: um caso de uso, uma interface e uma API exigem verificações diferentes. A ferramenta é um script para uma operação repetível, por exemplo gerar um DOCX ou validar um XML. O modelo define a forma. As instruções detalhadas são carregadas apenas quando necessárias, então o contexto não fica sobrecarregado.

A estrutura dos projetos também teve de ser refeita após o feedback dos colegas. No início havia três camadas: fontes, rascunhos, artefatos. Depois se viu que um documento passa por muitas iterações, e surgiram diretórios por tipo de documento, com md/ e docx/ lado a lado. O contrato é simples: tudo nos diretórios de trabalho é rascunho, mesmo que a compilação tenha sido bem-sucedida. As versões aceitas pelo especialista vão para um diretório de release separado.

Os detalhes que decidem

A digitalização das fontes é considerada o alicerce: se o agente lê uma tabela errada, o erro vaza para os requisitos. Tabelas complexas dos reguladores, com linhas aninhadas, perdiam a hierarquia em uma representação plana, então a regra ficou rígida: tabelas somente em HTML. Os diagramas são convertidos para PlantUML, draw.io ou BPMN, mas conferidos com o original, pois um diagrama sintaticamente correto não garante conexões corretas.

As lacunas de dados o agente registra em open-questions.md com um identificador e um status, e no documento deixa uma marca explícita com um link. É proibido inventar uma resposta, e na sessão seguinte o agente lê o registro e continua.

O que levar daqui

Se você está implantando agentes em uma equipe, comece não pela escolha do modelo, mas pelos contratos: quem é responsável pelo quê, onde ficam os rascunhos e onde fica o que foi aceito, como as incógnitas são registradas. Os erros dos usuários devem virar correções do cânone, e não ficar no chat. E não confunda um esquema urgente com um permanente: o autor chama abertamente a troca entre modelos por causa dos limites da assinatura de decisão sob pressão, não de recomendação. O artigo é interrompido no meio, então sobre o suporte por mensageiros e a memória só é possível julgar pelo sumário, mas a base já é útil para quem constrói esse tipo de infraestrutura.