Aula 24Quando algo dá errado

🖥️ Versão Desktop. Nesta aula, quase tudo acontece na aba Code do app Claude Desktop: na caixa de mensagem, no seletor de modo, no painel Browser e nos menus do app. O único comando do trilho principal é o /doctor, que você digita na caixa de mensagem, como um pedido. Dois comandos da versão do terminal, o /rewind e o /feedback, não fazem parte do caminho do app, e a aula mostra o que usar no lugar deles. Um comando de terminal aparece só em "Para ir além", para quem programa: o git lfs install.

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 versão do app, atualizar e descobrir por que uma regra da casa, uma skill ou um conector parou de funcionar
• Pedir ajuda pelo caminho do app

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, você vê cada mudança antes e pode recusar, como na Aula 05. Se a mudança parece errada, recuse e escreva o motivo na caixa de mensagem.

Já aprovou? No app, quem guarda o histórico da página são as versões, como você viu na Aula 10. 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.
• 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, abra a página no painel Browser (um clique no caminho do index.html na conversa) 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 seu navegador? Copie o texto e cole na caixa de mensagem. Se for mais fácil, tire um print da tela e arraste o arquivo para a caixa de mensagem, ou use o botão + → Add files or photos (adicionar arquivos ou fotos).
• A página só ficou estranha, sem mensagem nenhuma? Peça ao Claude para olhar: "abra a página no painel Browser, me mostre um print e diga o que está diferente do que era antes".

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. No seletor de modo, na linha abaixo da caixa de mensagem, escolha Plan 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, pergunte na caixa de mensagem. Quando estiver bom, troque o seletor para Manual e escreva: "Plano aprovado, pode seguir." Aprove mudança por mudança e, no fim, confira no painel Browser 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. Elas são as mesmas no app e no terminal, e, enquanto aparecem, o Claude não consegue responder. Vale reconhecer as mais comuns:

O anel de uso, ao lado do seletor de modelo, mostra quanto do plano você já usou. 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 caixa de mensagem e peça a explicação, como no passo 2. A lista completa, em inglês, fica na referência de erros.

O app: a versão, a atualização e o check-up

Algo está estranho no app e você não sabe por onde começar? Faça nesta ordem:

1. Confira a versão. No Mac, clique em Claude → About Claude, na barra de menus; no Windows, em Help → About Claude. Clique no número da versão para copiá-lo: ele vai servir se você precisar pedir ajuda.
2. Atualize. No Mac, Claude → Check for Updates; no Windows, Help → Check for Updates. Se vier uma versão nova, comece uma conversa nova com + New.
3. Peça o check-up. Digite /doctor na caixa de mensagem (ou clique em + → Slash commands e escolha na lista). Ele confere a instalação, as extensões (as skills, os conectores, os plugins e as ações automáticas), os CLAUDE.md e as 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 app responder que o /doctor não está disponível aqui, siga para Pedir ajuda, mais abaixo, com a versão que você copiou.

A tela ficou em branco ou travou ao abrir? Feche o app e abra de novo: no Mac e no Windows, ele se atualiza sozinho ao abrir.

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

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

Pedir ajuda

⚠️ Revise o que você manda. Um print pode mostrar o nome das suas pastas e, se a página estiver aberta, dados de clientes. Corte ou cubra o que não precisa ir.

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

🔧 Para ir além (para quem já programa; pode pular): esta parte mostra como investigar a configuração por dentro, no app: as duas versões, a revisão das instruções, o que carregou de verdade, as ações automáticas (hooks) que falham, os conectores que rodam no computador, o modo Verbose, o log de depuração, os logs do sistema, uma sessão limpa e os tropeços de instalação, com o PATH, as variáveis de ambiente e o Git LFS. Se você nunca programou, pule direto para o Na prática.

As duas versões. O About Claude mostra a versão do app. Para ver a versão do Claude Code que a aba Code usa, digite /status numa sessão local e leia a linha Claude Code. A aba Code roda a sua própria cópia do Claude Code, que o app baixa e atualiza (Aula 03). Se você também usa o claude no terminal, as duas versões podem ser diferentes, e atualizar uma não atualiza a outra.

A revisão das instruções. O /doctor prompt-audit também roda no app: ele revisa os seus CLAUDE.md, CLAUDE.local.md e AGENTS.md, mais as regras, skills e subagentes em .claude/ e ~/.claude/, procurando instruções escritas para modelos antigos, arquivos ou comandos citados que não existem e instruções que se contradizem. Nada muda até você pedir. Para uma pasta só, passe o caminho: /doctor prompt-audit .claude/skills/post-instagram. O mesmo pedido, em português:

Revise meus CLAUDE.md, CLAUDE.local.md e AGENTS.md e as regras, skills e
subagentes em .claude/ e ~/.claude/. Aponte instruções escritas para modelos
antigos, arquivos ou comandos citados que não existem e instruções que se
contradizem. Não mude nada sem eu pedir.

Os relatórios do /skill-doctor (as skills que pesam e ninguém usa) e do /insights (onde as suas sessões travam) ficam na versão do terminal. No app, para tirar do caminho as skills que você não usa, use o skillOverrides da Aula 13.

O que carregou de verdade. A versão do terminal tem o /context, o /skills, o /hooks e o /mcp. No app:

• Pergunte ao Claude. Os CLAUDE.md, as descrições das skills e as ferramentas MCP entram no contexto da sessão, então ele sabe dizer o que recebeu e de onde veio cada item: "Quais CLAUDE.md, skills e servidores MCP estão valendo nesta sessão, e de onde vem cada um?"
• O menu /. Digite / na caixa de mensagem, ou clique em + → Slash commands: a lista traz os comandos prontos, as suas skills, as do projeto e as dos plugins instalados.
• Settings → Connectors, com os conectores ligados no app (Aula 14).
• O arquivo. Para hooks e permissões, abra o settings.json no painel de arquivos (clique no caminho quando ele aparecer na conversa) ou peça ao Claude a lista dos hooks e de onde vem cada um (Aula 15).

Regra geral: se o Claude não vê, não carregou.

Digitou /nome e nada rodou? Na aba Code, um /nome que não existe na sessão não roda nada: o texto vai para o Claude como uma mensagem normal, com um aviso de que o comando não rodou. Se isso acontece com uma skill sua, ela não carregou: confira a pasta dela.

💡 Mudou um arquivo e nada mudou? Um hook novo ou alterado no settings.json vale na sessão aberta depois de alguns segundos. 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 /compact ou numa sessão nova (+ New).

Conectores que rodam no computador. Um servidor remoto que cai no meio da sessão é reconectado sozinho, em até cinco tentativas. Um servidor local (stdio) não volta sozinho. Um servidor de arquivo (.mcp.json ou ~/.claude.json): confira a configuração dele e abra uma sessão nova; se não resolver, reinicie o app. No Windows, se os servidores não conectam, confira a configuração, reinicie o app, veja no Gerenciador de Tarefas (Task Manager) se o processo do servidor está rodando e leia os logs do servidor. Se um servidor local nem inicia, confira o comando dele: um caminho relativo conta a partir da pasta da sessão, e não da pasta do .mcp.json. Use o caminho completo.

O modo Verbose. Os modos de visualização controlam quanto detalhe aparece na conversa. Aperte Ctrl+O (no Mac e no Windows) até chegar ao Verbose, ou abra o menu da sessão, na setinha ao lado do título, e escolha Transcript view. O Verbose mostra cada chamada de ferramenta, cada arquivo lido e cada passo intermediário, mais o raciocínio do Claude: é o modo para descobrir por que o Claude fez alguma coisa.

O log de depuração. Digite /debug na caixa de mensagem, se quiser seguido da descrição do problema, como em /debug o hook não dispara. O log passa a ser gravado dali em diante, e o Claude o lê para diagnosticar. O claude --debug e o claude --safe-mode da versão do terminal são opções da linha de comando e não valem no app.

Os logs do sistema. Para um erro do próprio app, como uma tela em branco ou um travamento, olhe os logs: no Mac, no Console.app; no Windows, no Event Viewer, em Windows Logs → Application. O menu Help → Troubleshooting também guarda um arquivo com os logs do app: Show Logs in Finder (Mac), Show Logs in File Explorer (Windows) ou Show Logs in File Manager (Linux). Revise os trechos antes de colar numa issue pública: eles podem trazer caminhos de arquivos e outros detalhes do seu computador.

Uma sessão limpa. Não sabe nem de qual peça suspeitar? Teste sem a sua personalização, em duas etapas:

1. Crie uma pasta vazia, fora dos seus projetos, e abra nela uma sessão Local. Sem .claude/, .mcp.json nem CLAUDE.md, nada de projeto carrega. Se o problema some, a culpa é de uma peça do projeto: volte à tabela e confira uma por uma.
2. Se o problema continua, a suspeita passa para o que é seu, de usuário. Desligue uma peça por vez e teste de novo: os hooks, com "disableAllHooks": true no ~/.claude/settings.json; os plugins, em + → Plugins → Manage plugins; os conectores, em Settings → Connectors; as skills, com o skillOverrides (Aula 13). Quando o problema sumir, a última peça desligada é a culpada. No fim, religue o resto e apague o "disableAllHooks".

As políticas que a sua empresa define, se houver, continuam valendo o tempo todo.

Instalação e app. Estes são os tropeços mais comuns no app, pelo que aparece na tela:

Relatar pelo GitHub. Se o problema também acontece no claude do terminal, procure ou relate nas issues do Claude Code no GitHub, com a versão do app, o sistema, a mensagem de erro exata e os logs que importam, revisados.

Mais detalhes, em inglês: a solução de problemas do app e a referência de erros.

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. Na aba Code, clique em + New. Na linha abaixo da caixa de mensagem, escolha Local e a pasta da sua página e, na mesma linha, Manual no seletor de modo.
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 a mudança aparecer para você aprovar, recuse e escreva "mudei de ideia" na caixa de mensagem. Confira no painel Browser que nada mudou.
4. Faça o mesmo pedido de novo e, desta vez, aprove. Veja no painel Browser que o botão sumiu. Agora peça: "desfaça a última mudança que você fez", aprove e confira no painel Browser: 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 caixa de mensagem e peça: "explique em português simples o que aconteceu e o que eu faço". Compare com a tabela.
6. Treine o plano: troque o seletor para Plan 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, como hoje é só treino, troque o seletor de volta para Manual sem aprovar.
7. Confira a versão do app em About Claude e clique no número para copiá-lo. Depois, use Check for Updates.
8. Digite /doctor na caixa de mensagem. Leia o que ele achou e aceite só o que você entender. Se ele oferecer o Auto como padrão, recuse.
9. (Se você fez a Aula 11) Pergunte: "quais arquivos CLAUDE.md você leu nesta conversa?"

Resumo

• Quebrou a página? Primeiro desfaça. Antes do sim, recuse; depois, peça "desfaça a última mudança que você fez" 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 arraste um print para a caixa de mensagem. Peça "explique em português simples o que aconteceu e o que eu faço".
• Por último, o conserto com plano: no Plan, o que vai mudar em cada arquivo e como conferir na tela. No Manual, aprove mudança por mudança e guarde uma versão.
• Limite da sessão: espere a renovação, ou marque Auto-continue when limits reset no cartão. 529 Overloaded: o serviço está ocupado; espere ou troque de modelo. Authentication required ou Error 403: entre de novo pelo app. Unable to connect: confira a internet.
• Algo estranho no app: confira a versão em About Claude, use Check for Updates e peça o /doctor, que só corrige o que você confirmar.
• Regra da casa ignorada: pergunte o que o Claude leu. Skill sumida: + New. Conector parado: Settings → Connectors.
• Para ajuda: pergunte ao Claude e, para um problema do app, use Help → Get Support, com a versão, o sistema e a mensagem de erro.

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