Codified Context: Infrastructure for AI Agents in a Complex Codebase
Este artigo apresenta uma infraestrutura de contexto codificado, composta por uma constituição de memória ativa, agentes especialistas e uma base de conhecimento, desenvolvida para um grande sistema distribuído em C# para superar as limitações de memória persistente e manter a coerência em sessões de codificação assistida por IA.
Artigo original sob licença CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). Esta é uma explicação gerada por IA do artigo abaixo. Não foi escrita nem endossada pelos autores. Para precisão técnica, consulte o artigo original. Ler aviso legal completo
Imagine que você está construindo um arranha-céu gigante, mas em vez de ter uma equipe de engenheiros experientes, você tem apenas um engenheiro genial, mas com amnésia.
Esse engenheiro (a Inteligência Artificial) sabe tudo sobre construção: sabe como misturar concreto, como calcular a resistência do aço e como desenhar fachadas lindas. O problema é que, toda vez que você o chama para trabalhar em uma nova sala, ele esquece completamente o que foi feito na sala anterior, quais regras de segurança foram combinadas e quais erros já foram cometidos. Ele tende a repetir os mesmos erros e a inventar soluções que não combinam com o resto do prédio.
O artigo de Aristidis Vasilopoulos apresenta uma solução para esse problema: uma "Infraestrutura de Contexto Codificado". Em vez de tentar forçar a IA a lembrar de tudo na hora, o autor criou um sistema de arquivos vivos que funcionam como a memória e a bússola do projeto.
Aqui está como esse sistema funciona, usando analogias do dia a dia:
1. A Grande Ideia: Tratar Documentação como "Fio Elétrico"
Geralmente, quando escrevemos um manual ou uma documentação, é algo chato que ninguém lê, feito apenas para humanos. Neste projeto, a documentação é tratada como infraestrutura crítica, como o fio elétrico ou o encanamento. Se o fio estiver cortado, a luz não acende. Se a documentação estiver errada ou faltando, a IA constrói coisas erradas.
O sistema é dividido em três "camadas" (ou andares), cada uma com uma função específica:
🏛️ Camada 1: A "Constituição" (Memória Quente)
- O que é: Um único arquivo pequeno que a IA lê toda vez que você inicia uma conversa.
- A Analogia: Imagine que é a Constituição de um país ou as Regras do Jogo que ficam coladas na parede da sala de reuniões.
- O que ela faz: Ela diz: "Nós usamos este tipo de tijolo", "Nunca pinte a parede de azul", "Se o elevador falhar, faça X". Ela garante que, não importa quem (ou qual IA) entre na sala, todos sigam as mesmas regras básicas. Ela é sempre carregada na memória, como um chapéu de segurança que você nunca tira.
🧠 Camada 2: Os "Especialistas" (Agentes de Domínio)
- O que é: Um grupo de 19 "personas" ou especialistas diferentes, cada um com seu próprio manual de instruções.
- A Analogia: Imagine que você não tem apenas um engenheiro, mas uma equipe de consultores. Se você precisa consertar o sistema elétrico, você chama o "Eletricista". Se precisa de pintura, chama o "Pintor".
- O que eles fazem: Cada especialista já chega na sala com meio cérebro cheio de conhecimento específico. Por exemplo, o "Especialista em Rede" já sabe, de cor, todos os erros comuns que causam falhas na conexão, sem precisar pesquisar. O autor descobriu que, para tarefas difíceis, é melhor ter um especialista que já "estudou o assunto" do que tentar explicar tudo do zero para um generalista.
📚 Camada 3: A "Biblioteca de Conhecimento" (Memória Fria)
- O que é: Uma coleção de 34 documentos detalhados sobre cada parte do sistema (como funciona o sistema de salvamento, como funciona a física do jogo, etc.).
- A Analogia: É a biblioteca técnica ou o arquivo morto do prédio. Você não lê tudo o tempo todo (seria muito pesado), mas quando surge um problema complexo, você vai até a biblioteca, pega o livro específico sobre aquele assunto e lê a página necessária.
- O que ela faz: Ela contém os detalhes finos. Se o "Constituição" diz "não use tijolos vermelhos", a "Biblioteca" explica por que e como usar os tijolos cinzas corretamente.
Como tudo se conecta? (O Sistema de Tráfego)
O autor criou um "semáforo inteligente" (chamado de Trigger Table). Quando você pede algo à IA, o sistema olha o que você está fazendo e decide automaticamente:
- "Isso é uma regra geral?" -> Usa a Constituição.
- "Isso é sobre rede?" -> Chama o Especialista em Rede e abre o Livro de Rede.
- "Isso é sobre interface?" -> Chama o Especialista em UI.
Isso evita que a IA fique confusa ou tente adivinhar coisas que ela deveria saber.
O Resultado na Prática
O autor usou esse sistema para construir um jogo multiplayer complexo (com mais de 100.000 linhas de código) sozinho, usando a IA como sua única ferramenta de escrita de código.
O que aconteceu?
- Sem o sistema: A IA esquecia regras, criava bugs que se repetiam e precisava que o humano explicasse as mesmas coisas dezenas de vezes.
- Com o sistema: A IA manteve a consistência por 283 sessões de trabalho. Se um erro fosse corrigido uma vez, ele era "gravado" na documentação, e a IA nunca mais cometeria aquele erro.
Lições para o Dia a Dia (Resumo das Regras de Ouro)
O artigo termina com conselhos simples para quem usa IA:
- Comece com as regras básicas: Mesmo um pequeno arquivo de regras ajuda muito desde o primeiro dia.
- Se você explicou duas vezes, escreva: Se você teve que explicar a mesma coisa para a IA duas vezes, crie um documento. A próxima vez, a IA lerá o documento em vez de você ter que explicar de novo.
- Crie especialistas: Se uma tarefa é muito difícil, crie um "agente especialista" com todo o conhecimento daquele assunto embutido nele.
- Cuidado com documentos velhos: Se você mudou o código mas não atualizou o manual, a IA vai seguir o manual velho e estragar tudo. A documentação precisa ser tão viva quanto o código.
Conclusão
A grande descoberta deste trabalho é que, para construir coisas grandes com IA, não basta ter um cérebro inteligente; é preciso ter uma memória organizada. Ao transformar a documentação em uma infraestrutura ativa (como eletricidade e água), o autor conseguiu que uma única pessoa, com ajuda de IA, construísse um sistema complexo que normalmente exigiria uma equipe inteira, mantendo a qualidade e a consistência do início ao fim.
Afogado em artigos na sua área?
Receba digests diários dos artigos mais recentes que correspondam às suas palavras-chave de pesquisa — com resumos técnicos, no seu idioma.