CLAUDE.md para equipes: como transformamos as memórias de IA de cinco pessoas em regras compartilhadas

Todo desenvolvedor que trabalha com um agente de programação de IA está, discretamente, elaborando um manual de regras. A memória automática do Claude Code salva anotações das suas correções à medida que trabalha, seu perfil pessoal ~/.claude/CLAUDE.mdcoleta as preferências que você se cansou de repetir, e algumas habilidades pessoais se desenvolvem em torno das tarefas que você realiza todas as semanas. Tudo isso é privado. A memória automática fica na máquina local e é específica para cada repositório: os agentes dos seus colegas de equipe nunca têm acesso a ela.

Assim, cinco pessoas aprendem a mesma lição separadamente, cada uma em um arquivo particular. As regras de que sua equipe mais precisa já estão registradas. Só que não estão registradas em nenhum lugar compartilhado.

Em setembro, nós cinco realizamos uma “colheita de memórias”: reunimos esses arquivos pessoais e discutimos quais regras mereciam se tornar regras da equipe. Veja como fizemos isso, quais regras foram selecionadas, onde cada uma foi colocada e o que descobrimos, incluindo as regras que avaliamos erroneamente.

O que é uma colheita de memórias

Uma “colheita de memórias” é um exercício em equipe que envolve três etapas. Cada pessoa exporta suas memórias de agente privado e suas regras pessoais. Um revisor agrupa as entradas das exportações de todos. As regras que várias pessoas registraram de forma independente são propostas para os arquivos compartilhados: o projetoCLAUDE.md, AGENTS.md, uma habilidade compartilhada ou uma verificação no CI.

É a etapa de manutenção que a engenharia de contexto costuma ignorar. Já argumentamos anteriormente que os arquivos de contexto precisam de um ciclo de feedback impulsionado pelos agentes que os utilizam. Uma “colheita” é esse mesmo ciclo aplicado às pessoas, em vez de às sessões: trata-se da Etapa 4 do ciclo de vida do feedback do agente, voltada para as anotações que já ficaram retidas na memória privada.

As ferramentas disponíveis para isso são escassas. Das dez ferramentas de programação de IA que analisamos, apenas a Devin oferece um ciclo que monitora uma sessão, propõe uma regra compartilhada e aguarda a aprovação de um usuário. As demais dependem de arquivos que as pessoas escrevem e enviam manualmente, ou de conjuntos de instruções que um administrador distribui. Nenhuma delas analisa as memórias pessoais de várias pessoas para identificar regras em potencial para a equipe.

O que fizemos

Em 17 de setembro de 2026, cinco desenvolvedores executaram, cada um, um script de exportação em suas próprias memórias do Claude Code, em seu “global” pessoal eCLAUDE.md em suas habilidades pessoais. O script não transmite nada. Cada um leu seu próprio pacote, excluiu tudo o que não deveria ser transmitido e só então o enviou.

Os cinco pacotes continham 444 entradas de memória, 5 CLAUDE.mdarquivos globais, 13 habilidades pessoais e 194 linhas descrevendo as habilidades instaladas em cada repositório. Um revisor, um agente de IA que trabalhava em conjunto com um humano, agrupou as entradas dos cinco pacotes e elaborou uma proposta para cada grupo. Em 22 de setembro, quatro de nós votamos em duas páginas de revisão. As promoções foram enviadas como pull requests comuns em três repositórios: nosso repositório principal de produtos, um repositório de jogos e nosso plugin de habilidades compartilhadas.

Os pacotes ficam em um ramo que nunca é mesclado. Apenas as promoções são enviadas, cada uma como um PR separado para o repositório ao qual se refere, revisadas como qualquer outra alteração.

O que leva à promoção: considere o número de autores, não o de trabalhos

Uma regra é promovida quando duas ou mais pessoas a registraram de forma independente. Conte os autores distintos, nunca as entradas. Essa única regra fez a maior parte do trabalho e precisou de três ajustes antes de se tornar confiável.

Leve em conta o usuário mais ativo. Um pacote continha 251 das 444 entradas, distribuídas por 10 repositórios. Todos os demais contribuíram com 37 a 68 entradas, distribuídas por 1 a 4 repositórios. Portanto, “dois autores” geralmente significava “nosso usuário mais ativo do agente mais um”, e um agrupamento sem o usuário mais ativo era mais raro e constituía uma evidência mais forte. Marcamos esses agrupamentos separadamente.

Uma pessoa equivale a um autor. Um desenvolvedor exportou dados de duas máquinas. Isso conta como um autor. Uma pessoa repetindo a mesma regra três vezes é uma forma de ênfase. Para haver corroboração, é necessária uma segunda pessoa.

Fontes compartilhadas não são independentes. Os arquivosCLAUDE.md globais de duas pessoas eram idênticos, byte a byte, em suas quatro primeiras seções, pois ambas haviam adotado o mesmo texto publicado: as diretrizes de codificação de Andrej Karpathy para agentes de IA. Ambas estavam citando um único documento de origem, portanto isso foi considerado uma única fonte. Qualquer cluster futuro que se baseie apenas nesse par será comparado primeiro com o texto original.

Para classificar cada agrupamento, utilizamos os quatro operadores do ExpeL, um método de pesquisa para agentes que aprendem regras a partir da experiência: ADICIONAR uma nova regra, VOTAR A FAVOR de uma que já conste nos documentos compartilhados, VOTAR CONTRA uma que seja contrariada pelas evidências, EDITAR uma que esteja próxima, mas incorreta. Votar contra e editar são tão importantes quanto adicionar. Uma coleta que só sabe adicionar regras deixa seus arquivos de contexto mais longos, mas nunca mais corretos.

O critério de seleção determina o que o revisor propõe, e não o que a equipe pode adotar. Uma segunda página de revisão listava os fatos de um único autor que pareciam valer a pena compartilhar, e os participantes da sala votaram em cada um deles. Eles foram aceitos porque as pessoas os leram e concordaram.

Onde cada regra deve ser definida

Chegar a um acordo sobre uma regra é metade da decisão. A outra metade é a sua “altitude”: o nível em que ela será efetivamente lida e aplicada. (Nosso capítulo do guia sobre onde uma correção deve ser aplicada aborda o processo na íntegra.) Para as regras coletadas, esta é a tabela de roteamento que utilizamos:

A regra é	Isso deve ficar em	Por que
Um fato constante: cada sessão neste repositório precisa de	O projeto CLAUDE.md	Ele é carregado no início de cada sessão
O mesmo vale para todas as ferramentas de IA que a equipe utiliza	AGENTS.md, importado de CLAUDE.md	Um arquivo que todas as ferramentas conseguem ler
Aplicável apenas a uma parte do código-fonte	Uma regra com escopo de caminho em .claude/rules/	Carrega apenas quando o agente seleciona os arquivos correspondentes
Um procedimento utilizado em vários repositórios	Uma habilidade em um plug-in compartilhado	Os plug-ins contêm habilidades, não CLAUDE.md
Um procedimento específico para um repositório	Uma habilidade de repo	Carrega quando a tarefa exigir
Os detalhes da referência são muito longos para cada sessão	Um documento, além de uma dica de uma linha em CLAUDE.md	Um documento que não é carregado é um documento que o agente nunca lê
Verificável mecanicamente	Uma regra do Lint, um teste ou uma verificação de CI	A prosa adverte; um cheque a impede
Sobre o que o agente faz, como comandos do Git ou encerrar processos	Um gancho em um plug-in compartilhado	O CI nunca vê as ações do agente; um gancho interrompe o comando
Uma preferência em relação às suas próprias ferramentas, máquina ou orçamento	Sua experiência pessoal CLAUDE.mdou sua lembrança	Isso não é um fato relacionado ao código-fonte

Há dois pontos que merecem destaque. Primeiro, um plugin do Claude Code pode incluir habilidades, agentes e hooks, mas não procedimentosCLAUDE.md. Os procedimentos abrangem vários repositórios em um plugin; as regras permanentes devem ser definidas em cada repositório que precise delas.

Em segundo lugar, só exclua a memória privada depois que o destino for carregado automaticamente. Se você mover uma regra para um documento que não é carregado, o agente simplesmente a esquece. Quando uma regra era movida para documentos de referência, a memória privada era reduzida a um ponteiro, em vez de desaparecer.

O que fazer com as contradições

As memórias agrupadas apresentam discrepâncias. Resolva uma contradição com base no escopo sempre que possível, substitua o lado desatualizado e deixe as divergências relacionadas a preferências em um grupo explícito de itens não resolvidos.

Verifique o escopo primeiro. Uma contradição dizia respeito à forma de configurar dependências em uma segunda cópia de trabalho de um repositório: duas pessoas haviam escrito regras opostas. Ambas estavam corretas em seus respectivos repositórios. Uma alteração posterior em uma habilidade compartilhada resolveu a questão para ambas, e a memória do nosso usuário mais ativo acabou sendo a versão desatualizada; portanto, é essa que deve ser substituída, em vez de ser discretamente excluída.

Substitua, nunca sobrescreva. Quando uma regra compartilhada for alterada, adicione a nova regra com a data e mantenha a antiga legível, da mesma forma que um registro de decisão de arquitetura substitui uma decisão anterior. O próximo revisor poderá ver o que mudou e por quê.

Mantenha uma questão em aberto. A segunda contradição dizia respeito a qual modelo de IA os subagentes deveriam usar. Duas pessoas queriam um modelo de primeira linha para cada subagente; outra escolhia os modelos de acordo com a tarefa. A votação ficou dividida em dois votos de “discutir” e dois de “concordar”. A questão permaneceu propositalmente sem solução, pois se trata de quanto cada pessoa está disposta a gastar por conta própria, e não de um fato relacionado à base de código. Isso permanece nas regras particulares de cada pessoa.

O que a colheita revelou

Quinze promoções foram aprovadas na primeira página de revisão: 11 para nosso repositório principal de produtos (duas delas também se aplicavam ao repositório de jogos), três para o plugin de habilidades compartilhadas e uma corrigindo o próprio exportador do Harvest. Outras dezessete foram aprovadas a partir da segunda página: fatos de autor único que o grupo concordou em compartilhar, além de dois conjuntos que a primeira contagem havia registrado erroneamente como de autor único. Na segunda página, um item foi rejeitado, três foram deixados em espera para mais discussão ou para um local mais adequado, e três foram aprovados, mas precisam de código ou de uma habilidade, em vez de apenas uma linha de documentação. A questão sobre o modelo permaneceu em aberto.

O grupo de comentários mais recorrente dizia respeito aos comentários. Três autores, um dos quais havia escrito isso quatro vezes: os comentários apresentam fatos duradouros sobre o código; eles nunca narram a alteração ou seu histórico. Um autor observou que os subagentes são os infratores mais comuns.

A questão mais ampla dizia respeito às evidências. Quatro dos cinco autores já haviam escrito uma versão da frase “verifique antes de afirmar; uma busca sem sucesso não é evidência de ausência”. As alegações dos revisores são hipóteses, e não conseguir reproduzir um bug não prova que ele não possa ocorrer. Era o que mais se aproximava de uma regra interna compartilhada pela equipe, mas não estava registrado em nenhum documento compartilhado.

Um conjunto de casos relacionado, de dois autores, tratava de um estado desatualizado do Git: um branch local muito atrasado em relação ao remoto, uma pesquisa realizada no checkout errado. Cada um dos cinco incidentes resultou em uma afirmação falsa, mas apresentada com convicção, que chegou a constar na mensagem de commit ou na descrição de um PR.

A coleta corrigiu orientações incorretas, não apenas orientações ausentes. Três constatações foram solicitações de VOTO NEGATIVO ou EDIÇÃO em relação a orientações que já tínhamos:

• Nosso guia AGENTS.mdorientou os agentes a aplicar a correção em todo o repositório aolint:fix alterar regras de lint. Três pessoas haviam alertado separadamente contra isso: o repositório não passa no lint na versão inicial; portanto, uma correção em todo o repositório oculta seu diff em alterações de formatação não relacionadas.
• Uma skill compartilhada que, segundo se diz, recorre à API em caso de falhagh pr edit. Ela não falha: exibe um aviso não fatal, retorna o código de saída 0 e mantém a solicitação de pull inalterada. Um mecanismo de fallback baseado em uma falha que nunca ocorre nunca é executado. Três autores se depararam com isso em três repositórios.
• Um aviso já existente na documentação do nosso agente classificava um erro no banco de dados como “seguro” porque ele gerava um erro imediatamente. Três pessoas cometeram esse erro em três tabelas diferentes. Em um dos casos, o erro passou pela revisão, passou pela integração contínua (CI) e só causou uma falha durante a execução.

Algumas regras acordadas deveriam fazer parte de uma verificação automática. O aviso do banco de dados acima é verificável automaticamente: um teste que lesse o esquema encerraria toda a aula, enquanto o documento apenas alerta sobre isso. “Nunca edite manualmente o arquivo de esquema gerado” foi considerado verdadeiro e ainda está em espera, pois a redação não é a forma correta de impor essa regra. Dois outros itens acordados já foram redigidos como procedimentos passo a passo, o que os torna habilidades. Vários itens saíram da votação como tickets, em vez de documentação.

Uma regra pode ser um comportamento padrão e, mesmo assim, precisar ser escrita. Duas pessoas escreveram, independentemente uma da outra, “nunca faça commit ou push a menos que seja solicitado”. Uma delas resumiu bem: “escrever arquivos não significa ter permissão para fazer commit deles”. Qualquer agente já deveria se comportar dessa maneira. Duas pessoas escreveram isso porque a situação continuava ocorrendo mesmo assim, o que justifica torná-la explícita.

A coleta encontrou um bug na própria coleta. Cada pacote trazia um carimbo de versão, de modo que a revisão se recusava a comparar pacotes criados por regras de coleta diferentes. O carimbo provinha da versão do plug-in, e não do exportador. Todos os cinco pacotes foram criados por scripts idênticos em nível de byte e marcados com três versões diferentes. A barreira de segurança nunca poderia ser acionada em caso de uma mudança real nas regras, mas seria acionada a cada atualização de plugin não relacionada. Essa correção foi uma das quinze.

Com que frequência executá-lo

A primeira coleta é a mais trabalhosa: meses de anotações pessoais, analisadas em uma única sessão concentrada. Depois disso, reserve cinco minutos para uma verificação rápida durante uma reunião regular de sincronização da equipe: há alguma novidade que mais de uma pessoa tenha anotado?

Cinco modos de falha a serem considerados no projeto:

• Somente gravação: as regras são promovidas e ninguém verifica se o comportamento do agente mudou.
• Obsoleta e sem responsável: uma regra compartilhada permanece em vigor por mais tempo do que o código que ela descreve.
• Promovido no n=1: a opinião veemente de uma pessoa se torna uma regra da equipe simplesmente porque foi ela quem a escreveu primeiro.
• Um documento que reúne quatro tipos de conteúdo: normas permanentes, procedimentos, referências e histórico, tudo em um único arquivo que ninguém lê do começo ao fim.
• Abstraída a ponto de se tornar inútil: uma regra generalizada a tal ponto em relação ao incidente que a originou que já não indica ao agente o que fazer.

O que mudaríamos da próxima vez

A comparação do nosso processo com ferramentas que aprendem sozinhas revelou quatro lacunas. Estamos incluindo uma correção para cada uma delas na coleta de dados antes da próxima execução.

As regras sobre as próprias ações do agente precisam de um gancho. Duas de nossas promoções diziam respeito ao que o agente faz, e não ao que o código determina: subagentes fazendo commit no branch errado e um encerramento geral do processo que desativou o shell no qual ele estava sendo executado. A CI nunca detecta nenhuma dessas situações. Um gancho pode interromper o comando antes que ele seja executado, e um plug-in compartilhado o leva para todas as máquinas que o instalam.

Uma regra que as pessoas continuam aprendendo de novo e de novo não está funcionando. Esse é o modo de falha de “somente gravação” mencionado acima, e uma coleta pode medi-lo. Se uma regra foi promovida da última vez e as pessoas ainda a gravaram em sua memória privada depois disso, a linha compartilhada não está funcionando. Esse é o sinal para tirá-la do texto e colocá-la em um gancho ou em uma verificação.

Verifique se uma memória ainda está correta antes de promovê-la. Uma memória alertou sobre um bug ativo que já havia sido corrigido. Se fosse promovida, teria gerado um aviso falso para todos. Qualquer elemento que mencione um arquivo, uma função ou um bug será verificado primeiro em relação ao código atual.

Uma coleta de dados reflete apenas o que as pessoas registraram por escrito. O número de registros variou de 37 a 251 por pessoa, o que diz mais sobre quem registra as coisas por escrito do que sobre quem enfrenta problemas. Da próxima vez, cada pessoa pode primeiro pedir ao seu agente para ler as transcrições de suas próprias sessões recentes e listar as correções que a memória não consegue abranger. Elas decidem quais salvar. As transcrições ficam fora do pacote compartilhado.

Também pensamos em deixar que um agente cuidasse de tudo: monitorar as sessões, criar suas próprias regras e carregá-las automaticamente. Algumas ferramentas já funcionam dessa maneira, e nosso mapa de ciclos de feedback de agentes inclui uma delas. Isso funciona bem para a configuração de uma única pessoa. No entanto, quando se trata de regras das quais toda uma equipe depende, ainda queremos que as pessoas leiam cada uma delas e votem.

Execute um manualmente

Você não precisa de ferramentas especiais. Nossa exportação consistiu em um pequeno script, mas cada etapa pode ser feita manualmente:

1. Exportar de forma privada. Cada pessoa copia sua pasta de memória automática (no Claude Code, ~/.claude/projects/<project>/memory/), seus ~/.claude/CLAUDE.mde quaisquer habilidades pessoais em uma pasta por pessoa.
2. Faça uma triagem antes de compartilhar. Cada pessoa deve excluir tudo o que não deve ser divulgado: credenciais, dados de clientes, qualquer informação sobre um colega identificado. Nada sai sem que seu proprietário tenha lido.
3. Agrupar por significado. Um revisor, seja ele humano ou um agente, agrupa as entradas que expressam a mesma ideia com palavras diferentes e registra quem escreveu cada uma delas.
4. Conte os autores distintos. Um candidato é aquele que tem dois ou mais autores independentes. Agrupe os computadores de uma mesma pessoa, desconsidere o texto compartilhado do upstream e observe quais clusters permanecem mesmo sem o seu usuário mais ativo.
5. Classifique e encaminhe. Identifique cada candidato como ADD, UPVOTE, DOWNVOTE ou EDIT e, em seguida, atribua a ele um destino a partir da tabela de roteamento acima.
6. Liste as contradições separadamente. Resolva-as com base no escopo sempre que possível; deixe o restante sem solução e indique isso.
7. Vamos colocar a questão em votação. Coloquem as propostas em uma página e os fatos apresentados por um único autor em outra, e decidam juntos.
8. Trate cada promoção como uma ação de relações públicas em relação ao repositório ao qual ela se refere. Mantenha os pacotes brutos fora do main.

Perguntas frequentes

O que é uma “colheita de memórias”?

A coleta de memórias é uma prática em equipe para agentes de programação de IA: cada desenvolvedor exporta as memórias e regras pessoais de seu agente; um revisor agrupa as entradas das exportações de todos; e as regras que várias pessoas escreveram de forma independente são transferidas para arquivos compartilhados, como CLAUDE.mdou AGENTS.md. Essa é a etapa de manutenção em nível de equipe da engenharia de contexto.

Quantas pessoas precisam concordar para que uma regra seja incorporada ao CLAUDE.md?

Utilizamos dois ou mais autores independentes. Conte pessoas distintas, não entradas: uma pessoa que reescreva uma regra três vezes, ou que faça o upload a partir de dois computadores, ainda conta como um único autor. Duas pessoas que copiaram o mesmo texto publicado também não são consideradas independentes. O limite determina o que é proposto; a equipe ainda vota em cada promoção.

O que deve constar no CLAUDE.md da equipe e o que deve ficar na memória pessoal?

É um fato incontestável que, a cada sessão, o conteúdo desse repositório deve pertencer ao projetoCLAUDE.md, pois ele é carregado automaticamente. Os procedimentos vão para a seção “skills”, os detalhes de referência vão para a seção “docs” com um link, e tudo o que uma máquina possa verificar vai para uma regra de lint ou um teste. As preferências relacionadas às suas próprias ferramentas, máquina ou orçamento permanecem pessoais.

As regras da equipe devem ficar no arquivo CLAUDE.md ou no AGENTS.md?

As regras que todas as ferramentas de IA devem seguir vão em AGENTS.md; as instruções específicas do Claude ficam em CLAUDE.md. O Claude Code pode ser lido AGENTS.mddiretamente ou por meio de uma importação@AGENTS.md, de modo que um único arquivo pode atender a todas as ferramentas que sua equipe utiliza.

O que você faz quando as versões de dois desenvolvedores se contradizem?

Verifique primeiro o escopo: ambas as opções podem ser válidas em repositórios diferentes, e uma mudança posterior na ferramenta pode ter resolvido a questão. Se um dos lados estiver desatualizado, substitua-o em vez de sobrescrevê-lo. Se a divergência for uma questão de preferência, e não um fato relacionado à base de código, deixe-a sem solução e mantenha-a nas regras particulares de cada pessoa.

Com que frequência uma equipe deve realizar uma limpeza de memória?

Realize uma sessão delimitada para esvaziar a fila de tarefas pendentes e, em seguida, mantenha uma verificação rápida de cinco minutos durante uma reunião regular de sincronização da equipe para identificar novos candidatos. A primeira rodada é a mais dispendiosa; depois disso, o volume deve ser pequeno.

Que seja uma decisão da equipe

Em uma coleta de memórias, a equipe decide quais regras passam a ser compartilhadas; o revisor apenas faz propostas. A exportação, o agrupamento e a contagem podem ser automatizados. A votação, porém, não pode — nem deve — ser automatizada. Quais regras são vinculativas para todos, quais permanecem pessoais e quais divergências ficam em aberto são decisões que cabem às pessoas que terão de conviver com elas. É o mesmo argumento que apresentamos no relatório “existe, a sala não”: uma visão agregada só é útil quando as pessoas responsáveis pelas correções decidirem em conjunto.

Essa é uma retrospectiva com diferentes fontes de informação. Quando nossos agentes de IA apresentaram seus próprios itens para a retrospectiva, as evidências vieram de suas sessões. Desta vez, elas vieram de nossas próprias anotações particulares, e a sala desempenhou a mesma função: identificar o padrão, definir o nível de importância e atribuir um responsável a cada ponto. Se sua equipe já realiza uma retrospectiva regular, uma “colheita de memórias” pode ser incluída como um item da pauta. A prática completa está em nosso guia para retrospectivas de agentes de IA.

Fez sua própria colheita ou acha que nosso limite está errado? Conte para a gente: ai-discussion@teamretro.com.