Você começa uma feature no Claude Code. Ele trava em um erro de tipo complicado, então você entrega o mesmo repositório ao Codex, que é melhor nesse tipo de trabalho pesado. O Codex corrige, mas agora não faz ideia de qual era o objetivo da feature, quais arquivos você já havia combinado não tocar, ou o que significa "pronto" nesse contexto. Você reexplica tudo de memória. Dez minutos depois você volta, e o Claude Code também esqueceu. O código avançou. O contexto, não.
Esse é o preço de rodar mais de um agente de programação. Cada ferramenta mantém sua própria memória em seu próprio formato e em sua própria sessão, então no momento em que o trabalho passa de um agente para outro, tudo, exceto o diff, cai no chão. Manter o contexto ao alternar entre agentes de programação significa fazer com que esse contexto viva em algum lugar fora de qualquer agente individual, em um formato que o próximo consiga ler sem que você precise narrá-lo.
Este artigo mostra como fazer isso, usando o Sharkly como fluxo de trabalho: a camada que fica acima dos seus agentes de programação e mantém contexto, progresso, bloqueios, resultados e revisão humana visíveis desde a solicitação até o lançamento. Você já tem agentes de programação. O problema aqui está na costura entre eles, e ela fica mais larga a cada agente que você adiciona.
Por que o contexto não viaja entre agentes
O contexto de uma tarefa de programação vive em três lugares, e apenas um deles é portável.
O primeiro é o arquivo de instruções: CLAUDE.md, AGENTS.md, GEMINI.md. Regras permanentes, convenções, os comandos para rodar os testes. O segundo é o estado da sessão: o histórico do que você e o agente acabaram de dizer, o que ele tentou, o que ele descartou. O terceiro é o próprio artefato, o diff em disco ou a branch.
Apenas o terceiro viaja de graça. Um agente diferente consegue ler o código, mas não consegue ler uma conversa da qual não participou, e não vai ler um arquivo de instruções endereçado a outra ferramenta. Essa é a fronteira que vale declarar claramente: trocar de agente preserva o código e descarta o raciocínio. O commit sobrevive. O "porquê" estava em um buffer de histórico que um agente viu e o próximo nunca verá.
Então manter o contexto durante uma troca são, na verdade, dois trabalhos: tornar as regras permanentes legíveis por todos os agentes, e fazer com que o estado da tarefa em andamento exista como algo que não seja a memória de uma única ferramenta. As próximas seções tratam deles na ordem. (Se a sua dor é perder contexto entre execuções do mesmo agente, esse é um problema relacionado, mas separado, abordado em manter o contexto entre sessões de IA.)
Faça das regras permanentes um único arquivo que todo agente lê
Comece pela vitória fácil. O Claude Code lê o CLAUDE.md, o Codex lê o AGENTS.md, o Gemini CLI lê o GEMINI.md. Mesmo trabalho, três nomes de arquivo. Se você os mantém separadamente, eles se desalinham, e o agente para o qual você trocou agora está seguindo regras desatualizadas enquanto você presume que não.
Escreva as regras uma vez e aponte os outros nomes de arquivo para elas. No macOS ou Linux:
# AGENTS.md is the source of truth; the others are aliases
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md
git add AGENTS.md CLAUDE.md GEMINI.md
Agora todo agente que abre o repositório lê as mesmas convenções, e há um único arquivo para atualizar quando elas mudarem. Mantenha-o curto e objetivo: o comando de teste, os diretórios proibidos, a regra de revisão, como os commits devem parecer. Esse é o contrato compartilhado que cada agente herda no instante em que inicia, não importa para qual deles você trocou.
O modo de falha a observar: colocar detalhes específicos da tarefa nesses arquivos. O arquivo de instruções serve para regras que valem para todas as tarefas do repositório. "Usamos Vitest, não Jest" pertence aqui. "Termine a lógica de retry do checkout e não toque no middleware de autenticação" não pertence; isso é verdade para uma tarefa desta semana e falso na próxima. Misturar os dois faz com que todo agente leia instruções que eram destinadas a um trabalho já entregue.
Carregue o contexto de trabalho, não apenas as regras
O arquivo de regras leva um novo agente até a linha de partida. Ele não diz nada sobre a tarefa em andamento: o que foi decidido, o que está pela metade, o que ainda é incerto. Esse conhecimento é exatamente o que evapora quando você troca, porque ele só existia na sessão do agente anterior.
A solução manual é uma nota de handoff. Antes de trocar de agente, peça ao atual para anotar onde ele está: o objetivo, os arquivos que alterou, o que verificou, e a única coisa sobre a qual não tinha certeza. Cole isso no próximo agente como primeira mensagem. Funciona, e para uma única troca é o suficiente. Vale internalizar o padrão por si só; o formato de uma boa nota é abordado em modelos de handoff de agentes.
O modo de falha é que a nota não vive em lugar nenhum durável. É um parágrafo em um terminal que você vai fechar, ou uma mensagem que você redigita toda vez. Alterne de um lado para o outro duas vezes e você estará mantendo a nota de handoff à mão, na sua cabeça, em três ferramentas. O contexto existe, mas você se tornou o banco de dados onde ele está armazenado. Isso se sustenta para uma tarefa. Não se sustenta quando você está rodando várias, que é onde a abordagem faça-você-mesmo esgota.
Onde a configuração faça-você-mesmo para de escalar
Regras com symlinks mais uma nota de handoff colada levam você longe com um repositório e dois agentes. Adicione um terceiro agente, um segundo repositório, ou uma tarefa que se estende por um dia, e a aritmética se volta contra você. Cada troca é uma exportação e reimportação manual. Cada tarefa tem sua própria linha de "o que está pronto" que só existe onde o último agente a deixou. Nada te avisa que um Agente de backend terminou o endpoint que o Agente de frontend está esperando, porque "avisar" era uma mensagem em um terminal que ninguém está observando.
Nesse ponto, a solução não é uma nota melhor. É tirar o contexto de trabalho dos agentes por completo e colocá-lo em uma Task compartilhada da qual todo agente e pessoa lê e para a qual escreve. Uma Task no Sharkly reúne o objetivo, os critérios de aceitação, o diff, os bloqueios e a discussão em um único registro. Execução, bloqueios, resultados e acompanhamento retornam à linha do tempo dessa Task, então trocar de agente deixa de ser uma exportação. Você reatribui a Task; o próximo agente lê o mesmo registro no qual o anterior escreveu.
É também aqui que a divisão entre humano e agente fica clara. Agentes pesquisam, executam, testam e reportam à Task. Pessoas definem a direção, concedem autoridade e aceitam o resultado. A automação para onde o julgamento da equipe é necessário, e o registro que o próximo responsável lê é o mesmo que um revisor lê. Isso só funciona porque o contexto não está mais preso em uma sessão.
Aqui está o par de decisões honesto. Se você roda um agente em um terminal em um repositório, você não precisa de nada disso; o contexto nunca sai, então não há nada a preservar. Recorra a uma Task compartilhada no momento em que o contexto precisar sobreviver a uma troca, seja essa troca de agente para agente, de agente para humano, ou apenas de você para você amanhã de manhã. Se você quer continuar usando vários agentes de programação em vez de se comprometer com um único ecossistema, essa portabilidade é o ponto: seu fluxo de trabalho sobrevive a qualquer agente que você escolher em seguida, porque o contexto nunca esteve armazenado dentro de nenhum deles. Essa também é a configuração que permite rodar Claude Code e Codex juntos em um mesmo código sem que nenhum dos dois fique cego no handoff, e ela combina naturalmente com worktrees, um checkout por tarefa, para que agentes em paralelo não colidam.
A checklist que você pode seguir hoje
Percorra isto na ordem. As três primeiras não custam nada; a quarta é o que você passa a usar quando as três primeiras param de acompanhar o ritmo.
- Unifique o arquivo de regras. Crie symlinks de
CLAUDE.md,AGENTS.mdeGEMINI.mdpara uma única fonte. Mantenha-o apenas com convenções de todo o repositório, sem detalhes de tarefa. - Escreva uma nota de handoff antes de cada troca. Objetivo, arquivos alterados, o que foi verificado, questão em aberto. O agente atual pode redigir; você cola no próximo.
- Decida a troca pela tarefa, não pelo hábito. Combine o agente com o trabalho à sua frente, usando um guia de roteamento em vez de usar por padrão o terminal que estiver aberto.
- Tire o contexto dos agentes quando as notas pararem de escalar. Assim que você estiver equilibrando mais de dois agentes ou repositórios, coloque o objetivo, o estado e a revisão em uma Task compartilhada, para que trocar seja uma reatribuição, não uma reexplicação.
Se você já roda vários agentes e re-narra o mesmo contexto toda vez que troca, esse é o problema em torno do qual o Sharkly foi construído: um único lugar onde as tarefas, o progresso e os resultados de cada agente permanecem visíveis, para que o contexto sobreviva à troca.
