Recuperação do Claude Code: Safe Mode, /cd e modelos alternativos

Materiais práticos sobre trabalhar com agentes: documentação Ailoot.

O que mudou no Claude Code em junho de 2026?#

Anteriormente, quando o Claude Code começava a comportar-se de forma estranha — um indicador de carregamento interminável, uma falha ao arrancar, o agente a ignorar as regras em CLAUDE.md, um hook que não era executado sem dar sinal — só havia uma saída: comentar manualmente secções de .claude/settings.json, desativar servidores MCP um a um ou, no pior dos casos, apagar ~/.claude e reinstalar. Num caso descrito, apagou-se ~/.claude e perdeu-se a configuração do servidor MCP, que tinha demorado hora e meia a montar. Mais tarde, percebeu-se que a culpa era de uma linha em CLAUDE.md e que poderia ter sido encontrada em 10 segundos — mas isso só ficou claro depois de uma recuperação completa.

Em junho de 2026, a Anthropic lançou três mecanismos que mudam este cenário. Em resumo, o que chegou e quando:

A seguir, cada mecanismo é explicado passo a passo, juntamente com a ordem pela qual os deve aplicar quando uma sessão do Claude Code descarrila.

O que costuma avariar o Claude Code?#

No exemplo descrito, o CLAUDE.md foi inicialmente criado com 80 linhas — e funcionou durante um mês. No segundo mês, tornou-se evidente que, uma vez por semana, o Claude violava todas as regras definidas: tocava em .env, executava git push --force, remexia em node_modules. Não o fazia de forma maliciosa — simplesmente esquecia-se. Uma vez, o .gitignore foi apagado e a razão não ficou imediatamente clara. Este cenário é abordado com mais detalhe no guia sobre CLAUDE.md.

Quando o CLAUDE.md chega às 400+ linhas, começa a causar problemas silenciosamente: ocupa uma parte significativa da janela de contexto no arranque da sessão e dilui as instruções importantes entre as secundárias. O Claude continua formalmente a ler o ficheiro, por isso, visto de fora, parece que «as regras estão lá, mas não funcionam» — um sinal típico de um contrato demasiado extenso.

Os hooks são a segunda fonte comum de problemas. Os Claude Code hooks têm uma particularidade que a Anthropic não salienta.

Ou seja, sys.exit(1) num hook Python (ou qualquer «falhou com um erro» convencional em Unix) não interrompe o Claude. Só o código 2 é bloqueante. No caso descrito, o hook era considerado uma «proibição absoluta», mas na prática registava uma reclamação e permitia a ação.

Os servidores MCP são a terceira camada e também podem avariar à sua maneira.

O sintoma é muitas vezes igual: os comandos MCP estão disponíveis, mas devolvem failed sem um traceback. Para saber mais sobre a configuração do MCP e como adicionar servidores com claude mcp add, consulte o guia separado.

A quarta fonte é a hierarquia de três níveis de settings.json. Tem ~/.claude/settings.json (nível de utilizador), .claude/settings.json na raiz do projeto (projeto), .claude/settings.local.json (local) e, opcionalmente, definições geridas por um administrador da empresa. Estas são combinadas de acordo com regras de prioridade. Quando alguém adiciona um servidor MCP ao nível do projeto e já tem uma entrada semelhante, mas com uma configuração de arranque diferente, ao nível do utilizador, o resultado é um conflito silencioso que parece significar «o Claude Code está avariado».

Como funciona o --safe-mode e o que desativa?#

A formulação original da Anthropic no changelog da v2.1.169 diz:

A Anthropic esclarece na documentação de configuração do modelo:

Esta é uma ferramenta de diagnóstico, não um «ambiente limpo». O safe mode ajuda a responder a uma pergunta: o problema está no comportamento normal do Claude Code ou nas personalizações adicionadas? Isto faz parte da engenharia de contexto — gerir aquilo que o Claude vê e não vê em cada momento. Se tudo funcionar no safe mode, é evidente que as camadas devem ser verificadas através de uma pesquisa binária. Se não funcionar, o problema está na própria instalação, na autorização, na rede ou na infraestrutura; nesse caso, faz sentido consultar claude doctor e os registos.

O que o safe mode desativa (lista oficial da Anthropic — 5 camadas principais):

• CLAUDE.md em todos os níveis (utilizador / projeto)
• Plugins
• Skills
• Hooks
• Servidores MCP

O que continua a funcionar:

• Autorização (a sua sessão OAuth ou chave de API)
• Seleção do modelo (--model sonnet, --model opus)
• Ferramentas integradas (Read, Write, Bash, Grep, entre outras)
• Permissões
• Estado do Git
• Nomes dos diretórios

Um pormenor importante: o safe mode não desativa as definições geridas nem as políticas de um administrador da empresa. Se trabalha numa equipa em que o Bedrock GovCloud ou uma configuração MDM define availableModels, essas restrições mantêm-se — o safe mode desativa apenas as suas personalizações, não as políticas da empresa.

Como isolar uma camada e encontrar o culpado em 60 segundos?#

Um procedimento de diagnóstico para quando o Claude Code «deixou de ouvir». A versão mínima para todos os comandos abaixo é Claude Code v2.1.169. Se tiver uma versão anterior, atualize primeiro (npm update -g @anthropic-ai/claude-code ou através do instalador nativo da Anthropic).

1. Abra a mesma pasta em que os problemas estavam a ocorrer.
2. Execute claude --safe-mode.
3. Se iniciar sem problemas, verifique o pedido original. Funcionou? Então a culpa é de uma das camadas. Avance para o passo 4.
4. Se continuar avariado no safe mode, não toque nas configurações. Execute primeiro claude doctor; verifique a autenticação, a versão e a existência de instalações em conflito.

Quando o safe mode iniciar sem problemas, ative as camadas uma de cada vez, começando pelo culpado mais provável. A ordem baseia-se na experiência descrita:

1. CLAUDE.md. Execute claude sem safe mode, mas mude temporariamente o nome do ficheiro: mv CLAUDE.md CLAUDE.md.bak. Se funcionar, a causa é esse ficheiro. Depois, pode fazer uma pesquisa binária: mantenha metade das linhas e verifique.
2. Hooks. Abra .claude/settings.json e defina temporariamente [] na secção hooks. Reinicie o claude. Funciona? Então a culpa é de um dos hooks. Ative-os um a um.
3. Servidores MCP. De forma semelhante, em ~/.claude.json ou .claude/settings.json, defina temporariamente a secção mcpServers como um objeto vazio, reinicie e verifique.
4. Skills. Mova .claude/skills/ para uma pasta temporária. Inicie e verifique.

O que significa «mudança temporária de nome»: os ficheiros não são apagados durante o diagnóstico. mv ou git stash permitem restaurar tudo com um comando, caso se conclua que essa camada não era a culpada.

Como mudar a pasta de trabalho com /cd sem perder o contexto?#

Do changelog da v2.1.169, a 8 de junho:

Porque é útil para resolver problemas. Imagine que está na pasta do projeto ~/work/myapp e o Claude Code se comporta de forma estranha. Antes, a única forma de verificar «se funciona de todo» era fechar a sessão, mudar para outra pasta e iniciar de novo. Perdia o contexto, o histórico e a cache do prompt já aquecida. Agora:

# In the same session:
/cd ~/sandbox/test

O Claude muda para a nova pasta e lê o CLAUDE.md que lá exista como uma mensagem, não como substituição do prompt de sistema — ou seja, a cache é preservada. Se tudo funcionar em ~/sandbox/test, é evidente que o problema estava na configuração de ~/work/myapp.

A 12 de junho, a v2.1.176 corrigiu uma regressão desagradável: /cd mostrava o ramo antigo do git até ser feito um reinício completo. Se tiver uma versão anterior, atualize ou simplesmente ignore git status durante as primeiras mensagens após a mudança — será atualizado.

Como configurar modelos alternativos para um erro 529?#

No cenário descrito, uma tarefa longa é executada no Opus num projeto uma vez por semana; ao fim de 10 minutos, a API devolve 529 Overloaded e a sessão falha. Antes, era preciso esperar ou mudar manualmente para Sonnet com --model sonnet, perdendo todo o contexto já aquecido. Num business/ de grandes dimensões, com uma configuração de segundo cérebro, isto demora cerca de vinte minutos de trabalho. Agora existe um mecanismo adequado.

A citação exata da documentação oficial:

E, separadamente, como funciona a cadeia:

Há duas formas de configurar esta opção. Através da CLI:

claude --fallback-model sonnet,haiku

Através de ~/.claude/settings.json:

{
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

Uma observação à parte sobre os limites de pedidos. A Anthropic não encaminha deliberadamente um erro 429 para a cadeia, para impedir que se contorne o limite de pedidos mudando para o modelo seguinte. O modelo alternativo só funciona quando o modelo principal está sobrecarregado, indisponível ou devolve um erro de servidor não repetível (por exemplo, 529 Overloaded). Os limites de pedidos seguem a lógica normal de repetição e espera progressiva.

Mais uma observação — a 12 de junho, a v2.1.174 corrigiu uma regressão: a compactação não respeitava --fallback-model. Se tiver uma sessão longa e houver compactação durante uma sobrecarga, antes desta correção o modelo alternativo não era chamado. Se trabalhar com sessões longas (/compact, /loop durante a noite), atualize pelo menos para a v2.1.174.

O que corrigir quando a culpa é do CLAUDE.md, de um hook, do MCP ou de uma skill?#

Estratégias específicas para cada camada.

Se a culpa for do CLAUDE.md

Abra o ficheiro e verifique o tamanho. Com base na experiência descrita, mantenha o CLAUDE.md ativo com, no máximo, 200 linhas; transfira o resto para routers e documentos de apoio junto ao projeto (a estrutura completa do segundo cérebro está no guia sobre o segundo cérebro). Se tiver 400+ linhas, é quase de certeza o culpado. Passos:

1. Faça uma cópia de segurança: cp CLAUDE.md CLAUDE.md.full.
2. Volte a um modelo curto que funcione. Encontra um modelo pronto a usar no guia «Como configurar o CLAUDE.md».
3. Reinicie o Claude Code. Verifique.
4. Se funcionar, reponha as regras em pequenos blocos de 10–20 linhas, verificando após cada bloco.
5. Encontre o bloco que afeta o comportamento. Reescreva-o como um hook com o código de saída correto (os códigos de saída dos hooks são abordados na subsecção seguinte deste H2).

Se a culpa for de um hook

A questão principal é saber se o código de saída está correto. Os hooks do Claude Code usam:

• Exit 0 — tudo bem; a ação prossegue.
• Exit 1 — um erro, mas não bloqueante. O Claude continua como se nada tivesse acontecido.
• Exit 2 — um erro bloqueante. Só este código interrompe efetivamente a ação.

Se escreveu sys.exit(1) ou exit 1 num hook shell a pensar que estava a bloquear, esse código funciona como uma mensagem de aviso no Claude Code e não interrompe a ação. Mude-o para 2. Para mais informações sobre hooks e como os configurar sem esta armadilha, consulte o guia separado.

O segundo caso comum é um hook devolver JSON inválido em stdout. O Claude Code analisa a resposta do hook como JSON e, se incluir conteúdo adicional (um registo, um indicador de progresso, um emoji), considera-se que o hook falhou e a ação prossegue. Regra: stdout só contém JSON; tudo o resto vai para stderr.

O terceiro caso é um hook que lê algo de ~/.claude/ que o safe mode ocultou. É um cenário normal; a solução não é corrigir o hook com um patch, mas verificar os.environ.get('CLAUDE_CODE_SAFE_MODE') no início e sair com o código 0.

Se a culpa for de um servidor MCP

Sintomas: os comandos MCP estão disponíveis, mas devolvem failed sem um traceback claro. Passos:

1. Execute claude mcp list — que servidores estão definidos?
2. Desative os servidores um a um em ~/.claude.json: mude o nome da chave claude-server-A para _claude-server-A (isto desativa-a sem a apagar).
3. Reinicie o claude. Verifique que chamadas funcionam.
4. Quando encontrar o servidor culpado, verifique o respetivo registo: claude mcp logs <name>.
5. Se for um servidor de terceiros (@modelcontextprotocol/server-postgres e outros semelhantes), verifique se tem uma versão recente. O ecossistema MCP continua em turbulência; os servidores avariam regularmente com as atualizações do Claude Code.

Se encontrar «falhas ao arrancar, e apenas com dois MCP», compare o comportamento no safe mode sem MCP.

Se a culpa for de uma skill

Uma skill é composta por SKILL.md e código em .claude/skills/<name>/. Sintomas: o Claude ignora a skill, aplica-a na altura errada ou aplica-a mas produz resultados sem sentido. Passos:

1. Abra SKILL.md. Verifique a descrição — deve ter 1–2 frases e indicar especificamente quando utilizar a skill. Se disser «um assistente universal para tudo», o Claude não percebe quando a deve invocar.
2. Procure contradições com CLAUDE.md. Se CLAUDE.md disser «escreve sempre testes», mas a descrição da skill disser «utiliza para prototipagem rápida sem testes», há um conflito.
3. Se a skill utilizar comandos externos (npm, python, git), verifique se estão disponíveis no PATH do sistema. Uma skill tem o seu próprio ambiente mínimo.

Se Safe Mode não ajudar: diagnosticar e preservar o estado antes de reparar#

Remover dados do utilizador não é um atalho de diagnóstico. Use as verificações abaixo para identificar a falha; se forem inconclusivas, preserve a evidência e investigue. Qualquer reparação começa por cópia verificada e mantém a conta e a identidade no armazenamento de credenciais existentes. Ordem:

1. claude doctor — diagnóstico automático. A Anthropic escreve na sua documentação:

2. Verifique se há instalações em conflito. Muitas pessoas têm instalada ao mesmo tempo uma versão global npm e o instalador nativo:

3. Verifique se ANTHROPIC_API_KEY está a intercetar a sua sessão OAuth. Esta é uma causa comum de «nada funciona, a chave expirou»:

Solução: execute unset ANTHROPIC_API_KEY na sessão shell atual ou remova-a de ~/.zshrc / ~/.bashrc.

4. Repare só a instalação identificada pelo diagnóstico; preserve antes todo o estado. Uma falha Safe Mode ou doctor inconclusivo não prova que deva remover dados. Pare todas as sessões Claude e outros escritores antes de uma cópia consistente. Mantenha utilizador Unix, HOME, armazenamento de credenciais do sistema e conta Anthropic; não rode chaves nem crie outra identidade.

O exemplo de cópia seguinte é para Linux com GNU tar. Em macOS ou Windows, use uma ferramenta que preserve ACLs, atributos alargados, ligações e metadados da plataforma e verifique o restauro; não assuma suporte de opções exclusivas GNU. O arquivo contém credenciais e transcrições: mantenha-o privado e fora de repositórios.

# Executar como o mesmo utilizador dono do estado Claude, após parar escritores.
set -eu
umask 077
backup_dir=$(mktemp -d "$HOME/.claude-recovery-XXXXXXXX")
set --
if [ -e "$HOME/.claude" ] || [ -L "$HOME/.claude" ]; then
  set -- "$@" .claude
fi
if [ -e "$HOME/.claude.json" ] || [ -L "$HOME/.claude.json" ]; then
  set -- "$@" .claude.json
fi
[ "$#" -gt 0 ] || exit 1
tar --acls --xattrs --numeric-owner -cpf "$backup_dir/claude-state.tar" -C "$HOME" "$@"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$HOME"
sha256sum "$backup_dir/claude-state.tar" > "$backup_dir/claude-state.sha256"
(cd "$backup_dir" && sha256sum -c claude-state.sha256)
mkdir "$backup_dir/restore-check"
tar --acls --xattrs -xpf "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
printf 'Verified recovery directory: %s\n' "$backup_dir"

Todos os comandos têm de passar. O arquivo cobre a árvore .claude inteira existente, incluindo sessões ignoradas/não controladas e estado de plugins, e .claude.json, não só definições Git. Se algum caminho for ligação simbólica ou houver dados noutro local configurado, pare e inclua o destino resolvido na mesma cópia verificada; arquivar só a ligação não copia o destino. O arquivo não inclui macOS Keychain nem outro armazenamento externo de credenciais: mantenha essas identidades no lugar.

Se o diagnóstico identificar especificamente a instalação local antiga como cópia em conflito, mova só essa instalação para a pasta privada de recuperação, sem eliminar configuração e sessões:

# Usar backup_dir verificado no bloco anterior.
if [ -d "$HOME/.claude/local" ]; then
  mv "$HOME/.claude/local" "$backup_dir/legacy-local"
fi

Remova a instalação npm só se o diagnóstico a identificar como conflito e pretender manter a nativa. Use depois o instalador nativo documentado, sem eliminar .claude ou .claude.json:

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor

Em Windows, o comando nativo continua a ser:

irm https://claude.ai/install.ps1 | iex

Restaure separadamente. Pare novamente os escritores. Verifique a soma do arquivo e extraia para uma pasta de recuperação vazia como acima; compare com sucesso antes de usar os ficheiros. Para repor a instalação antiga movida, confirme primeiro que $HOME/.claude/local não existe e mova $backup_dir/legacy-local de volta para esse caminho exato. Restaure um ficheiro de definições diagnosticado a partir da extração verificada só depois de preservar a substituição atual; não sobreponha a árvore inteira cegamente. Sessões, MCP e identidade original ficam preservados. Um retrato Git não cobre transcrições ignoradas/não controladas, credenciais ou metadados do sistema de ficheiros.

O que NÃO deve fazer quando o Claude Code está avariado?#

Não mude as chaves antes do diagnóstico

«A autorização não funciona» deve-se, em 90% dos casos, a ANTHROPIC_API_KEY a intercetar a subscrição, a um erro de UI do hook ou a uma falha do MCP. Mudar as chaves não corrigirá nada disto e causará mais uma hora de inatividade: terá de revogar a chave antiga, emitir uma nova, voltar a assinar o CI com ela e atualizar as variáveis em produção. Execute primeiro claude --safe-mode. Funciona? Então o problema está nas personalizações; não é necessário mexer nas chaves.

Não faça uma reposição completa antes de experimentar o safe mode

Eliminar .claude pode destruir sessões, configuração MCP e outro estado não controlado. Diagnostique primeiro, verifique uma cópia privada e use uma mudança de local reversível só na camada de instalação ou configuração efetivamente implicada.

Não entre em pânico com um erro de UI num hook

Antes de corrigir alguma coisa, verifique se o hook foi realmente executado (através de um registo em stderr ou de uma impressão explícita), em vez de confiar no indicador visual.

Não aumente o código de saída de um hook antes de corrigir a lógica

Quando o seu hook de bloqueio não bloqueia, é tentador definir exit 2 e dar o problema por resolvido. É uma correção funcional, mas esconde outro problema: se o bloqueio não funcionou durante um mês, então passou tudo aquilo que o hook devia proibir. Primeiro, percorra o registo do git e descubra exatamente o que passou. Depois, acrescente o bloqueio. Um bloqueio agora ativo não desfaz o que aconteceu antes.

Não edite o CLAUDE.md de produção sem uma salvaguarda do safe mode

No caso descrito: edita o CLAUDE.md, o Claude começa a comportar-se de forma estranha, executa git diff e vê que alguém também acrescentou um servidor MCP e um hook ao repositório nessa noite. Culpa a sua edição, reverte-a e o Claude continua a comportar-se de forma estranha. Regra: antes de executar git revert, execute claude --safe-mode. Se o problema persistir no safe mode, a sua edição não teve nada que ver com ele; não é preciso revertê-la.

Não acredite que «o Claude corrige o seu próprio MCP»

Um cenário típico: pede ao Claude para «adicionar uma determinada ferramenta ao servidor MCP», o Claude reescreve a configuração funcional, tudo deixa de funcionar e, depois, o Claude passa vários turnos a depurar os estragos que causou — gastando entretanto a quota da sessão. Quando o MCP está avariado, obtenha a configuração manualmente; não deixe essa tarefa para o agente. Parte do arsenal de ferramentas do agente também funciona através do MCP e um MCP avariado significa um diagnóstico avariado.

O que fazer depois de o corrigir?#

Depois de analisar o incidente, não volte imediatamente ao trabalho. Primeiro, acrescente medidas preventivas para evitar que o incidente se repita. Pode perder horas num segundo cérebro (a pasta business/ com a estrutura do projeto) e no CLAUDE.md, e é difícil restaurá-los manualmente — esse é um bom motivo. Conjunto mínimo:

1. ~/.claude/settings.json com permissions.disableBypassPermissionsMode: "disable" — uma proibição arquitetónica do modo de contorno, para que --dangerously-skip-permissions não funcione se for iniciado por engano.
2. Hooks para Read(./env*), Bash(git push --force), Write(./node_modules/**) — ações que têm de ser travadas ao nível da lei, não do desejo.
3. Configuração da sandbox para execuções autónomas longas (/loop, /schedule).
4. /compact com as suas próprias regras sobre o que descartar do contexto, para que o Claude não se esgote.

O esquema completo de proteção em quatro camadas está no guia «Como configurar o Claude Code para não danificar o seu projeto durante a noite». Um guia aborda a prevenção antes de iniciar /loop; o outro trata da recuperação depois de /loop já ter causado danos. São um par lógico.

Materiais práticos: documentação Ailoot.

Mais materiais e ferramentas: Ailoot.