Engenharia com IA

A leitura comum de “usar IA para programar” é um assistente que escreve função. Não é o que eu faço, e a diferença não é de grau.

Eu construí um ferramental de engenharia em volta do agente, e ele deixou de ser meu: hoje é um produto interno que qualquer pessoa da engenharia instala com um comando. As ferramentas da casa viraram comandos que o agente opera, os padrões viraram instrução que ele carrega sozinho, o conhecimento do parque virou base consultável que se atualiza sem intervenção, e o atrito do dia a dia virou entrada de um ciclo que gera ferramenta nova. Escrever código é a parte pequena disso.

O que existe hoje

Habilidades distribuídas	11 — uma por ferramenta ou domínio operacional da casa
Ganchos automáticos	5, em par para os dois sistemas operacionais do time
Comandos de linha	8, cobrindo service desk, banco, log, identidade, versão e padrão
Base de conhecimento	681 fichas de sistemas do parque, mais 20 regras de padrão de código
Testes	3.798 linhas — o ferramental tem mais teste do que CLI

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.

As quatro 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

As três decisões que sustentam 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

São 3.798 linhas de teste — mais do que de CLI. Duas suítes 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”.

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.

Onde isso aparece medido

Prática	Repositórios
Especificação numerada versionada junto ao código	20%
Contexto de agente versionado	9%

Os dois números são baixos de propósito: o ferramental é recente, e eu 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 por repositório vem depois.

Ver também

Qualidade e engenharia de contexto · Como eu depuro · Como eu trabalho