Theory of Code Space: Do Code Agents Understand Software Architecture?

O artigo apresenta o "Theory of Code Space" (ToCS), um benchmark que avalia a capacidade de agentes de IA de construir e manter crenças arquiteturais coerentes em bases de código, revelando que a eficácia da exploração ativa, o uso de mapas de crenças estruturados e a estabilidade da memória variam significativamente entre diferentes modelos de linguagem.

O essencial

Imagine que você pediu a um assistente de IA para organizar uma biblioteca gigante e bagunçada, onde os livros estão espalhados em centenas de prateleiras, sem um catálogo visível. O assistente não pode ver tudo de uma vez; ele tem que caminhar pela biblioteca, pegar um livro de cada vez, ler o título e tentar desenhar um mapa mental de onde cada coisa está.

É exatamente isso que o artigo "Teoria do Espaço de Código" (Theory of Code Space - TOCS) investiga. Os autores criaram um teste para descobrir se os "robôs programadores" (agentes de IA) realmente entendem como o software é construído ou se eles apenas estão "chutando" enquanto olham para os arquivos.

Aqui está a explicação simplificada, usando analogias do dia a dia:

1. O Problema: O "Mapa Mental" Quebrado

Os modelos de IA atuais são ótimos em escrever pequenos trechos de código (como resolver um quebra-cabeça de uma peça só). Mas, quando precisam mexer em um projeto grande com dezenas de arquivos interligados, eles tendem a se perder.

Os pesquisadores compararam isso a um explorador em uma caverna escura:

• O que deveria acontecer: O explorador entra, vê uma caverna, anota onde estão as paredes, e constrói um mapa mental coerente de todo o lugar.
• O que acontece na realidade: Muitos agentes de IA olham para uma caverna, esquecem o que viram 5 minutos atrás, ou acham que a caverna mudou de lugar. Eles não conseguem manter um "mapa" estável do software enquanto exploram.

2. O Teste: A "Biblioteca com Orçamento"

Para testar isso, os autores criaram o TOCS. Eles geraram projetos de software artificiais (como se fossem bibliotecas) e deram aos agentes de IA uma tarefa:

• Orçamento limitado: O agente tem "dinheiro" (ações) para abrir apenas alguns arquivos.
• Exploração ativa: Ele decide qual arquivo abrir primeiro.
• O "Check-up" (Probing): A cada 3 passos, o agente é interrompido e obrigado a desenhar o mapa atual dele em um formato estruturado (um JSON), como se dissesse: "Até agora, sei que o Arquivo A fala com o B, e que o C é proibido de tocar no D".

O objetivo é ver se esse mapa mental fica melhor com o tempo ou se ele começa a alucinar e esquecer coisas que já viu.

3. As 3 Descobertas Surpreendentes (O "Pulo do Gato")

Os pesquisadores testaram vários modelos de IA (como GPT-5, Claude, Gemini) e descobriram coisas muito interessantes:

A. A "Luz do Dia" vs. "Exploração no Escuro" (A Lacuna Ativo-Passiva)

• Analogia: Imagine que você precisa decorar uma casa.
  • Modelo A (GPT-5): Ele aprende melhor quando pode andar pela casa, abrir portas e descobrir as coisas sozinho. Se você der a ele um panfleto com a planta de toda a casa de uma vez, ele se confunde e faz pior. Ele precisa "explorar" para entender.
  • Modelo B (Gemini): Ele é o oposto. Ele faz pior quando tem que escolher o que olhar. Se você der a ele a planta completa de uma vez, ele entende tudo. Se ele tiver que andar pela casa sozinho, ele se perde.
• Conclusão: Nem toda IA é boa em "explorar". Para alguns, a exploração ativa é uma habilidade que falta.

B. O "Caderno de Anotações" (Auto-Andaimagem)

• Analogia: Alguns agentes usam o que escreveram no "check-up" anterior como um caderno de anotações para ajudar no próximo passo.
• O que aconteceu: O modelo GPT-5 usou seus próprios mapas anteriores como uma "muleta" para melhorar. Ele olhou para o que escreveu antes e disse: "Ah, esqueci dessa parte, vou corrigir". Isso melhorou muito seu desempenho.
• O outro lado: Outros modelos (como o Gemini) não usaram esse caderno. Escrever o mapa não os ajudou a lembrar das coisas. Para eles, o caderno era apenas papel gasto.

C. A "Amnésia Catastrófica" (Estabilidade do Mapa)

• Analogia: Imagine dois estudantes estudando para uma prova.
  • O Estudante Pequeno (Gemini 2.5 Flash): É o menor dos modelos, mas é incrivelmente estável. Ele vê um arquivo, anota no mapa, e nunca esquece. Seu mapa só cresce, nunca diminui.
  • O Estudante Gigante (Gemini 2.5 Pro): É o modelo mais inteligente e grande. Ele começa a desenhar um mapa lindo, mas de repente, no próximo "check-up", ele esquece tudo que descobriu antes. O mapa dele desmorona.
• Conclusão: Ser um modelo "maior" ou "mais inteligente" não garante que ele consiga lembrar do que viu. A capacidade de manter a memória de longo prazo varia muito e não depende apenas do tamanho do cérebro da IA.

4. Por que isso importa?

Hoje, as empresas querem usar IAs para reescrever sistemas inteiros de bancos, hospitais e governos. Se a IA não consegue manter um "mapa mental" estável de como o software funciona, ela vai quebrar coisas sem querer, criar dependências proibidas ou esquecer regras de segurança.

O artigo mostra que:

1. Precisamos treinar as IAs não apenas para "escrever código", mas para manter mapas mentais do projeto.
2. O jeito que fazemos a pergunta (o "prompt") importa muito. Às vezes, a IA parece burra porque o teste foi mal formulado, não porque ela não sabe.
3. A "exploração ativa" (decidir o que olhar) é uma habilidade difícil que nem todas as IAs têm.

Resumo Final

O TOCS é como um exame de direção para IAs. Em vez de apenas ver se elas sabem dirigir (escrever código), o teste vê se elas sabem ler o mapa, lembrar de onde passaram e não bater no carro do vizinho por esquecimento. A descoberta principal é que algumas IAs são ótimas em dirigir sozinhas, outras precisam de um GPS completo na mão, e algumas, por mais inteligentes que pareçam, esquecem onde estão a cada 5 minutos.

Resumo técnico

1. O Problema

Embora os Agentes de IA (baseados em Grandes Modelos de Linguagem - LLMs) demonstrem excelência em tarefas de geração de código isoladas (como benchmarks HumanEval), eles falham consistentemente em tarefas de engenharia de software que exigem compreensão de arquitetura em repositórios complexos e multi-arquivos.

• A Lacuna: Existe uma desconexão entre a capacidade de gerar snippets de código e a capacidade de manter uma "cognição" coerente sobre as dependências, invariantes e intenções de design de um sistema inteiro.
• Hipótese: Os agentes falham não por falta de conhecimento de sintaxe, mas por incapacidade de construir e manter mapas cognitivos (representações estruturadas de dependências e invariantes) sob condições de observabilidade parcial (orçamento limitado de ações para abrir arquivos).
• Analogia: O trabalho se baseia na Theory of Space (TOS), que demonstrou falhas em modelos multimodais ao navegar em ambientes espaciais parciais, transplantando esse conceito para o domínio do código.

2. Metodologia: O Benchmark TOCS

Os autores introduzem o Theory of Code Space (TOCS), um benchmark projetado para avaliar a construção ativa de crenças arquitetônicas.

2.1 Ambiente e Ação

• Geração Procedural: O ambiente consiste em repositórios de código gerados proceduralmente (padrão Pipeline em Python) com estrutura arquitetônica controlada.
• Observabilidade Parcial: O agente opera sob um orçamento de ações (B=20). Ele não vê o código inteiro de uma vez.
• Ações Disponíveis:
  • LIST: Listar arquivos em um diretório.
  • OPEN: Abrir o conteúdo completo de um arquivo (custa 1 ação).
  • SEARCH: Buscar localizações de símbolos (sem conteúdo).
  • INSPECT: Verificar assinatura e docstring de um símbolo (custa 1 ação, sem corpo do código).
  • DONE: Terminar.
• Desafio: O agente deve inferir dependências que não são visíveis apenas por importações estáticas (ex: conexões via registro, fluxos de dados).

2.2 Probing de Mapa Cognitivo (Cognitive Map Probing)

A cada $K=3$ ações, o agente é interrompido e obrigado a externalizar seu estado de crença como um JSON estruturado.

• O JSON inclui: componentes (obtidos/inferidos), dependências tipadas, invariantes (regras de arquitetura) e rastreamento de incerteza.
• Isso gera uma série temporal de compreensão arquitetônica, permitindo analisar como a crença evolui, se estabiliza ou colapsa.

2.3 Métricas de Avaliação

• F1 de Dependência: Precisão e recall das arestas do grafo de dependência inferido vs. a verdade fundamental.
• F1 de Invariantes: Capacidade de descobrir restrições arquitetônicas plantadas (ex: "Módulo A não pode importar C diretamente").
• Gap Ativo-Passivo (APG): Compara o desempenho do agente explorando ativamente vs. recebendo todo o código de uma vez (Passivo) ou recebendo o traço de observações de uma execução anterior (Replay).
• Decomposição do APG: Separa o custo de seleção (escolher quais arquivos abrir) do custo de decisão (como processar as observações).

3. Principais Contribuições

1. Framework TOCS: O primeiro benchmark para avaliação de construção ativa de crenças arquitetônicas em código.
2. Gerador de Código Procedural: Um gerador que cria repositórios com quatro tipos de arestas de dependência (IMPORTS, CALLS_API, DATA_FLOWS_TO, REGISTRY_WIRES) e invariantes plantados.
3. Análise de Comportamento de Modelos: Experimentos piloto com 4 baselines (regras) e 6 LLMs de ponta (GPT-5.3-Codex, Claude Sonnet 4.6, Gemini 2.5/3, etc.).
4. Descobertas Surpreendentes: Identificação de três fenômenos críticos dependentes do modelo (detalhados abaixo).

4. Resultados e Descobertas Chave

4.1 O Gap Ativo-Passivo é Dependente do Modelo

Diferente de benchmarks espaciais onde modelos sempre pioram na exploração ativa, no TOCS o resultado varia:

• GPT-5.3-Codex: Desempenha melhor na exploração ativa do que recebendo todos os arquivos de uma vez (Gap negativo). A sobrecarga de informação ao ver tudo de uma vez prejudica sua capacidade de identificar dependências.
• Gemini 2.5 Flash: Desempenha melhor quando recebe todos os arquivos de uma vez (Gap positivo). Sua estratégia de exploração ativa é ineficiente e prejudica a compreensão.
• Conclusão: A "exploração ativa" é, em si, uma habilidade não trivial que falta em alguns modelos.

4.2 Auto-Andaimagem (Self-Scaffolding) Dependente do Modelo

Manter o mapa de crenças estruturado (JSON) no contexto do modelo atua como uma memória de trabalho externa:

• GPT-5.3-Codex: Beneficia-se enormemente (+14 pontos de F1) ao reter o JSON anterior no contexto. O modelo usa seu próprio mapa passado para orientar a exploração futura.
• Gemini 2.5 Flash: Não mostra ganho significativo na detecção de dependências ao reter o mapa, embora ajude na descoberta de invariantes.
• Implicação: A capacidade de usar a própria saída como "andaime" para raciocínio futuro varia drasticamente entre modelos.

4.3 Instabilidade Dramática do Estado de Crença

• Colapso Catastrófico: Modelos maiores (como Gemini 2.5 Pro) podem construir um mapa razoável e, em uma única sondagem, esquecer componentes inteiros descobertos anteriormente, reduzindo o F1 a zero.
• Estabilidade Surpreendente: O modelo menor (Gemini 2.5 Flash) manteve crenças perfeitamente estáveis, sem perder arestas corretas entre sondagens.
• Viés de Recência: O Gemini 3 Flash tendeu a relatar apenas os componentes mais recentemente examinados, ignorando o histórico.
• Conclusão: A estabilidade do estado de memória não é uma função direta da escala do modelo, mas sim dos objetivos de treinamento e da capacidade de atualização incremental.

4.4 Desempenho Geral

• LLMs vs. Baselines: Os melhores LLMs (GPT-5.3-Codex e Claude Sonnet 4.6) superaram todas as estratégias baseadas em regras (como BFS ou aleatório), especialmente na descoberta de tipos de arestas complexas (como Registry Wires e Data Flows) que exigem raciocínio semântico, não apenas análise de AST.
• Precisão vs. Recall: Houve uma desacoplamento significativo; alguns modelos tiveram precisão quase perfeita (0.98) mas recall muito baixo (0.13), indicando que eles não ousavam inferir conexões não explícitas.

5. Significado e Implicações

• Para o Design de Agentes: A simples recuperação de contexto (RAG) não é suficiente. Os agentes precisam de mecanismos explícitos para construir e manter mapas de dependência estruturados.
• Treinamento de Beliefs: É necessário otimizar modelos para a "externalização fiel" de conhecimento arquitetônico, não apenas para a geração de código.
• Estratégia de Exploração: A escolha de quais arquivos abrir é um gargalo crítico. A decomposição do Gap Ativo-Passivo mostra que a seleção de arquivos é uma habilidade distinta da compreensão do conteúdo.
• Limitações e Futuro: O benchmark atual usa um único padrão arquitetônico (Pipeline) e Python. O trabalho futuro visa expandir para múltiplos padrões, linguagens e avaliar modos de "Revisão" (Revise) e "Exploração" (Exploit).

Conclusão

O TOCS revela que a compreensão de arquitetura de software por agentes de IA é frágil e altamente dependente do modelo específico. A capacidade de manter uma "verdade fundamental" interna coerente sob observabilidade parcial e de usar essa crença para guiar a exploração futura são as habilidades fundamentais que diferenciam os agentes de ponta dos modelos atuais, e que ainda precisam ser desenvolvidas. O benchmark é lançado como software de código aberto para permitir que a comunidade avalie e melhore essas capacidades.