# 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:

1.  **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.
    
2.  **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”.
    
3.  **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.
    
4.  **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.
    
5.  **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:

1.  O agente identifica o serviço afetado.
    
2.  Ele consulta a documentação do domínio.
    
3.  Ele cruza os sinais de observabilidade.
    
4.  Ele encontra as decisões arquiteturais relacionadas.
    
5.  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.