Meu backup do Claude Code nunca falhou — e ficou sete dias sem copiar 11,7 MB

Um script copia o meu ~/.claude/ todo dia às 09:10 e vinha rodando havia meses sem um erro sequer. Nenhum alerta, nenhuma linha vermelha no log. Mesmo assim, o banco vetorial da minha memória — 11,7 MB, o índice do MemSearch — passou cerca de sete dias sem cópia nenhuma. O script rodou em todos esses dias. Só não tocou naquele arquivo em nenhum deles.

O que dói não é o buraco de sete dias. É que quatro documentos afirmavam que o arquivo estava coberto: o cabeçalho do script, a tabela de manifesto do README, a nota de inclusões logo abaixo dela e as instruções de restauração. Nenhum estava certo. A documentação concordava consigo mesma e discordava do código — e foi essa concordância que me fez parar de conferir.

O problema não era esquecer o backup, era o diretório crescer depois dele

O medo padrão em backup é o esquecimento: ninguém configurou, ninguém agendou. Aqui o agendamento existe, roda e escreve no log — e ainda assim nasce coisa nova dentro do diretório monitorado sem que o manifesto, uma lista fixa escrita num dia específico, saiba que ela existe.

Já aconteceu duas vezes. Na primeira, um diretório novo de memória e taxonomia apareceu junto com uma ferramenta que instalei; eu não atualizei a lista de diretórios espelhados no mesmo dia, e ele passou dois dias existindo só na máquina local. Dois dias é pouco — só não foi mais por sorte.

A segunda foi o banco vetorial, e durou uma semana. O padrão é idêntico: um backup que roda sem erro todo dia prova uma coisa só — que cobre o que existia no dia em que a lista foi escrita. Não o que existe agora.

O que roda hoje é uma lista fixa de diretórios, copiada todo dia às 09:10

O mecanismo é modesto de propósito: um script Python de sincronização, hoje na versão 1.2.0, revisada em 2026-06-04. O Agendador de Tarefas do Windows dispara às 09:10, com pythonw.exe, sem janela de console na tela.

A cópia obedece a três listas fixas: arquivos avulsos — o CLAUDE.md global —, diretórios espelhados inteiros (hooks, memória, skills, agentes, comandos, mais a memória por projeto) e, criada depois do segundo incidente, uma só para binários que vivem na raiz. Antes de qualquer commit, os valores sensíveis viram um marcador neutro — o script reconhece padrões de token conhecidos e qualquer valor comprido o bastante para parecer credencial, e o marcador não deixa escapar nem o nome da chave.

O destino são duas camadas. A cópia espelhada vai para um repositório Git meu, o Project_Setup, e o commit só sai quando existe diferença real. Separada dela, uma camada de backup mais ampla roda todo dia à noite para a nuvem e alcança até o banco vetorial que o git ignora. Cada execução deixa rastro num log rotativo de 1 MB, cinco arquivos mantidos.

Manter essa lista escrita item por item tem uma vantagem que eu não trocaria: dá para abrir o script e ler, em vinte segundos, o que é copiado — sem glob, sem regra implícita. O preço vem colado nela: alguém precisa editar a lista toda vez que uma ferramenta nova cria pasta dentro de ~/.claude/. E o preço nunca é cobrado no dia da omissão. Ele chega semanas depois, quando o diretório novo já guarda coisa que faz falta.

O arquivo de 11,7 MB morava na raiz, e a varredura só descia pelos subdiretórios

O segundo incidente foi o mais grave, e a causa é quase geométrica. O banco vetorial não fica dentro de memory/, nem de skills/, nem de nenhum diretório da lista: mora na raiz de ~/.claude/, um nível acima de tudo que o script percorria. A varredura entrava em cada diretório espelhado e ia embora; o arquivo ficava ali, sem ser alcançado.

A correção óbvia teria criado um problema pior. Mover o arquivo para dentro de um diretório já espelhado resolveria o backup e quebraria a volta: a ferramenta que lê esse índice espera encontrá-lo na raiz, não dentro de memory/. O conserto que ficou de pé foi outro — uma categoria nova no script, específica para binários de raiz, que entrou junto com a versão 1.2.0.

O que mudou o meu jeito de ler documentação foi a concordância entre os quatro documentos. Um README em branco teria me obrigado a abrir o script e conferir. Quatro afirmações batendo entre si fizeram o contrário: me deram permissão para não conferir.

O que não tem cópia nenhuma hoje é a configuração legada do Claude Code

O arquivo ~/.claude.json guarda a configuração global legada do Claude Code: as declarações dos servidores MCP conectados, os plugins instalados, permissões, a conta vinculada. Esse arquivo não está em nenhuma camada do backup. Nem no script da manhã, nem no espelho em git, nem na cópia noturna para a nuvem. O motivo é o mesmo do incidente anterior: ele vive um nível acima do que as três camadas cobrem. Perdê-lo hoje significa remontar de cabeça cada servidor MCP e cada plugin, sem lista de conferência para saber quando acabou.

A lista de lacunas conhecidas não para aí, e nenhuma tem correção. Um arquivo de histórico de comandos, com cerca de 3,8 MB, não aparece em canto nenhum da documentação — nem como incluído, nem como excluído. Um diretório de planos ficou fora do manifesto e das exclusões explícitas. O alerta de falha cobre só o script da manhã: se a camada noturna quebrar, nada dispara aviso. E a auditoria trimestral que o próprio README do backup manda fazer nunca saiu do papel.

Também nunca restaurei esse backup de ponta a ponta numa máquina limpa. O que testei foi o alerta, com uma falha sintética injetada só para confirmar que o aviso chega até mim. São coisas diferentes, e eu já tratei uma como a outra. Recolocar os segredos exige colar cada valor de volta na mão, a partir do gerenciador de senhas, sem inventário de quais chaves precisam voltar.

O que eu faria diferente é comparar o manifesto com o diretório, não com a documentação

A auditoria que falta cabe em três passos: listar o que existe dentro de ~/.claude/, listar o que o manifesto do script diz copiar e olhar a diferença entre as duas listas. Nada disso pede ferramenta nova. Pede que alguém rode.

Se eu recomeçasse, essa comparação viria antes de qualquer alerta bonito de falha. Alerta responde a uma pergunta estreita: o script quebrou? A comparação responde à que me custou os dois incidentes: o script ainda cobre o que existe? Nas duas vezes em que o meu backup falhou de verdade, ele não quebrou. Rodou com sucesso, em cima de um mapa velho.

Backup que nunca falhou é uma garantia sobre o passado

Enquanto ninguém compara o manifesto com o diretório real, o teste prático não é "rodou hoje sem erro". É este: rode a comparação e veja se aparece, dentro de ~/.claude/, algo que o manifesto não menciona. No dia em que ela rodar pela primeira vez e não trouxer nada novo, meu risco principal deixa de ser estrutural e passa a ser disciplina de manter a lista em dia — problema menor e mais fácil de perceber. Até lá, cada "sucesso" no log é uma afirmação sobre o dia em que a lista foi escrita, não sobre hoje.