Os meus agentes esquecem o repositório. Fiz-lhes um mapa

Os meus agentes de programação esquecem o repositório entre sessões, por isso dou-lhes um caminho de leitura fixo. Quatro camadas de texto simples mostram o que está atualizado, as decisões já tomadas e onde está o código relevante. Assim gastam menos contexto a redescobrir o código, mas manter o mapa certo continua a ser a parte difícil.

O que é um sistema de gestão de contexto? Um caminho de leitura fixo

Para uma alteração de faturação, o meu sistema de gestão de contexto envia o agente para um índice que indica dois documentos e uma pasta. Este caminho de leitura fixo substitui uma pesquisa aberta por todo o repositório, por isso o agente começa nos ficheiros com maior probabilidade de serem relevantes.

A documentação do Claude Code explica por que motivo um ponto de partida repetível é importante: “Cada sessão do Claude Code começa com uma janela de contexto nova” [1]. O agente começa sem conhecer o repositório e não consegue levar o que aprendeu para a sessão seguinte. Qualquer continuidade tem de vir de informação que possa voltar a encontrar.

O mapa não tenta guardar tudo aquilo de que o agente poderá precisar. Um ficheiro de instruções carregado automaticamente aponta para o estado atual, as decisões anteriores e as localizações relevantes do código, enquanto o agente só carrega os detalhes quando a tarefa os exige. A escolha inicial é importante porque serve de base a todas as decisões posteriores.

Quanto custa uma sessão em branco? Tokens e precisão

Uma sessão em branco custa qualidade e tokens porque o agente tem de compreender o sistema antes de o poder alterar. Se essa aprendizagem depender de correspondências de palavras-chave, é fácil ignorar pormenores importantes, e a alteração resultante pode parecer razoável embora esteja errada. A própria pesquisa também consome contexto antes de começar o trabalho pedido.

Carregar mais ficheiros não resolve o problema por si só, pois um modelo não mantém o mesmo nível de atenção durante uma janela de contexto longa. A Chroma Research testou 18 modelos e concluiu que o desempenho diminuía à medida que a entrada crescia, mesmo em tarefas que os mesmos modelos executavam bem com um prompt curto [2].

Os contextos longos falham de várias formas, não apenas por falta de espaço. Drew Breunig explica que os primeiros erros podem afetar o raciocínio posterior, que as ações anteriores podem distrair o modelo e que diferentes partes da entrada podem entrar em conflito. Cita também um estudo da Databricks no qual o Llama 3.1 405B começou a perder precisão por volta dos 32.000 tokens; os agentes tornaram-se menos eficazes acima dos 100.000 tokens, mesmo em modelos com janelas de um milhão de tokens [3].

A equipa de engenharia da Anthropic descreve a mesma limitação como um orçamento de atenção [4]. Na prática, cada token gasto a compreender o repositório deixa menos atenção para a alteração pedida.

Os números do meu repositório principal tornam esta escolha inevitável. Os seus 418 ficheiros markdown contêm cerca de 7 MB de texto e, conforme o método de estimativa, lê-los todos exigiria entre 5,7 e 8,75 janelas de contexto de 200.000 tokens. O agente tem de ler apenas uma parte, por isso utilizo uma ordem documentada em vez de deixar essa escolha aos primeiros resultados de uma pesquisa por palavras-chave.

Quatro camadas de texto simples dão prioridade aos factos atuais

O sistema orienta cada sessão através de regras, estado atual, decisões e histórico opcional. Ficheiros normais do repositório tornam as quatro camadas fáceis de inspecionar, rever e atualizar, o que para mim importa mais do que um sistema de pesquisa sofisticado.

AGENTS.md            # the rules; auto-loaded (CLAUDE.md is a symlink to it)
docs/
  STATE.md           # current truth: live, in flight, not yet verified
  INDEX.md           # the router: which docs to read for which task
  decisions/         # one numbered file per decision; superseded, never edited
  sessions/          # history: what happened when, explicitly not authority

cada sessão

• AGENTS.md regras e ordem de leitura, carregado automaticamente

aponta para

o mapa

• STATE.md estado atual, ler primeiro
• INDEX.md documentos para esta tarefa

encaminha para

a tarefa

• Documentação da área e código apenas o que a alteração afeta
• decisions/ porque está feito desta forma
• sessions/ histórico, nunca autoridade

O ficheiro de regras vem primeiro porque os agentes o carregam automaticamente. A Agentic AI Foundation descreve o AGENTS.md como um padrão aberto usado por mais de 60.000 projetos de código aberto [5], enquanto o Claude Code lê o CLAUDE.md. A documentação do Claude Code recomenda a ligação que utilizo: tornar o CLAUDE.md uma ligação simbólica ao AGENTS.md e manter o ficheiro partilhado com menos de 200 linhas [1].

No início, mantinha um ficheiro separado para cada ferramenta, mas as respetivas regras começaram a divergir. A ligação simbólica eliminou essa fonte de divergência ao dar às duas ferramentas o mesmo ficheiro e deixar-me uma única cópia para atualizar.

Do ficheiro de regras, cada sessão passa para o resumo. Este indica o que está em produção, o que ainda está em curso e, mais importante, o que ainda não foi verificado. A última categoria impede o agente de tratar trabalho inacabado ou um pressuposto não confirmado como factos.

Depois do resumo vêm as decisões e o histórico. O projeto ADR define um registo de decisão de arquitetura como um documento sobre uma decisão de arquitetura importante [6]; no meu sistema, cada registo explica tanto a decisão como a sua razão. O meu repositório acumulou 74 registos em oito semanas e, quando uma decisão muda, um novo registo substitui o antigo em vez de o reescrever. Os registos de sessão são diferentes: formam um histórico ao qual apenas se acrescentam entradas e que o agente pode consultar, mas nunca como fonte do estado atual.

Uma ordem de autoridade resolve respostas contraditórias

As camadas só funcionam se o agente souber resolver conflitos entre elas. Por isso, todos os pontos de entrada do repositório indicam a mesma ordem de autoridade: o código prevalece sobre os registos de decisões, estes prevalecem sobre o resumo e o resumo prevalece sobre o histórico. Quando uma pesquisa encontra cinco respostas escritas em momentos diferentes, o agente pode seguir a fonte com maior prioridade e atualizar ou assinalar as restantes.

Manter o histórico fora do caminho normal de leitura tem um grande efeito prático. Os registos de sessão representam 73% de todos os bytes de documentação deste repositório, por isso excluí-los reduz a estimativa de leitura total de 8,75 janelas de contexto para cerca de 2,3. A documentação atual continua a ser extensa, mas torna-se muito mais fácil de percorrer para o agente.

Como mantenho os ficheiros de contexto atualizados? Documentação e código mudam juntos

Trato a documentação como parte da alteração ao código. Sempre que o código muda um facto de arquitetura, o mesmo commit tem de atualizar o documento relevante, em vez de deixar esse trabalho para uma limpeza posterior. O ficheiro de instruções apresenta esta regra logo no início e repete-a na verificação final do agente, quando é mais difícil ignorar a atualização.

No meu repositório, os agentes seguiram essa verificação com mais regularidade do que as pessoas. Depois de alargar a regra à documentação destinada ao utilizador, a percentagem de commits de UI que atualizava os documentos correspondentes subiu de 12,3% para 31,9%. Uma taxa de 31,9% está longe de mostrar que a regra é sempre cumprida, mas é 2,6 vezes superior à anterior, e a maioria das falhas surgiu em alterações que nenhum agente acompanhou do início ao fim.

Aplico uma segunda regra à informação que muda entre sessões: antes de parar, o agente escreve um registo curto da sessão e atualiza o resumo. A passagem para outra tarefa desencadeia o mesmo processo. Sem esse momento explícito, as atualizações que parecem fáceis de fazer mais tarde são igualmente fáceis de esquecer.

Embeddings e servidores MCP não distinguiam informação atual

Deixei de usar ambos porque encontrar informação não era o problema. Os sistemas encontravam informação relevante, mas não conseguiam determinar de forma fiável se continuava atualizada. O meu servidor MCP de memória e o índice vetorial devolviam muitas vezes o tema certo do mês errado, porque embeddings criados antes de uma refatoração não sabem que a arquitetura mudou.

Cada solução criava outra fonte de informação que eu tinha de manter, trazendo de volta o problema que queria resolver. Vários frameworks de memória de código aberto traziam ainda outra preocupação: o código nem sempre impunha o comportamento descrito no README. Quando passei a ter de verificar a atualidade dos dados e a implementação, deixei de avaliar esses sistemas. Os agentes alojados levantam a mesma questão sobre o que persiste entre sessões, um tema que trato em o que a Agents API da OpenAI guarda e o que o harness do Codex assume.

A Anthropic recomenda manter no contexto identificadores simples, como caminhos de ficheiros e consultas, e carregar os pormenores apenas quando o agente precisar deles [4]. Os ficheiros simples adequam-se a esse método porque podem ser pesquisados, comparados e revistos na mesma pull request que o código que descrevem. Um revisor consegue detetar um ficheiro markdown antigo; um índice de embeddings desatualizado é muito mais difícil de inspecionar.

Quanto custou o sistema? Menos leitura, mais manutenção

O sistema manteve a carga inicial automática em 0,22% da documentação do meu repositório, mas não conseguiu manter essa documentação correta. Uma auditoria em julho de 2026 concluiu que o resumo tinha crescido 9,5 vezes em 26 dias e continha um aviso desatualizado.

O repositório é um monorepo de produção com cerca de 277.000 linhas de TypeScript, usado por três ferramentas de agente diferentes. A estrutura cumpriu a sua função ao dar a cada ferramenta um ponto de entrada curto e uma ordem de leitura coerente. A informação dentro dessa estrutura era muito menos fiável. A forma como dois dos atuais agentes de programação lidam com funcionalidades grandes é uma comparação à parte: Claude contra Codex em grandes funcionalidades multiagente.

da documentação carregada automaticamente

0,22%

um ficheiro de regras de 15,5 KB num total de 7 MB

janelas de 200K para ler tudo

8,75×

5,7× segundo a estimativa baseada em palavras

crescimento do resumo em 26 dias

9,5×

de 75 para 711 linhas, sem nunca diminuir

Os dois primeiros valores mostram a vantagem da ordem de leitura: o agente começa com 0,22% da documentação e só carrega mais quando a tarefa o exige. O terceiro revela a fraqueza persistente do sistema. O STATE.md devia manter-se curto e ser reescrito no mesmo ficheiro, mas cresceu 9,5 vezes em menos de um mês e, durante a auditoria, o seu aviso principal estava errado. Indicava que ainda faltava enviar vários commits, embora o envio tivesse acontecido dias antes.

Esse aviso desatualizado não era um caso isolado. A documentação do esquema indicava 20 a 25 tabelas, enquanto o código tinha 34, e a auditoria removeu documentação de funcionalidades que nunca tinham existido. Também verificou 2.873 ligações relativas entre documentos e encontrou 82 que não funcionavam.

O padrão mais consistente foi a diferença entre instruções escritas e verificações automáticas. Um teste aplica a minha regra tipográfica às cadeias de texto da interface, onde a auditoria não encontrou violações, enquanto cerca de metade dos ficheiros de documentação simples quebrava a mesma regra porque nada os verificava. Na prática, a ligação simbólica e o verificador de tipos eram as únicas partes em que o cumprimento era garantido automaticamente. O registo de decisão que introduziu o sistema tinha deixado este limite claro: “Isto reduz a taxa de falhas; não a elimina.”

Ainda não encontrei a quantidade certa de informação a carregar. Se os ficheiros iniciais contiverem muito pouco, o agente tem de adivinhar; se contiverem demasiado, recrio o problema dos contextos longos medido pela Chroma Research [2]. O equilíbrio muda de repositório para repositório, por isso ajusto-o a cada poucas semanas em vez de tratar a estrutura como definitiva.

No trabalho, mantenho o caminho de leitura e dispenso a estrutura extra

No trabalho, mantenho a mesma ideia de um caminho de leitura, mas apresento-a como documentação normal do projeto. O sistema completo fica nos meus projetos pessoais porque, segundo a minha experiência, muitas equipas veem uma estrutura tão específica para agentes como vibe coding, em vez de documentação para programadores.

Na prática, a versão de trabalho parece documentação normal do projeto: um ponto de entrada claro, documentos estáveis para cada área e um índice que explica onde encontrar cada coisa. Estes ficheiros markdown ajudam os novos colegas, e os agentes de programação também os conseguem seguir.

As duas versões diferem por mais do que a aparência. No trabalho, as equipas tomam decisões em reuniões e em quadros de planeamento, por isso o repositório não pode ser a fonte completa do histórico de decisões quando grande parte dele vive noutro local. Os meus projetos pessoais não têm um registo externo equivalente; se eu não escrever uma decisão no repositório, a sessão seguinte não terá forma de a encontrar.

Como começar: um ficheiro de regras com menos de 200 linhas

Eu começaria com um ficheiro de regras com menos de 200 linhas que indique as convenções do repositório e a ordem pela qual o agente deve ler os outros ficheiros. A documentação do Claude Code recomenda acrescentar uma regra quando o agente repete um erro [1], e esse também é o sinal que uso para fazer manutenção. Um erro repetido significa que o caminho de leitura não explicou algo com clareza suficiente.

O resto pode surgir à medida que fizer falta. Adicione um ficheiro de estado e aponte para ele a partir das regras; depois, crie um índice quando a documentação já não couber num único ecrã. Escreva o primeiro registo de decisão quando um agente questionar algo que você já decidiu e adicione uma pasta de histórico quando precisar de registar trabalho anterior sem o apresentar como verdade atual. Um caminho de leitura claro também mudou a forma como um modelo trabalha para mim, o que descrevo no meu fluxo de trabalho com o Opus 5, feito de planos claros e tarefas menores.

A partir daí, mantenha os ficheiros com o mesmo cuidado que dedica ao código. O meu artigo anterior defendia backends suficientemente pequenos para um agente compreender; este sistema aplica o mesmo princípio à informação que o código não consegue explicar sozinho. O agente continuará a começar todas as sessões sem memória, mas um caminho de leitura bem mantido permite-lhe encontrar o contexto certo sem ler todo o repositório.