Desenvolvedor transfere o contexto de um agente de IA dos chats para o repositorio com doubled-graph

Quando voce troca o Claude Code pelo Codex ou por outra ferramenta, o primeiro pensamento costuma ser como transferir o historico dos chats. O autor de uma analise publicada no Habr considera essa a pergunta errada. Ha seis meses, ele mantem o contexto do projeto nao nas conversas, mas no repositorio, e afirma que trocar de agente deixou de ser doloroso.

Por que o historico de chats e uma memoria ruim

Uma conversa preserva a discussao sobre o projeto, nao as decisoes finais. Ela contem ruido, repeticoes, ideias abandonadas e mensagens educadas de "OK". O novo agente precisa ler e reinterpretar tudo isso, sem ter como verificar a interpretacao: o chat nao possui contratos, limites de modulos ou criterios de aceitacao que possam ser comparados com o codigo.

Ha ainda uma segunda desvantagem. Reconstruir o contexto vira um imposto cobrado a cada nova sessao. Sempre que a ferramenta muda, e preciso reunir o conhecimento novamente e descobrir qual das mensagens contraditorias foi a definitiva.

O autor propoe um teste simples de portabilidade. Abra o repositorio em um agente que nunca tenha visto o projeto e forneca uma unica instrucao: "Leia o que existe aqui e explique como o projeto esta estruturado e o que esta acontecendo nele agora." Se a resposta for precisa, o contexto realmente vive no repositorio.

O que fica no repositorio

A base e a metodologia GRACE, de osovv, distribuida sob a licenca MIT: a intencao, os limites dos modulos e as verificacoes ficam armazenados junto ao codigo. O autor acrescentou tres elementos: um fluxo de migracao para codigo existente, um grafo de chamadas por meio do CodeGraphContext e um wrapper MCP. O conjunto forma o utilitario doubled-graph.

O codigo recebe comentarios-ancora emparelhados. Cada modulo tem um MODULE_CONTRACT com objetivo, escopo e dependencias; cada funcao tem um CONTRACT com entradas, saidas e efeitos colaterais; e a logica e dividida em blocos. O campo LINKS conecta um arquivo a um modulo, de modo que um grep comum por um identificador como M-AUTH-VALIDATE entrega ao agente alguns paragrafos relevantes em vez de 40 arquivos. Um linter verifica se as ancoras estao emparelhadas, se sao unicas e se correspondem as exportacoes reais.

Ha dois grafos. Declared descreve a intencao e fica em .grace/graph/. Computed e construido a partir da AST e mostra os fatos: quem chama quem. A ferramenta detect_changes compara os dois e encontra divergencias: codigo sem modulo, modulo sem codigo, dependencias desatualizadas, modulo sem verificacao ou arquivo sem anotacoes. Um hook post-commit atualiza o grafo computed, enquanto detect_changes pode ser executado no pre-commit ou no CI. Antes de editar, o agente tambem pergunta o que sera afetado pela mudanca.

Migracao de projetos antigos

Metodos do tipo "primeiro a especificacao, depois o codigo" geralmente fracassam em projetos com dez anos de idade, nos quais nao existe especificacao, mas o codigo funciona. Por isso, ha dois modos. Em migration, o codigo e a fonte da verdade: o agente reconstroi a intencao, anota os arquivos e passa por gates de aprovacao humana. Em post_migration, os artefatos sao a fonte da verdade, e qualquer divergencia e considerada suspeita. Nesse caso, ha tres saidas: atualizar o artefato por meio de um pacote de mudancas, reverter o codigo para adequa-lo ao contrato ou registrar o problema em DRIFT.md e bloquear o modulo.

Uma ideia separada e o belief-state. Em pontos criticos, o agente registra qual premissa nao obvia adotou, junto com uma ancora e um session_id. Quando um log de producao surgir meses depois, sera possivel reconstruir o estado da IA naquele ponto.

Limitacoes e conclusao

O autor e franco sobre as limitacoes: nao ha numeros, ele nao realizou um experimento controlado e tudo se baseia em impressoes subjetivas. A metodologia tambem e exigente: ele afirma que os dez principios precisam ser adotados integralmente e que uma implementacao parcial nao compensa o esforco. As anotacoes com ancoras acrescentam ruido ao codigo, enquanto os gates de aprovacao tornam correcoes rapidas mais lentas. Para projetos pequenos, isso pode ser excessivo.

Ainda assim, a ideia merece atencao mesmo sem a metodologia completa. Se voce trabalha com varios agentes, coloque no repositorio pelo menos os contratos dos modulos, o grafo de dependencias e a lista de verificacoes, e deixe o CI detectar divergencias em relacao ao codigo. Testar o resultado e facil: forneca a um agente novo aquela mesma instrucao unica. Para experimentar, execute pipx install doubled-graph, depois doubled-graph setup e use a instrucao inicial do diretorio prompts.