Aula 24Quando algo dá errado

Objetivos

Ao final desta aula você vai saber:

• Desfazer a mudança que quebrou a página, antes de tentar consertar
• Mostrar o erro ao Claude, colado ou num print, e pedir a explicação em português simples
• Pedir um plano antes do conserto
• Reconhecer as mensagens de erro mais comuns e saber o que fazer com cada uma
• Conferir a instalação com o /doctor e descobrir por que uma regra da casa, uma skill ou um conector parou de funcionar
• Pedir ajuda no lugar certo

Uma hora, algo dá errado. Você aprova uma mudança e o cardápio some da página. Aparece uma mensagem em inglês que você nunca viu. O Claude esquece uma regra da casa. Quase sempre o conserto é simples, e a ordem importa: primeiro desfazer, depois entender e só então consertar, com um plano.

 ↩️ Desfazer      →   💬 Entender         →   🗺️ Planejar o conserto
 (a página volta      (o erro em              (o que vai mudar,
  a funcionar)         português simples)      antes de mexer)

Para esta aula, você precisa da pasta da sua página (a confeitaria, ou a da sua ideia), com as versões guardadas das Aulas 06 e 10. Não precisa do GitHub: quem pulou a Aula 19 faz tudo igual, com a página do computador. A parte das regras da casa, das skills e dos conectores vale para quem fez as Aulas 11, 13 e 14.

Quebrou a página? Três passos

1. Desfaça primeiro

Não conserte em cima do erro: um conserto apressado pode quebrar outra coisa. Volte antes ao ponto em que a página funcionava.

O Claude ainda está pedindo licença? No Manual, nada muda antes do seu sim. Se a mudança proposta parece errada, escolha No e, com Tab, diga o motivo, como na Aula 05.

Já aprovou? Escolha um destes caminhos:

• Peça: "desfaça a última mudança que você fez". O Claude sabe o que mudou nesta conversa e põe o arquivo de volta como estava.
• Use o /rewind (ou aperte Esc duas vezes, com a caixa de texto vazia), como na Aula 09. Escolha o pedido que quebrou a página e volte o código: os arquivos ficam como eram logo antes dele. O /rewind não desfaz o que um comando mudou.
• Peça: "desfaça as mudanças desde a última versão guardada" (Aula 10). Tudo o que ainda não foi guardado vai embora, até o que estava bom. Na dúvida, pergunte antes: "tem alguma mudança que ainda não foi guardada numa versão?"

Depois, recarregue a página no navegador e confira se ela voltou a funcionar. Com a página de pé, você conserta com calma.

⚠️ A página já está no ar (Aula 19)? Desfazer no computador não muda o site. Se a mudança quebrada já foi guardada e enviada para o GitHub, peça para o arquivo voltar à versão de antes, sem apagar nenhuma versão (Aula 10). Depois, guarde uma versão nova e envie de novo, como na Aula 19.

2. Mostre o erro e peça a explicação

O Claude conserta melhor quando vê o que você viu, e você decide melhor quando entende o que aconteceu.

• A mensagem apareceu na conversa? O Claude já viu. É só pedir a explicação.
• Apareceu em outro lugar, como no navegador ou no terminal antes de abrir o Claude? Selecione o texto com o mouse, copie e cole na conversa. Se for mais fácil, tire um print da tela e cole com Ctrl + V (Alt + V no Windows): ele vira [Image #1] no pedido.
• A página só ficou estranha, sem mensagem nenhuma? Descreva o que você vê e mande o print: "depois da última mudança, os doces ficaram um em cima do outro, como neste print".

Então peça:

Explique em português simples o que aconteceu e o que eu faço.

Peça a explicação antes do conserto. Se ela não fizer sentido, pergunte de novo, com as suas palavras: "não entendi essa parte, explique de outro jeito".

3. Peça um plano antes do conserto

Entendeu o que aconteceu? Agora o conserto, com o fluxo da Aula 06. Aperte Shift + Tab até aparecer plan mode on e peça:

Proponha um plano para consertar isso, sem mudar nada ainda. Diga o que vai mudar em cada arquivo e como eu confiro na tela que deu certo.

Leia o plano. Se algo não fizer sentido, escolha No, keep planning e pergunte. Quando estiver bom, escolha Yes, manually approve edits e aprove mudança por mudança. No fim, confira no navegador e guarde uma versão.

💡 Conserto pequeno dispensa o plano, como na Aula 06: se ele cabe numa frase, como trocar um texto ou uma cor, peça direto. O que não se dispensa é desfazer antes e entender o que aconteceu.

As mensagens mais comuns

Algumas mensagens vêm do serviço da Anthropic, e não da sua página. Enquanto elas aparecem, o Claude não consegue responder, então vale reconhecer as mais comuns:

Na dúvida se o problema é com todo mundo, o status.claude.com mostra quando o serviço está com falha. E, se a sua mensagem não está aqui, cole na conversa e peça a explicação, como no passo 2. A lista completa, em inglês, fica na referência de erros.

A instalação: o check-up /doctor

Algo está estranho e você não sabe por onde começar? Digite:

/doctor

Ele faz um check-up da instalação, das extensões (as skills, os conectores, os plugins e as ações automáticas), dos CLAUDE.md e das permissões. Primeiro, mostra o que achou, e só muda alguma coisa depois que você confirma. Leia cada sugestão e aceite só as que você entender. Se ele oferecer deixar o modo auto como padrão, recuse: o Manual continua sendo o modo de quem está aprendendo.

Se o claude nem abre, digite no terminal:

claude doctor

É um diagnóstico só da instalação, que lê e não muda nada. E, se aparecer em vermelho, embaixo da conversa, Auto-update failed · Run claude doctor, a atualização automática não instalou: dá para continuar trabalhando, e o claude update, digitado no terminal, termina a atualização.

A personalização: regra, skill ou conector que parou

Esta parte vale para quem fez as Aulas 11, 13 e 14.

Pedir ajuda

⚠️ O relato leva a conversa junto. Antes de enviar, confira se nela não aparece senha nem dado de cliente.

Para ir além (opcional): diagnóstico da configuração

🔧 Para ir além (para quem já programa; pode pular): esta parte mostra como investigar a configuração do Claude Code por dentro: os check-ups para programadores, o que carregou de verdade, as ações automáticas (hooks) que falham, os conectores que rodam no computador, o log de depuração, o modo seguro e os tropeços de instalação e login, com o PATH, o perfil do terminal e as variáveis de ambiente. Se você nunca programou, pule direto para o Na prática.

Mais três check-ups.

O /doctor também procura instalações duplicadas, problemas no PATH e arquivos de configuração que não abrem, compara as extensões que você não usa com o contexto que elas ocupam, aponta hooks lentos e propõe tirar do CLAUDE.md o que o Claude descobriria sozinho lendo o código. O alias é /checkup.

O que carregou de verdade. Antes de editar qualquer arquivo, veja o que o Claude Code carregou: o /context lista o contexto por categoria, com os CLAUDE.md em Memory files; o /skills mostra as skills e a origem de cada uma; o /hooks, os hooks registrados, por evento; o /mcp, os servidores, o estado de cada um e quantas ferramentas trazem; e o /status, a versão, a conta e as configurações que estão valendo. Regra geral: se não aparece ali, não carregou.

💡 Mudou um arquivo e nada mudou? Um hook novo ou alterado no settings.json vale na sessão aberta depois de alguns segundos: rode /hooks de novo para conferir. Já o CLAUDE.md da raiz e o seu ~/.claude/CLAUDE.md são lidos no começo da sessão, e a edição só vale depois de um /clear, de um /compact ou de abrir o Claude de novo.

Conectores que rodam no computador. Um servidor remoto que cai no meio da sessão é reconectado sozinho, em até cinco tentativas; se todas falharem, aparece MCP server "<nome>" disconnected · open /mcp to reconnect. Um servidor local (stdio) não volta sozinho. O /mcp reconnect all tenta de novo, de uma vez, todos os que falharam ou pedem login (a partir da v2.1.284), e o /mcp reconnect <nome> tenta um só. Se um servidor local nem inicia, confira o comando dele: um caminho relativo conta a partir da pasta em que você abriu o Claude, e não da pasta do .mcp.json. Use o caminho completo.

O log de depuração registra o que o Claude Code faz por dentro: cada evento de hook, com os matchers testados, o código de saída e a saída do script, e o erro que um servidor MCP escreveu. Ele também mostra um SKILL.md com o cabeçalho quebrado, que carrega sem a descrição: o /nome funciona, mas o Claude não consegue escolher a skill sozinho.

O modo seguro. Não sabe nem de qual peça suspeitar? Abra o Claude sem nenhuma personalização:

claude --safe-mode

Nele, não carregam o CLAUDE.md, as skills, os plugins, os mods, os hooks, os servidores MCP, os comandos e subagentes personalizados, os estilos de saída, os workflows, os temas e atalhos personalizados, a linha de status, os servidores LSP e a memória automática. O login, a escolha do modelo, as ferramentas embutidas e as permissões funcionam normalmente. Se o problema some, a causa é uma dessas peças: volte à tabela e confira uma por uma. As políticas que a sua empresa define, se houver, continuam valendo.

Instalação e login. A Aula 03 mostrou o caminho feliz. Estes são os tropeços mais comuns, pela mensagem que aparece:

Relatar um bug. O /bug abre o mesmo relato do /feedback, com a mesma tela de consentimento, e o relato pode oferecer abrir uma issue já preenchida no GitHub do Claude Code. Num problema de instalação, inclua o sistema operacional, o comando que você rodou e a mensagem de erro inteira. Se você usa o Claude Code por outro provedor, como o Amazon Bedrock, nada é enviado: o relato vira um arquivo em ~/.claude/feedback-bundles/, que você mesmo encaminha.

Mais detalhes, em inglês: a referência de erros, a depuração da configuração e os problemas de instalação e login.

Na prática

Use a pasta da sua página (a confeitaria, ou a da sua ideia). Os erros deste exercício são de propósito, e tudo volta no fim.

1. Entre na pasta e abra o Claude Code: cd Documents/confeitaria, com o nome da sua pasta, e depois claude. Aperte Shift + Tab uma vez e confira se aparece manual mode on.
2. Pergunte: "tem alguma mudança que ainda não foi guardada numa versão?" Se tiver, peça para guardar.
3. Peça: "tire o botão Tortas do filtro do cardápio". Quando o Claude pedir licença, escolha No e, com Tab, escreva "mudei de ideia". Confira no navegador que nada mudou.
4. Faça o mesmo pedido de novo e, desta vez, aprove. Recarregue a página e veja que o botão sumiu. Agora desfaça: rode /rewind, escolha o pedido do botão e volte o código. Recarregue a página: o botão Tortas voltou.
5. Treine a explicação: copie da tabela desta aula a mensagem API Error: Repeated 529 Overloaded errors, cole na conversa e peça: "explique em português simples o que aconteceu e o que eu faço". Compare com a tabela da aula.
6. Treine o plano: aperte Shift + Tab até plan mode on e peça "o horário de funcionamento está difícil de ler no modo escuro. Proponha um plano para consertar, sem mudar nada ainda". Leia o plano e escolha No, keep planning: hoje é só treino. Aperte Shift + Tab até voltar ao manual mode on.
7. Rode /doctor. Leia o que ele achou e aceite só o que você entender. Se ele oferecer o modo auto como padrão, recuse.
8. (Se você fez a Aula 11) Rode /context e confira se o seu CLAUDE.md aparece em Memory files.

Resumo

• Quebrou a página? Primeiro desfaça. Antes do sim, recuse; depois, peça "desfaça a última mudança que você fez", use o /rewind ou volte à última versão guardada (Aula 10).
• Depois, entenda: o erro que está na conversa o Claude já viu; o de fora, cole ou mande num print. Peça "explique em português simples o que aconteceu e o que eu faço".
• Por último, o conserto com plano: no Plan Mode, o que vai mudar em cada arquivo e como conferir na tela. Aprove mudança por mudança e guarde uma versão.
• Limite da sessão ou da semana: espere a renovação. 529 Overloaded: o serviço está ocupado; espere e tente de novo. Not logged in ou Login expired: rode /login. Unable to connect: confira a internet.
• O /doctor faz o check-up da instalação e só corrige o que você confirmar. Se o claude nem abre, claude doctor, no terminal.
• Regra da casa ignorada: /context. Skill sumida: /skills e /reload-skills. Conector parado: /mcp, para entrar de novo.
• Para ajuda: pergunte ao Claude, relate com o /feedback (a conversa vai junto) e, para conta e cobrança, use a central de ajuda, em support.claude.com.

Na próxima aula, a última do curso: uma página com link para mostrar a quem você quiser, o artifact.