Engenharia com IA

Esta é a nota longa. A versão curta, com o problema e o que mudou, está em Ferramental de engenharia com IA.

O que existe hoje

Uma habilidade por ferramenta ou domínio operacional da casa. Ganchos automáticos, em par para os dois sistemas operacionais que o time usa. Comandos de linha cobrindo service desk, banco, log, identidade, versão, padrão e contexto. Uma base de conhecimento das aplicações do parque, mais as regras do padrão de código. E uma suíte de testes maior que o próprio ferramental, que é portão de merge request.

Instala e atualiza com o mesmo comando, tem modo de conferência que não escreve nada, e modo não interativo para repetir a configuração numa segunda máquina.

Deixou de ser meu. Hoje outras pessoas da engenharia commitam nele, e é esse o teste que importa: ferramental que só o autor mantém é configuração pessoal com nome bonito.

As peças

O ciclo é o que fecha o desenho. Ele consome as outras três e devolve capacidade para elas, sem que eu precise empurrar.

• Ferramenta como CLI: um agente que não consegue agir nas ferramentas reais é uma janela de chat. Tornar cada ferramenta endereçável por linha de comando é o que o transforma em operador
• Padrão que a máquina consome: o padrão da casa escrito uma vez, materializado no formato que cada ferramenta de IA entende, com habilidades apontando para os CLIs
• O ciclo que se alimenta: problema que custou caro vira registro, registro repetido vira oportunidade, oportunidade vira habilidade nova. Inclusive a promoção é automática
• O mapa do parque: as aplicações do grupo como base de conhecimento consultável, varrida e atualizada sem intervenção

O que sustenta o desenho

Conhecimento vive uma vez, adaptador é descartável

O conhecimento, o que uma ferramenta faz, qual armadilha ela tem, qual o padrão da casa, fica numa camada só. O formato que uma ferramenta de IA específica consome fica noutra, isolado como adaptador.

A consequência é a que importa: trocar de ferramenta de IA amanhã é escrever um adaptador irmão, não reescrever o conhecimento. Ferramenta de agente é o mercado que mais muda hoje; amarrar anos de conhecimento operacional ao formato de um fornecedor seria comprar dívida com data marcada.

Sincronização, não instalação

O comando não é de primeira vez: roda quantas vezes for preciso. Peça da ferramenta que mudou de versão é reescrita; conteúdo de quem usa nunca é tocado.

Essa separação é o que faz o mesmo comando servir para instalar e para atualizar, e é o que permite distribuir para o time sem medo: ninguém perde a configuração pessoal ao receber a versão nova. Foi por isso que o comando parou de se chamar “instalar”: o nome errado convidava ao uso errado.

Escrita graduada por raio de alcance

Todo o ferramental é do time: qualquer pessoa da engenharia propõe mudança. Mas as peças cujo erro tem alcance grande exigem revisão de quem lidera: os ganchos automáticos, o contexto comum a todas as sessões, o padrão de código, os comandos que escrevem em sistema sensível, e o próprio sincronizador.

Não é hierarquia por status. É raio de alcance: um erro numa habilidade de consulta atrapalha quem a usou; um erro no gancho de commit ou no sincronizador atinge todas as máquinas do time na próxima execução.

O ferramental tem testes que impedem vazamento

A suíte é maior que o próprio ferramental, e duas dessas verificações recusam o commit se algo pessoal ou identificável entrar na prosa versionada: token, caminho absoluto de máquina, e-mail pessoal, arquivo de credencial.

Duas decisões nesses guardas que eu defendo:

Isenção é nominal, nunca por diretório. É tentador isentar testes/ inteiro, já que a fixture precisa conter o conteúdo sujo. Mas diretório isento blinda para sempre, inclusive contra um vazamento real que caia ali no ano que vem. Cada isenção é de um arquivo específico, e só entra quando o achado não pode ser resolvido apertando o padrão.

Guarda sem caso positivo não é guarda. Cada detector tem um teste que planta o problema e exige que ele seja pego. Sem isso, um detector quebrado passa por detector funcionando, que é exatamente o tipo de falha silenciosa que este ferramental existe para evitar.

Aprendi isso do jeito caro, e o mesmo princípio está aplicado neste vault: o verificador que impede vazamento aqui também tem fixture positiva, porque a primeira versão dele aprovava um terço dos arquivos sem olhar e dizia “limpo”.

IA no produto, não só no processo

Tudo acima é IA aplicada a como eu construo software. É a maior parte do meu trabalho com o tema, mas não é tudo, e vale separar porque são problemas diferentes.

Em Triagem de licitações com LLM a IA está dentro do produto: um modelo lê milhares de editais públicos por dia, atribui uma nota de relevância e a razão dela, e o sistema que eu construí é a camada de curadoria humana em cima disso: ordena pela nota, mostra o porquê, e registra o veredito de quem decide.

A decisão de projeto que importa ali é a divisão de trabalho: o modelo ordena, a pessoa decide. Triagem tolera imprecisão porque ordenação aproximada já reduz mil para vinte; a decisão de disputar envolve capacidade, margem e relação com o órgão, que não estão no documento. E a razão vem junto da nota, senão a pessoa relê o edital para confiar e o ganho evapora.

Por que isso é competência de engenharia

Porque o gargalo mudou de lugar. Quando implementar fica barato, o valor migra para quem sabe definir o problema, verificar o resultado e organizar o contexto em que o trabalho acontece.

E há uma consequência que eu não tinha previsto: o agente falha exatamente onde a documentação falha. Quando a convenção está implícita, quando a regra mora na cabeça de alguém, quando “é assim que a gente faz aqui” nunca foi escrito, é ali que o resultado sai errado. Trabalhar assim me obrigou a tornar explícito o que eu já deveria ter tornado explícito para pessoas. O ganho de qualidade para o time veio junto, e não era o objetivo declarado.

O que eu mudei na minha própria prática

A qualidade da definição do problema virou o gargalo. Entender o problema, escolher a arquitetura e escrever o critério de aceite passaram a ser onde o resultado é decidido. É o que Projetar antes de implementar já defendia, agora com consequência prática imediata: a especificação é o que o agente executa.

Contexto versionado é infraestrutura. O que um agente precisa saber sobre um repositório (arquitetura, convenção, armadilha conhecida, o que não fazer) mora no repositório, versionado como código. Não é prompt descartável.

Verificação não é opcional. Agente produz resultado plausível com a mesma confiança com que produz resultado correto. Todo resultado passa por teste ou por conferência contra a fonte, e essa conferência é trabalho meu. É por isso que a parte mais interessante de Padrão que a máquina consome não é o padrão: é o mecanismo que faz um padrão mentiroso quebrar o build.

Até onde chegou

O ferramental é recente, e a adoção por repositório ainda é pequena, e prefiro declarar onde ele já está do que onde eu gostaria que estivesse. O que já está distribuído para o time é a base; o uso repositório a repositório vem depois.

Como isso se conecta com o resto: Qualidade e engenharia de contexto é a competência que sustenta, e Como eu depuro e Como eu trabalho são onde a prática aparece no dia a dia.