Como pedir ao Claude Code os estados da tela (vazio, carregando e erro) em vez de só o caso feliz

A tela volta linda no print e quebra na hora de plugar na API real

Acontece sempre: você pede um dashboard, uma listagem, um formulário, e vem tudo bonito, espaçado, com os dados de mentira encaixadinhos no lugar

Aí você liga na requisição de verdade e descobre que não existe lista vazia, não existe carregando, não existe erro, não existe usuário sem permissão

O motivo é chato de admitir: nada no enunciado obrigava o modelo a pensar nisso

Você pediu "uma tela de pedidos", e uma tela de pedidos, no sentido mais literal, é uma tela que mostra pedidos

O conserto não é prompt mágico (essas coisas toscas não existem), é descrever no pedido cada situação que a tela precisa cobrir

É o mesmo raciocínio de escrever um requisito pra um dev humano: se você não fala o que acontece quando a lista volta vazia, cada um decide uma coisa

O que ter antes de pedir a tela

Nada de PC da Nasa aqui, o setup é simples

• Projeto aberto no Claude Code, com um CLAUDE.md na raiz. Esse arquivo é lido no início de cada sessão e serve pra fixar padrões de código, decisões de arquitetura, bibliotecas preferidas e checklists de revisão (guarde essa informação, ela volta no final do post)
• Saber alternar pro modo plan. O Shift+Tab cicla os modos de permissão no meio da sessão: padrão, acceptEdits e plan. No plan mode o Claude lê os arquivos e propõe um plano sem escrever nada em disco até você aprovar, e a barra de status mostra o indicador de plan mode ativo
• Clareza sobre de onde vêm os dados da tela. Isso não é detalhe: o vocabulário dos estados depende da camada de dados. No TanStack Query, por exemplo, uma query fica em exatamente um de três estados de status: pending, error ou success

Se o Claude Code ainda nem abre direito na sua máquina, resolve isso primeiro: tem um guia aqui sobre erros ao instalar o Claude Code

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Passo a passo: como pedir os estados da tela ao Claude Code

A lógica dos passos é sempre a mesma: sair do genérico e virar enunciado

"Trate os erros" é genérico

"Se a requisição falhar, mostre X, com botão Y, e mantenha Z na tela" é enunciado

1. Descreva a tela e a origem dos dados

Comece dizendo o que a tela é e de onde vem o dado, porque isso define o vocabulário que o Claude vai usar no código

Tela: listagem de pedidos do cliente logado
Origem: GET /api/pedidos, via TanStack Query
Stack: React + TypeScript, componentes já existentes em src/components

O erro comum deste passo: pedir a tela sem dizer a camada de dados, e receber um useEffect improvisado com fetch na mão, quando o projeto inteiro já usa outra coisa

2. Nomeie os estados um a um

Não escreva "cubra os estados da tela"

Escreva a lista, item por item, porque o que está nomeado é o que vira código

A tela precisa cobrir 5 situações, cada uma com UI própria:
1. lista vazia (requisição deu certo e voltou zero itens)
2. dados carregando (primeira carga)
3. falha de requisição
4. campo inválido no filtro de busca
5. permissão negada
Não presuma nenhuma delas: descreva o que aparece na tela em cada uma

O erro comum deste passo: confundir lista vazia com erro. São coisas diferentes, uma deu certo e a outra não, e a tela precisa dizer isso pro usuário

3. Separe "não tem dado" de "está buscando"

Esse é o passo que mais salva tela na vida real

No TanStack Query, isFetching é verdadeiro sempre que a busca está rodando, inclusive num refetch em segundo plano, e é distinto do status: o status diz se HÁ dados, o fetchStatus diz se a função de busca está rodando

Na prática, se você não separa os dois, o refetch em background apaga a tela cheia e mostra o skeleton de novo, e o usuário sente aquele piscar horroroso a cada revalidação

Separe status de fetchStatus:
- status pending (ainda não tenho dado): mostra skeleton
- status success + isFetching (já tenho dado e estou atualizando):
  mantém a lista na tela e mostra indicador discreto de atualização
Nunca troque a lista já renderizada por skeleton num refetch

O erro comum deste passo: tratar todo carregamento como se fosse o primeiro

4. Defina o feedback de espera por duração

Aqui não é gosto pessoal, existe régua

A Nielsen Norman Group tem uma recomendação pra cada indicador de espera, e a escolha sai daí:

Então o pedido fica assim:

Carregamento:
- primeira carga da lista: skeleton com a forma dos cards
- ação pontual dentro da tela (salvar filtro): spinner no botão
- exportação longa: barra de progresso, não spinner

O erro comum deste passo: spinner pra tudo. Spinner numa espera longa deixa o usuário sem ideia de quanto falta, e é aí que ele recarrega a página no meio do processo

5. Distinga falha de autenticação de falha de permissão

Esses dois vivem colapsados num "deu erro" genérico, e são situações bem diferentes

O 401 Unauthorized indica que a requisição não tem credenciais de autenticação válidas pro recurso, e a resposta vem com o cabeçalho WWW-Authenticate dizendo o esquema de autenticação esperado

Já o 403 Forbidden indica que o servidor ENTENDEU a requisição e se recusou a processá-la, e autenticar ou reautenticar não muda nada, porque a falha vem da lógica da aplicação, tipo permissão insuficiente

Ou seja: mandar quem tomou 403 fazer login de novo é passeio inútil

Autenticação x permissão:
- 401: sessão inválida ou ausente, leva pro fluxo de login
- 403: usuário identificado sem permissão, NÃO oferece login de novo,
  explica que falta acesso e dá uma saída (voltar / pedir acesso)

O erro comum deste passo: cair no loop de login, em que o usuário autentica, volta, toma 403 de novo e reautentica pra sempre

6. Rode em modo plan antes de escrever arquivo

Com o pedido montado, aperta Shift+Tab até chegar no plan mode

O Claude vai ler o projeto e propor um plano sem editar nada até você aprovar

Aí você lê o plano procurando UMA coisa: os cinco estados estão lá?

Se faltar algum, você corrige no plano, que é barato, em vez de corrigir em cinco componentes já escritos

O erro comum deste passo: aprovar o plano no automático, no modo next, next e finish, e só descobrir o que faltou depois do código pronto

Os cinco estados, um a um: o que descrever em cada

Essa é a parte que vale copiar e adaptar

Lista vazia: o que descrever

Estado vazio bem projetado aumenta a confiança do usuário, melhora a aprendizagem do sistema e ajuda a começar tarefas-chave

Já uma tela totalmente vazia causa confusão sobre se e como o sistema está funcionando, que é exatamente aquele momento de "será que quebrou ou eu que não tenho nada aqui?"

Descreva no pedido:

• a frase que explica POR QUE está vazio (nunca cadastrou nada x o filtro não achou nada, são textos diferentes)
• a ação principal que tira o usuário do zero
• se cabe um exemplo do que vai aparecer ali quando tiver dado

Dados carregando: o que descrever

Aqui você já tem a régua do passo 4, então descreva por duração e por escopo

• tela inteira carregando pela primeira vez: skeleton com a forma real do conteúdo
• pedaço da tela ou ação pontual: spinner localizado, de 2 a 10 segundos
• processo longo, acima de 10 segundos: barra de progresso
• atualização em segundo plano com dado já na tela: mantém o conteúdo e sinaliza discreto

Descreva também o que NÃO pode acontecer: layout pulando quando o dado chega

Falha de requisição: o que descrever

Três perguntas, e o pedido precisa responder as três:

1. o que a mensagem diz (em português de gente, não o stack trace)
2. qual é a ação de recuperação (tentar de novo é o mínimo)
3. o que acontece com o dado que JÁ estava na tela

Esse terceiro ponto é o mais esquecido

Se o usuário estava vendo 40 pedidos e o refetch falhou, jogar tudo fora pra mostrar um ícone de erro é pior que manter a lista antiga com um aviso de "não consegui atualizar"

Campo inválido: o que descrever

Aqui a régua é de fluxo, não de status

Descreva quando a validação roda (ao digitar, ao sair do campo, ao enviar), onde a mensagem aparece (colada no campo, e não só num toast que some) e o que trava o envio

Validação:
- valida ao sair do campo e novamente no submit
- mensagem abaixo do campo, com o campo marcado
- botão de enviar bloqueado enquanto houver campo inválido
- ao falhar o submit, foca o primeiro campo com erro

Esse último item é o que separa formulário usável de formulário que faz o usuário caçar o erro rolando a página

Permissão negada: o que descrever

É o 403 virando tela

A identidade é conhecida, o que falta é permissão, e reautenticar não resolve

Então a tela precisa: dizer que aquilo existe mas não é acessível pra ele, não oferecer login de novo, e dar uma saída clara (voltar pro lugar onde ele TEM acesso, ou o caminho pra pedir acesso a quem administra)

Como fixar isso e não repetir o pedido toda vez

Digitar essa lista em todo pedido de interface é insustentável

A graça é escrever uma vez e a ferramenta lembrar

1. Escreva o bloco de estados no CLAUDE.md da raiz

O CLAUDE.md na raiz do projeto é lido no começo de toda sessão, e serve exatamente pra isso: padrões de código, decisões de arquitetura, bibliotecas preferidas e checklists de revisão

Então a sua lista de estados vira checklist escrito:

## Checklist de UI: toda tela nova

Toda tela com dado remoto cobre 5 estados, sem exceção:

1. Lista vazia: texto que explica o porquê + ação pra sair do zero
2. Carregando: skeleton na primeira carga; refetch em segundo plano
   NÃO apaga o conteúdo já renderizado
3. Erro de requisição: mensagem legível + tentar de novo + decisão
   explícita sobre o dado que já estava na tela
4. Campo inválido: mensagem junto ao campo, submit bloqueado,
   foco no primeiro erro
5. 401 x 403: 401 leva ao login; 403 explica falta de permissão e
   NÃO oferece reautenticar

O erro comum deste passo: escrever isso num arquivo solto de documentação que ninguém lê e esperar que o Claude Code adivinhe

2. Confira quais memórias estão realmente ativas

Rode /memory

Ele lista os arquivos de memória (CLAUDE.md, CLAUDE.local.md e os demais) nos escopos de usuário e de projeto, e ainda permite ligar ou desligar a memória automática

Vale a conferida quando o Claude começa a ignorar uma regra que você jura que escreveu: às vezes ela está no escopo errado

3. Isole a revisão de estados num subagente

Quando a revisão de UI merece contexto próprio, dá pra tirar ela da conversa principal

Subagentes do Claude Code são arquivos Markdown com frontmatter YAML e mantêm contexto separado do agente principal, o que evita poluir a conversa principal

Na prática: um subagente cuja única função é ler o componente e responder quais dos cinco estados estão faltando, sem carregar junto todo o histórico da feature

Se o seu fluxo também passa por outras ferramentas da Anthropic, os ajustes pra aproveitar melhor o Claude Cowork seguem a mesma lógica: o que você deixa escrito é o que a ferramenta repete

Conclusão

Tela completa não é a que mostra dado bonito

É a que sabe o que fazer quando não tem dado, quando o dado demora e quando o dado não vem

O caso feliz o modelo entrega de graça, o resto você precisa pedir com nome e sobrenome: lista vazia, carregando, falha, campo inválido e permissão negada

Próximo passo, e dá pra fazer hoje: escreve o bloco de estados no CLAUDE.md da raiz e roda o próximo pedido de interface em modo plan

Antes de aprovar, procura os cinco estados no plano

Se eles não estiverem lá, o código também não vai ter 🙂

até o próximo post!