Por Que Seu Agente de IA Continua Esquecendo o Projeto (E Como Resolver)

Todo mundo que já trabalhou com agentes de IA em projetos longos passou por isso. No primeiro dia o agente entrega bastante: estrutura a API, escreve testes, documenta. No dia seguinte, nova conversa, agente perdido. Você explica tudo de novo. Na terceira ou quarta sessão, acaba lendo transcrições enormes tentando lembrar o que foi decidido antes.

O problema não é só limite de contexto. É que estamos guardando o estado do projeto no lugar errado.

O Custo Oculto da Memória em Conversas

Conversas funcionam bem para trocar ideias entre humanos e IA. Como base de dados de projeto, elas são péssimas.

O que acontece na prática:

• Decisões somem no meio da conversa e ficam difíceis de recuperar
• Não existe uma fonte única da verdade sobre o que está valendo
• Cada nova sessão começa do zero, sem histórico útil
• Diferentes agentes tomam decisões conflitantes sem ninguém perceber

O gargalo não é mais se a IA consegue escrever código. O problema é fazer ela entender o que você está construindo e por quê.

A Solução Simples Que Funciona

E se guardássemos o estado do projeto da mesma forma que guardamos código: em arquivos versionados dentro do repositório?

Arquivos Markdown estruturados, com blocos leves de metadados. Nada de wiki separado. Nada de ferramenta extra. Só arquivos simples.

O formato é básico:

• Título claro
• Metadados sobre ciclo de vida (ativo, concluído, arquivado)
• Função do documento (especificação, log, decisão, guia)
• Relações com outros registros
• O conteúdo propriamente dito

A simplicidade é intencional. Sem sintaxe especial. Sem banco de dados. Só arquivos que o Git já controla.

O Que Você Consegue Fazer Com Isso

Uma ferramenta de linha de comando transforma esses arquivos em algo útil. Ela cria registros novos, arquiva os concluídos, move arquivos atualizando relações automaticamente, lista tudo com filtros e valida se as conexões apontam para registros reais.

O mais importante: o agente de IA não precisa mais vasculhar o chat. Ele roda comandos simples para consultar o estado do projeto.

Em vez de pedir que a IA "leia a conversa e entenda", você dá instruções diretas:

docs list --project=payment-service --role=spec
docs check

O agente vê o que foi decidido, o que está em andamento, o que está bloqueado. E pode modificar esse estado através de comandos estruturados, não editando arquivos manualmente.

Agente Novo, Estado Conhecido

Aqui está a diferença prática. Quando uma nova sessão começa, o agente acorda sem contexto. Com estado estruturado, ele faz o seguinte:

1. Roda docs list para ver o que está ativo
2. Lê o log de implementação do dia anterior
3. Consulta a especificação para saber o que deve construir

Sem precisar reconstruir decisões de mensagens antigas. O chat antigo vira descartável. O estado real fica no repositório.

Quando Isso Faz Diferença

Esse padrão ajuda quem trabalha com ferramentas de pair programming com IA em projetos que duram vários dias. Também serve para equipes que precisam de entendimento compartilhado sobre decisões tomadas e pendências. E funciona em pipelines de CI/CD que precisam validar a coerência do projeto.

Não substitui Git, testes ou revisão de código. É a camada que mantém o desenvolvimento assistido por IA coerente ao longo do tempo.

A Verdade Pouco Glamurosa

O melhor dessa abordagem é o quanto ela é simples. Você usa Markdown, Git e linha de comando — ferramentas que já fazem parte do dia a dia. Não inventa paradigma novo nem precisa de IDE especial.

Casos de borda mostram que funciona: se o agente corrompe uma relação, a validação pega. Se esquece um registro arquivado, o comando de listagem mostra. O índice é o contrato — ou está válido, ou não está.

É o tipo de infraestrutura que parece óbvia depois que existe. Mas é o que separa "a IA mais ou menos funcionou" de "a IA entendeu o projeto e entregou".