Seu software está pronto para ser entendido por uma IA?
Este é o primeiro artigo de uma série sobre arquitetura AI friendly, uma forma de pensar sistemas, contexto e ferramentas para que agentes de IA consigam trabalhar melhor com software real.
Talvez a melhor forma de pensar em uma IA trabalhando no seu sistema seja imaginar uma pessoa nova entrando na empresa.
Ela ainda não conhece o domínio, não sabe quais serviços existem, não entende as decisões antigas e não sabe onde encontrar as respostas. Para começar a contribuir, precisa passar por um processo de onboarding.
Essa pessoa pode tentar adivinhar as coisas. Também pode perguntar para alguém mais experiente. Mas, quando o conhecimento está bem documentado, ela consegue encontrar as respostas sozinha e avançar com mais autonomia.
Com agentes de IA acontece algo parecido. Quanto mais o agente depende de uma pessoa específica, de contexto informal ou da memória de quem já conhece aquela tarefa, pior ele funciona.
O objetivo de uma arquitetura AI friendly é tornar esse conhecimento mais explícito, acessível e navegável. Não apenas para a IA, mas também para qualquer pessoa nova que entre na equipe.
Nos últimos anos, a forma como construímos software mudou bastante. Primeiro aprendemos a escalar sistemas. Depois aprendemos a modularizar o código. Mais tarde, começamos a separar responsabilidades, distribuir serviços e organizar times por contexto. Agora estamos entrando em uma nova fase: criar software que não seja apenas usado por pessoas, mas que também possa ser compreendido por agentes de IA.
Isso parece sutil à primeira vista, mas muda bastante coisa. Um agente não entende seu sistema do mesmo jeito que um desenvolvedor experiente entende. Ele precisa de sinais, contexto, estrutura e caminhos de descoberta. Se esse contexto não está bem organizado, a IA até pode ajudar, mas vai trabalhar com mais ruído, mais tentativa e erro e menos precisão.
O problema não é falta de inteligência
Quando uma IA erra ao analisar um sistema, a explicação mais comum costuma ser: “o modelo não é bom o suficiente”. Às vezes isso é verdade. Mas muitas falhas acontecem por outro motivo: o sistema foi desenhado para pessoas que já conhecem o contexto, não para agentes que precisam descobri-lo.
Um desenvolvedor da casa sabe:
onde está a documentação relevante;
quais decisões ficaram em ADRs antigos;
qual serviço é dono de cada responsabilidade;
onde olhar em caso de incidente;
quais métricas indicam que algo está realmente errado.
Um agente, por padrão, não sabe nada disso. Ele pode inferir parte do caminho, mas inferência não substitui contexto explícito. Quando o contexto está espalhado, escondido ou inconsistente, a qualidade da resposta cai junto.
Código não é contexto suficiente
Existe uma armadilha comum: achar que, porque a IA consegue ler código, ela já entende o sistema.
Mas código é só uma parte da história.
O código mostra a implementação. Não mostra, necessariamente:
por que aquela decisão foi tomada;
qual problema de negócio ela resolve;
quais trade-offs foram aceitos;
quais partes são sensíveis;
o que já foi tentado e descartado;
como o sistema se comporta em produção.
Na prática, um sistema maduro vive em mais lugares do que o repositório. Ele vive em documentação, observabilidade, incidentes, tickets, decisões arquiteturais, dashboards e na memória coletiva do time. O desafio agora é transformar esse conhecimento disperso em algo que uma IA consiga navegar.
Uma arquitetura entendida por agentes
Se eu tivesse que resumir a ideia central deste artigo em uma frase, seria esta:
Arquitetura AI friendly é a disciplina de organizar sistemas para que agentes consigam descobrir, correlacionar e aplicar contexto com o mínimo de fricção.
Isso não significa expor tudo para a IA. Pelo contrário. Significa tornar o contexto:
mais acessível;
mais estruturado;
mais confiável;
mais conectado;
mais verificável.
Em outras palavras, não basta ter informação. A informação precisa ser encontrável e combinável.
O que isso muda na prática
Um sistema AI friendly tende a ter algumas características:
Documentação viva A documentação não pode ser um cemitério de páginas antigas. Ela precisa fazer parte do sistema e acompanhar as mudanças relevantes.
Decisões registradas Arquitetura sem histórico vira adivinhação. ADRs, RFCs e notas de decisão ajudam o agente a entender o “porquê”, não apenas o “como”.
Observabilidade como fonte de verdade Logs, traces e métricas não servem apenas para operar o sistema. Eles também ajudam a explicar o comportamento dele.
Contexto por domínio Nem todo conhecimento precisa viver no mesmo lugar. Cada contexto pode ter sua própria documentação, suas regras e seus pontos de consulta.
Ferramentas conectadas ao fluxo O agente precisa de acesso a sistemas que realmente contam a história do software: observabilidade, backlog, repositórios, incidentes e deploys.
O jeito antigo de organizar software
Essa conversa me lembra muito a evolução dos microserviços.
Antes, tentávamos colocar tudo em sistemas grandes e centralizados. Com o tempo, aprendemos que fazia mais sentido separar por domínio, responsabilidade e contexto. Não porque dividir seja elegante por si só, mas porque sistemas menores, com fronteiras claras, ficam mais fáceis de entender e evoluir.
Agora a pergunta é parecida:
Se aprendemos a decompor sistemas por contexto, por que continuamos entregando contexto em blocos gigantes para a IA?
Talvez a próxima evolução seja essa: não só decompor serviços, mas também decompor o conhecimento que alimenta agentes.
O papel das skills
Aqui entra uma peça importante: skills.
Uma skill é uma forma de empacotar contexto especializado. Em vez de dar ao agente um oceano de informação genérica, você oferece blocos de conhecimento com fronteiras claras.
Pense em exemplos como:
uma skill para Datadog;
uma skill para Argo;
uma skill para Databricks;
uma skill para New Relic;
uma skill para investigação de incidentes;
uma skill para análise de performance;
uma skill para mudanças em produção.
A ideia não é fazer o agente saber tudo ao mesmo tempo. É permitir que ele acione o contexto certo na hora certa.
Isso reduz ruído e aumenta a precisão. Em vez de tentar “ler o mundo inteiro”, o agente trabalha com um contexto mais específico e orientado ao problema.
Um exemplo simples
Imagine que um incidente começou a afetar a latência de uma API.
Sem uma arquitetura AI friendly, o agente pode até tentar ajudar, mas vai depender de muita sorte:
procurar logs em lugares errados;
interpretar dashboards sem saber quais métricas importam;
perder tempo em caminhos irrelevantes;
sugerir hipóteses genéricas.
Com contexto melhor organizado, o fluxo muda:
O agente identifica o serviço afetado.
Ele consulta a documentação do domínio.
Ele cruza os sinais de observabilidade.
Ele encontra as decisões arquiteturais relacionadas.
Ele concentra a investigação nas hipóteses mais prováveis.
O ganho aqui não é a IA fazer magia. É o sistema estar preparado para que ela trabalhe com menos atrito e mais precisão.
O que vale começar a fazer agora
Se você quiser começar de forma prática, eu sugeriria quatro frentes:
revisar a documentação mais importante do sistema;
registrar decisões arquiteturais de forma mais consistente;
melhorar a legibilidade operacional com observabilidade;
separar contextos que hoje estão misturados demais.
Você não precisa transformar tudo de uma vez. Na verdade, talvez o melhor caminho seja começar pelos pontos em que o time mais sofre: incidentes, onboarding e mudanças em áreas críticas.
Conclusão
Software pronto para ser entendido por uma IA não é software “feito para robôs”. É software com contexto mais claro, mais acessível e mais útil para qualquer pessoa ou processo que precise entender o sistema com rapidez.
No fundo, a proposta é simples: se a arquitetura ajuda pessoas a tomar melhores decisões, ela também pode ajudar agentes a tomar melhores decisões.
E talvez essa seja a próxima grande evolução da arquitetura de software: não apenas sistemas que escalem, mas sistemas que possam ser compreendidos com velocidade por humanos e por agentes trabalhando juntos.
Este foi apenas o começo. No próximo artigo, vou falar sobre por que código não é contexto suficiente e como projetar uma Context Architecture para agentes, conectando código, documentação, decisões arquiteturais e conhecimento do negócio.