# Código não é contexto: projetando uma Context Architecture para agentes

Este é o segundo artigo da série sobre arquitetura AI friendly. No primeiro texto, falei sobre como uma IA se parece com uma pessoa nova entrando em uma empresa e tentando entender um sistema pela primeira vez.

Agora quero aprofundar uma parte importante dessa comparação: onde essa pessoa encontra as informações de que precisa?

## Código é só uma parte da história

Quando alguém novo entra em uma equipe, normalmente começa pelo repositório. É ali que estão os serviços, os endpoints, os modelos, os testes e as regras implementadas.

Mas dificilmente o código responde tudo.

Ele pode mostrar que uma decisão existe, mas não explicar por que ela foi tomada. Pode mostrar que dois serviços se comunicam, mas não deixar claro qual deles é o dono daquela responsabilidade. Pode mostrar uma regra de negócio, mas não explicar em que situação ela se aplica ou o que acontece quando ela é alterada.

Para entender um sistema de verdade, uma pessoa precisa combinar várias fontes:

*   código;
    
*   documentação;
    
*   decisões arquiteturais;
    
*   tickets e épicos;
    
*   incidentes anteriores;
    
*   dashboards e métricas;
    
*   conversas com pessoas do time.
    

O mesmo vale para agentes de IA.

O problema é que, em muitas empresas, essas informações existem, mas não estão conectadas. O código está em um repositório. As decisões estão em uma ferramenta de documentação. Os tickets estão em outro sistema. Os incidentes estão em uma plataforma de operação. E o contexto mais importante continua na cabeça de algumas pessoas.

Ter informação não é o mesmo que ter contexto.

## O que é uma Context Architecture?

Eu gosto de pensar em Context Architecture como a forma de organizar e conectar as diferentes fontes de conhecimento que explicam um sistema.

Não é criar um documento gigante com tudo o que a empresa sabe. Também não é copiar toda a documentação para dentro de um banco vetorial e esperar que a resposta apareça.

É criar caminhos para que uma pessoa ou um agente consiga responder perguntas como:

*   qual é a responsabilidade deste serviço?
    
*   quais outros sistemas dependem dele?
    
*   por que ele foi construído dessa forma?
    
*   qual regra de negócio está sendo aplicada aqui?
    
*   como sabemos que ele está funcionando corretamente?
    
*   o que já aconteceu quando essa parte mudou?
    

Uma arquitetura de contexto bem construída não elimina a necessidade de raciocínio. Ela diminui o esforço necessário para encontrar as informações certas.

## O contexto não precisa estar em um único lugar

Existe uma tentação de centralizar tudo. Criar uma grande página chamada “Como a empresa funciona”, colocar milhares de linhas nela e esperar que todos encontrem o que precisam.

Na prática, esse documento envelhece rapidamente. Fica difícil saber o que ainda é válido, quem é responsável por atualizá-lo e qual parte se aplica a cada situação.

Talvez seja melhor pensar no contexto como uma rede:

![](https://cdn.hashnode.com/uploads/covers/67081fa628a6c4cdb75a7fc9/5bc9af65-df1f-4d59-aa77-c6b6310b8857.png align="center")

Cada fonte continua existindo no lugar mais adequado. O que muda é a existência de relações claras entre elas.

Uma tarefa deveria apontar para o domínio afetado. O domínio deveria apontar para os serviços envolvidos. O serviço deveria ter sua documentação operacional. As decisões importantes deveriam estar registradas. E os sinais de produção deveriam ser fáceis de encontrar.

O objetivo não é centralizar o conhecimento. É torná-lo descobrível.

## Um exemplo de estrutura

Vamos imaginar um domínio de pagamentos. O código pode estar em um repositório, enquanto a documentação, os ADRs e os runbooks continuam nas ferramentas que a equipe já usa:

![](https://cdn.hashnode.com/uploads/covers/67081fa628a6c4cdb75a7fc9/c2ef95d6-c84c-4a2f-a1ed-c1e3d8debb9d.png align="center")

O `README.md` do repositório pode explicar a responsabilidade do serviço e apontar para o `Architecture Hub`. A página `context.md` pode registrar os conceitos de negócio e as fronteiras do domínio. Os ADRs podem continuar em uma ferramenta de arquitetura, os runbooks em uma plataforma de documentação e os dashboards na ferramenta de observabilidade.

O `links.md` não precisa copiar o conteúdo dessas fontes. Ele pode funcionar como um índice confiável, com links para o lugar onde cada informação é mantida.

Um agente que recebe uma tarefa sobre pagamentos não precisa ler todos os arquivos do repositório imediatamente. Ele pode começar pelo mapa do domínio, seguir os links relacionados à tarefa e consultar cada fonte no momento adequado.

O mais importante nessa estrutura não é colocar tudo na mesma pasta. É deixar explícito onde cada tipo de conhecimento vive e como chegar até ele.

## Contexto precisa ter dono

Documentação sem ownership costuma virar documentação abandonada.

Se ninguém sabe quem deve atualizar uma página, ela provavelmente vai ficar desatualizada. Se uma decisão arquitetural não registra quem participou e em que contexto foi tomada, no futuro ela pode parecer uma regra sem motivo.

Por isso, uma Context Architecture também precisa responder:

*   quem é responsável por este contexto?
    
*   quando ele foi atualizado?
    
*   qual sistema é a fonte original desta informação?
    
*   como sabemos que ela ainda é válida?
    

Isso é importante para humanos e para agentes. Um agente pode encontrar uma página relevante, mas ainda precisa avaliar se aquela informação é atual, se pertence ao sistema certo e se pode ser usada para tomar uma decisão.

Contexto sem indicação de validade pode ser tão perigoso quanto a falta de contexto.

## O papel das decisões arquiteturais

Uma das informações mais valiosas para entender um sistema é o histórico das decisões.

O código atual mostra o resultado de várias escolhas. Um ADR ajuda a explicar essas escolhas.

Ele pode registrar:

*   o problema que precisava ser resolvido;
    
*   as alternativas consideradas;
    
*   os critérios usados na decisão;
    
*   os trade-offs aceitos;
    
*   as consequências esperadas.
    

Sem esse histórico, é comum alguém olhar para uma implementação e concluir que ela poderia ser muito mais simples. Talvez pudesse mesmo. Mas talvez existisse uma restrição que não aparece mais no código.

Para um agente, essa diferença é fundamental. Sem o contexto da decisão, ele pode sugerir uma mudança tecnicamente elegante, mas incompatível com uma necessidade real do negócio ou com uma limitação operacional conhecida pelo time.

## Contexto deve acompanhar o fluxo de trabalho

Outro ponto importante é não tratar contexto como uma atividade separada do desenvolvimento.

Se a documentação só é atualizada em uma grande revisão anual, ela vai ficar para trás. Se os ADRs são escritos apenas quando alguém lembra, muitas decisões importantes vão desaparecer. Se os incidentes não deixam aprendizados registrados, o time volta a investigar os mesmos problemas várias vezes.

O contexto precisa entrar no fluxo normal:

1.  Uma mudança começa com uma tarefa ou um épico.
    
2.  A equipe identifica os domínios e serviços afetados.
    
3.  As decisões relevantes são registradas.
    
4.  A documentação é atualizada junto com a implementação.
    
5.  A observabilidade mostra o comportamento depois do deploy.
    
6.  Incidentes e aprendizados voltam para a base de conhecimento.
    

Não precisa ser um processo pesado. O mais importante é que as relações existam e sejam mantidas próximas do momento em que o conhecimento é produzido.

## O que uma pessoa nova deveria conseguir fazer?

Uma boa forma de testar essa arquitetura é escolher uma tarefa real e imaginar alguém novo tentando executá-la.

Essa pessoa conseguiria descobrir:

*   qual parte do sistema precisa ser alterada;
    
*   quem é o responsável pelo domínio;
    
*   quais decisões limitam a solução;
    
*   como validar que a mudança funcionou;
    
*   onde investigar caso algo dê errado?
    

Se a resposta para todas essas perguntas for “precisa falar com alguém”, existe uma oportunidade de melhorar o contexto do sistema.

Esse mesmo teste pode ser aplicado a um agente de IA. A diferença é que o agente vai deixar ainda mais evidente quando uma informação importante depende de conhecimento informal.

Uma forma prática de medir isso é escolher uma tarefa pequena e observar o caminho necessário para resolvê-la. Se a pessoa precisa abrir vários sistemas sem nenhuma relação entre eles, ou perguntar para alguém antes de cada decisão, o problema não é apenas de documentação. É de arquitetura de contexto.

## Context Architecture não é burocracia

É possível transformar esse tema em mais um conjunto de processos obrigatórios. Não acho que esse seja o objetivo.

A proposta não é escrever documentação por escrever. É reduzir o tempo que as pessoas gastam procurando respostas e diminuir a dependência de quem esteve presente quando uma decisão foi tomada.

Uma arquitetura de contexto bem cuidada ajuda no onboarding, na investigação de incidentes, no planejamento de features e na manutenção do sistema. A presença de agentes de IA apenas torna essa necessidade mais visível.

No fim, estamos falando de uma prática antiga com uma nova pressão: tornar o conhecimento do sistema mais explícito para que ele não fique preso à memória de poucas pessoas.

## Conclusão

Código explica como o sistema funciona em um determinado momento. Contexto ajuda a explicar por que ele funciona dessa forma, quais limites existem e como ele se relaciona com o restante da organização.

Uma Context Architecture não precisa colocar tudo em um único lugar. Ela precisa conectar as fontes certas, deixar claro quem é responsável por cada contexto e facilitar a descoberta das informações.

Quando fazemos isso, o sistema fica mais fácil de entender para quem está chegando, para quem está investigando um problema e também para os agentes que vão trabalhar ao nosso lado.

No próximo artigo, vou falar sobre observabilidade como fonte de contexto. Logs, métricas e traces não servem apenas para encontrar erros. Eles também ajudam a explicar o comportamento real do sistema.