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; o 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 própria máquina 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 escritas. 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 delas se encaixou e o que descobrimos, incluindo as regras que julgamos erroneamente.

O que é uma colheita de memórias

Uma coleta de memórias é um exercício em equipe que envolve três etapas. Cada pessoa exporta as memórias de seu 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 na 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 o 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 particulares 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 agrupamento. 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 que ela controla, revisadas como qualquer outra alteração.

O que garante a promoção: considere os autores, não os 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 cluster sem o usuário mais ativo era uma evidência mais rara e mais forte. Marcamos esses clusters separadamente.

Uma pessoa equivale a um autor. Um desenvolvedor exportou dados de duas máquinas. Isso conta como um autor. Uma pessoa repetir a mesma regra três vezes é uma forma de ênfase. Para haver corroboração, é preciso 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 referência, 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, APROVAR uma que já conste nos documentos compartilhados, REJEITAR 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ó consegue 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, não o que a equipe poderá adotar. Uma segunda página de revisão listava os fatos de autoria única 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. (O capítulo do nosso guia sobre onde uma correção deve ser aplicada aborda esse 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: toda 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 toca nos 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
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 dentro de 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 versão do nosso usuário mais ativo acabou sendo a 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 ponta para cada subagente; outra escolhia os modelos de acordo com a tarefa. A votação ficou dividida entre dois “discutir” e dois “concordar”. A questão permaneceu propositalmente sem resoluçã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 na 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 encontrar 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 anotado 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 de “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 incidentes 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 de referência, então 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 deixa 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 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 leia o esquema encerraria toda a classe, 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 do texto 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 muito 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, 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 seria acionada em caso de uma mudança real nas regras, mas seria acionada a cada atualização de plug-in 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 início 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.

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/), suas e~/.claude/CLAUDE.md 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, detalhes 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 de acordo com a 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. Coloque as propostas em uma página, 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 coleta 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 transformadas em 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 incluída no CLAUDE.md?

Utilizamos dois ou mais autores independentes. Conte pessoas distintas, não entradas: uma pessoa que reafirme uma regra três vezes, ou que faça o exportar a partir de dois computadores, ainda é considerada 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, em cada sessão, tudo o que estiver nesse 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 para um teste. 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 toda ferramenta de IA deve seguir devem ser inseridas em AGENTS.md; as instruções específicas do Claude devem permanecer 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 coleta de memórias?

Realize uma sessão limitada para esvaziar a lista de pendências e, em seguida, reserve cinco minutos durante uma reunião regular de sincronização da equipe para verificar se há 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 permanecem 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 “o que existe é a visão agregada, não a sala”: uma visão agregada só é útil quando as pessoas responsáveis pelas correções decidem em conjunto.

Essa é uma retrospectiva com diferentes fontes de informação. Quando nossos agentes de IA enviaram 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 detalhe 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.