Este é o primeiro artigo de uma série sobre arquitetura amigável à IA, uma forma de pensar sobre sistemas, contexto e ferramentas para que agentes de IA possam trabalhar com mais eficiência em software do mundo real.
Talvez a melhor maneira de pensar em uma IA trabalhando no seu sistema seja imaginar uma nova pessoa entrando na empresa.
Ela ainda não conhece o domínio, não sabe quais serviços existem, não entende decisões passadas e não sabe onde encontrar as respostas. Para começar a contribuir, precisa passar por um processo de integração.
Essa pessoa pode tentar descobrir as coisas. Também pode perguntar a alguém mais experiente. Mas, quando o conhecimento está bem documentado, ela consegue encontrar as respostas por conta própria e avançar com mais autonomia.
Algo semelhante acontece com agentes de IA. Quanto mais um agente depende de uma pessoa específica, de um contexto informal ou da memória de alguém que já sabe executar uma tarefa, pior ele desempenha.
O objetivo de uma arquitetura amigável à IA é tornar esse conhecimento mais explícito, acessível e fácil de navegar. 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 equipes em torno de contextos. Agora estamos entrando em uma nova fase: criar software que não seja apenas usado por pessoas, mas que também possa ser entendido por agentes de IA.
Isso pode parecer sutil no começo, mas muda muita coisa. Um agente não entende seu sistema da mesma forma que um desenvolvedor experiente. Ele precisa de sinais, contexto, estrutura e caminhos para descoberta. Se esse contexto não estiver bem organizado, a IA ainda pode ajudar, mas trabalhará com mais ruído, mais tentativa e erro e menos precisão.
O problema não é falta de inteligência
Quando uma IA comete um erro 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 projetado para pessoas que já conhecem o contexto, não para agentes que precisam descobri-lo.
Um desenvolvedor interno sabe:
onde está a documentação relevante;
quais decisões foram registradas em ADRs antigos;
qual serviço é responsável por cada responsabilidade;
onde olhar quando ocorre um incidente;
quais métricas indicam que algo está realmente errado.
Por padrão, um agente não sabe nada disso. Ele consegue descobrir algumas coisas por conta própria, mas ainda precisa de um contexto claro. Quando o contexto está espalhado, escondido ou inconsistente, a qualidade da resposta também cai.
Código não é contexto suficiente
Existe uma armadilha comum: presumir que, como a IA consegue ler código, ela já entende o sistema.
Mas o código é apenas parte da história.
O código mostra a implementação. Ele não necessariamente mostra:
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 existe em mais lugares do que no repositório. Ele vive na documentação, na observabilidade, nos incidentes, nos tickets, nas decisões arquiteturais, nos dashboards e na memória coletiva da equipe. O desafio agora é transformar esse conhecimento em algo que uma IA possa navegar.
Uma arquitetura que os agentes conseguem entender
Se eu tivesse que resumir a ideia central deste artigo em uma frase, seria esta:
Arquitetura amigável à IA é a disciplina de organizar sistemas para que agentes possam descobrir, correlacionar e aplicar contexto com o mínimo de atrito.
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, ter informação não é suficiente. A informação precisa ser fácil de encontrar e combinar.
O que isso muda na prática
Um sistema amigável à IA tende a ter algumas características:
Documentação viva
A documentação não pode ser um cemitério de páginas desatualizadas. Ela precisa fazer parte do sistema e acompanhar as mudanças relevantes.Decisões registradas
Arquitetura sem histórico vira suposiçã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
Registros, rastreamentos e métricas não são usados apenas para operar o sistema. Eles também ajudam a explicar seu comportamento.Contexto organizado por domínio
Nem todo conhecimento precisa viver no mesmo lugar. Cada contexto pode ter sua própria documentação, regras e pontos de referência.Ferramentas conectadas ao fluxo de trabalho
O agente precisa ter acesso aos sistemas que realmente contam a história do software: ferramentas de observabilidade, listas de tarefas, repositórios, incidentes e implantações.
A forma antiga de organizar software
Essa conversa me lembra muito a evolução dos microsserviços.
No passado, tentávamos colocar tudo em sistemas grandes e centralizados. Com o tempo, aprendemos que fazia mais sentido separar as coisas por domínio, responsabilidade e contexto. Não porque dividir seja elegante, mas porque sistemas menores, com limites claros, são mais fáceis de entender e evoluir.
Agora a pergunta é parecida:
Se aprendemos a decompor sistemas por contexto, por que continuamos entregando contexto para a IA em blocos enormes?
Talvez a próxima evolução seja esta: não apenas decompor serviços, mas também decompor o conhecimento que dá suporte aos agentes.
O papel das habilidades
É aqui que entra uma peça importante: habilidades.
Uma habilidade é uma forma de empacotar contexto especializado. Em vez de dar ao agente um oceano de informações genéricas, você fornece blocos claros e bem delimitados de conhecimento.
Pense em exemplos como:
uma habilidade para Datadog;
uma habilidade para Argo;
uma habilidade para Databricks;
uma habilidade para New Relic;
uma habilidade para investigação de incidentes;
uma habilidade para análise de desempenho;
uma habilidade para mudanças em produção.
A ideia não é fazer o agente saber tudo ao mesmo tempo. É permitir que ele ative o contexto certo no momento certo.
Isso reduz o ruído e aumenta a precisão. Em vez de tentar ler tudo, o agente trabalha com um contexto mais específico e focado no problema.
Um exemplo simples
Imagine que um incidente começou a afetar a latência de uma API. Sem uma arquitetura amigável à IA, o agente ainda pode tentar ajudar, mas dependerá muito da sorte:
procurando registros nos lugares errados;
interpretando dashboards sem saber quais métricas importam;
perdendo tempo em caminhos irrelevantes;
sugerindo hipóteses genéricas.
Com um contexto mais bem organizado, o fluxo muda:
O agente identifica o serviço afetado.
Consulta a documentação do domínio.
Correlaciona os sinais de observabilidade.
Encontra as decisões arquiteturais relacionadas.
Concentra a investigação nas hipóteses mais prováveis.
O benefício não é a IA fazer mágica. É o sistema estar preparado para que a IA trabalhe com menos atrito e mais precisão.
O que vale a pena começar agora
Se quiser começar de forma prática, eu sugeriria quatro áreas de foco:
revisar a documentação mais importante do sistema;
registrar decisões arquiteturais de forma mais consistente;
melhorar a clareza operacional por meio da observabilidade;
separar contextos que hoje estão misturados demais.
Você não precisa transformar tudo de uma vez. Na verdade, a melhor abordagem pode ser começar pelas áreas onde a equipe mais enfrenta dificuldades: incidentes, integração de novas pessoas e mudanças em áreas críticas.
Conclusão
Software pronto para ser entendido por uma IA não é software “construído para robôs”. É software com um contexto mais claro, acessível e útil para qualquer pessoa ou coisa que precise entender o sistema rapidamente.
No fundo, a ideia é simples: se a arquitetura ajuda as pessoas a tomar decisões melhores, ela também pode ajudar agentes a tomar decisões melhores.
E talvez esta seja a próxima grande evolução da arquitetura de software: não apenas sistemas que escalam, mas sistemas que podem ser rapidamente entendidos por humanos e agentes trabalhando juntos.
Este foi apenas o começo. No próximo artigo, discutirei por que o código não é contexto suficiente e como projetar uma Arquitetura de Contexto para agentes conectando código, documentação, decisões arquiteturais e conhecimento de negócio.
Comentários