Guia do Claude AI: Dicas e Tutoriais Práticos

O Projects do Claude Code foi reconstruído. Até agora um projeto era uma pasta que guardava conversas e material de referência; o novo Projects é uma única conversa. Você escreve o que precisa, o Claude divide aquilo em threads, as threads rodam em paralelo na nuvem e cada uma abre um pull request e volta com um relato quando termina. Fechar o notebook não as interrompe. Antes de mergulhar, porém, vale conferir três coisas: as contas que podem usar ainda são poucas (um beta público de Pro e Max, que chega primeiro às contas sem projetos existentes), o github.com e o Claude GitHub App são exigências na prática, e a velocidade com que isso devora o seu limite de uso não tem nada a ver com a de uma sessão única. Este artigo percorre como saber se a liberação já chegou até você, com o que uma thread começa (incluindo a armadilha em que regras de permissão e hooks deixam de valer assim que um projeto tem mais de um repositório), de onde vem o custo em tokens, inclusive o padrão de Opus em esforço high, e como escolher entre as cinco formas de trabalhar em paralelo: subagents, agent view, Agent Teams, dynamic workflows e Projects, tudo a partir da documentação e do blog oficiais.

Você quer deixar só o planejamento com um modelo mais inteligente e passar a implementação para um modelo mais rápido e mais barato. O opusplan do Claude Code é uma indicação de modelo que faz isso automaticamente. Ele roda no Opus durante o modo de planejamento e no Sonnet no resto do tempo, e pode ser usado com /model opusplan ou com o model do settings.json. Mas ele não aparece na lista do /model e, como o modelo troca toda vez que você entra ou sai do modo de planejamento, a cada troca a conversa inteira é relida sem cache. Com base na documentação oficial, no histórico de mudanças e nas issues do GitHub em 15 de setembro de 2026, este artigo organiza como configurar (incluindo fixar versões e o contexto de 1M), o fluxo do modo de planejamento até a aprovação e a implementação, como ele saiu da tela de seleção na v2.0.0 e a explicação de um funcionário da Anthropic, uma estimativa do custo de cache gerado pelas trocas e como contê-lo, as diferenças em relação à ferramenta advisor e aos subagentes, e os usos em que ele combina ou não.

Dá para manter a sessão principal do Claude Code no Opus 5 e entregar só tarefas como tradução ou verificações em grande volume a subagentes no Sonnet ou no Haiku? Dá. O modelo do subagente é decidido nesta ordem: o modelo indicado na chamada, o model do arquivo de definição, a variável de ambiente CLAUDE_CODE_SUBAGENT_MODEL e o modelo da sessão principal; o esforço (effort) também pode ser definido para cada subagente. Com base na documentação oficial em 15 de setembro de 2026, este artigo organiza as diferenças dessa ordem entre versões, o CLAUDE_CODE_SUBAGENT_MODEL_FORCE para fixar todos em um único modelo, o destino dos aliases, que muda conforme o provedor, e o fato de que, desde a v2.1.198, o Explore nativo herda o modelo da sessão principal. Em seguida, mostra o que aconteceu quando iniciei subagentes em outros modelos e conferi nos logs de conversa: eles rodaram no modelo indicado, cada um leu dezenas de milhares de tokens só para iniciar, o cache dos subagentes expira em 5 minutos mesmo na assinatura, e a mesma tradução entregue ao Opus 5, ao Sonnet 5 e ao Haiku 4.5, duas vezes para cada um, teve diferenças de tempo, custo e qualidade. Por fim, resume o efeito no custo e nos limites de uso e os critérios para decidir que trabalho passar para um modelo mais barato.

Quando você roda várias sessões em paralelo, começa a se perguntar qual delas está consumindo o seu limite semanal. Só que o /usage do Claude Code mostra apenas os números da sessão atual e o consumo do plano inteiro dividido por Skill, subagente, plugin e servidor MCP, e a parcela usada por cada sessão não aparece nem no anel de uso do app desktop nem na página de configurações do claude.ai (em setembro de 2026). A resposta está nos logs de conversa guardados na sua máquina (os arquivos JSONL em ~/.claude/projects), mas somá-los como estão dá o resultado errado, porque uma única resposta é gravada em várias linhas, uma por bloco de conteúdo, e os registros dos subagentes ficam em arquivos separados. Medida na minha própria máquina, a soma direta chegou a cerca do dobro do valor correto e, como o tamanho do erro variava de uma sessão para outra, até a ordem entre elas mudou. Este artigo mostra o que as telas oficiais mostram e o que não mostram, como contar os logs corretamente com um script de agregação de cerca de 50 linhas, a medição em que uma sessão levou quase um terço de todo o uso, os limites do que os números podem dizer e como configurar o OpenTelemetry se você quiser acompanhar o uso ao longo do tempo.

Você não precisa pedir toda vez "comece pela conclusão" ou "responda em português": basta escrever isso uma vez no campo de instruções que vale automaticamente para todas as conversas. Esse campo são as "Instruções personalizadas" no ChatGPT, as "Instruções para Claude" no Claude e as "Instruções para o Gemini" no Gemini, mas o nome na tela, o lugar onde fica e a quantidade de caracteres permitida são diferentes. O ChatGPT aceita 1.500 caracteres no Free e no Go e 5.000 no Plus ou superior (limite elevado em julho de 2026), enquanto o Claude e o Gemini não divulgam um limite. Este artigo confere o lugar e o limite na ajuda oficial das três empresas e, com base no guia oficial de prompts da Anthropic, mostra como escrever instruções que funcionam, com um exemplo. Além disso, reúne em uma lista de verificação as situações em que, segundo as ajudas oficiais, as instruções não valem, como dentro de projetos, dentro de Gems, em chats temporários e em contas da empresa.

Você escreve em português e o Claude responde em inglês. O repositório oficial do Claude Code recebe o mesmo relato repetidas vezes, e a pesquisa também mostrou que, quando o pedido e a resposta estão em idiomas diferentes, mesmo os modelos mais fortes não conseguem responder de forma consistente no idioma pedido. Mas a causa não é uma só. O problema se divide em quatro tipos: o inglês que entra aos poucos enquanto o Claude lê código e saídas de ferramentas, a volta ao inglês logo depois da compactação que resume a conversa, a resposta que vira outro idioma e, desde o fim de setembro de 2026, com o Opus 5.5, "só as frases entre uma ferramenta e outra viram inglês", e cada um pede uma correção diferente. Este artigo mostra como identificar cada tipo, explica por que a configuração language do Claude Code, que fixa a instrução no prompt de sistema, continua valendo depois da compactação, apresenta o hook que, segundo relatos, funcionou contra o tipo 4, que não para nem com essa configuração, traz a medição nos registros do autor, em que as frases do meio do trabalho em inglês subiram de cerca de 11% para cerca de 50%, e organiza o problema relatado a partir de setembro de 2026, de sessões longas em que a própria saída desanda, separando o que foi confirmado do que ainda não foi.

Instalar Skills demais sufoca o contexto: metade dessa frase está certa e metade está errada. Segundo a documentação oficial do Claude Code, a listagem de Skills consome um orçamento fixo de 1% da janela de contexto do modelo e, por mais Skills que você acrescente, é ali que ela para. Em vez de crescer, a listagem passa a descartar descrições, começando pelas Skills menos invocadas, e mantém apenas os nomes. Uma Skill que perdeu a descrição deixa de se conectar com aquilo que você pediu, e ainda assim nenhum erro aparece e nada fica mais lento. Este artigo percorre os papéis distintos das três ferramentas de medição (/context, /usage e /skill-doctor), a definição de erro de cache como 5% e 2.000 tokens, a queda da validade do cache de uma hora para cinco minutos conforme o contrato, por que a CLI continua mais leve que o MCP mesmo agora que as definições de ferramentas são carregadas sob demanda, o raciocínio por trás de manter o CLAUDE.md abaixo de 200 linhas e o que cortar primeiro depois de medir, sempre restrito ao que foi possível confirmar na documentação oficial.

O trabalho trava enquanto você usa o Claude, você pesquisa exatamente a mensagem que apareceu e a busca não devolve nada. The model returned no content because the response was blocked by content filtering, The response was blocked by the provider's content filter, Streaming response ended before any complete data was received, Could not locate the Claude CLI on PATH e Connection to Claude's response was lost. Claude may still be working são cinco exemplos disso. O que elas têm em comum é aparecerem durante o uso do Claude e, ainda assim, não serem encontradas (ao menos aparentemente) no material do Claude. O motivo é simples: quem escreveu a mensagem que está na sua tela não é necessariamente o programa que você imagina. Este artigo não explica cada causa do zero; ele é a porta de entrada para identificar quem escreveu a mensagem e encaminhar você ao artigo certo. Primeiro, as quatro camadas capazes de escrever uma frase de erro (o backend que fornece o modelo, o próprio Claude Code, o programa que o inicia como extensão de IDE ou wrapper, e o cliente de terceiros). Comparando de fato, duas das cinco existiam como itens na referência oficial de erros do Claude Code. A definição oficial de Streaming response ended… é que os cabeçalhos voltaram mas o corpo não trazia mensagem da API do Claude, ou seja, não é queda no meio. Já Could not locate the Claude CLI on PATH está num capítulo separado, Wrapper and IDE errors, que a documentação oficial descreve como mensagens impressas pelo programa que faz a inicialização. As duas frases de content filter, em contrapartida, são vocabulário de terceiros, e a issue #35736 do OpenCode relata que três falhas distintas — 404 do Vertex, socket rompido e recusa de verdade — aparecem todas como o mesmo blocked by content filter. Só uma das três torna a frase correta. A documentação oficial do GitHub também afirma que, ao usar o Claude, entrada e saída passam pelos filtros de conteúdo do GitHub Copilot, de modo que usar o Claude não garante que quem barrou foi o filtro da Anthropic. Da última das cinco não há string nem na referência oficial nem na documentação do Remote Control, então a origem não foi identificada, nenhum nome é citado e ficam registrados quatro passos para o leitor descobrir sozinho. O que está confirmado e o que não está aparecem separados por rótulos.

O Claude Code para no meio da resposta e mostra API Error: Connection lost mid-response. The response above may be incomplete. Pesquisar essa frase exata devolve pouca coisa porque o nome é relativamente novo: a referência oficial de erros diz que, antes da v2.1.227, Connection lost mid-response aparecia como Connection closed mid-response, e que ao mesmo tempo Response stalled mid-stream virou The response stopped arriving e Connection closed while thinking, before producing a response virou Connection lost before a response was produced. O fenômeno já existia; só a palavra mudou. Partindo dessa renomeação, este artigo organiza tudo apoiado apenas na documentação oficial e em issues públicas. Primeiro, a definição oficial das seis mensagens de resposta interrompida (Server error, Connection lost, computer went to sleep, The response stopped arriving, Part of the response never arrived e The response stream was malformed), o motivo de a saída parcial ser preservada de propósito — reenviar poderia executar a mesma chamada de ferramenta duas vezes — e o procedimento de retomada, que é responder continue. Depois, por que não há nova tentativa automática, pela bifurcação oficial dos Automatic retries: quedas antes de qualquer conclusão são reenviadas com backoff até 10 vezes; depois do raciocínio e antes da saída, no máximo 2 vezes, até terminar em Connection lost before a response was produced; depois de um bloco concluído, nada é reenviado e o aviso aparece. Em seguida, as três camadas em que a conexão pode se romper (equipamento e conexão local, caminho com proxy e gateway, servidor e reuso de conexão), a releitura do material mTLS na rotação de certificados (a partir da v2.1.232), um checklist de isolamento com 9 passos, os valores padrão dos quatro temporizadores de vigilância do stream (first-byte 180 s, event 300 s, byte 180 s, body idle 5 minutos) e variáveis como CLAUDE_CODE_MAX_RETRIES, CLAUDE_CODE_RETRY_WATCHDOG e API_TIMEOUT_MS, além de uma tabela para distinguir oito mensagens parecidas. Também traz os relatos reais em que o HTTPS puro passa e só a CLI cai com ECONNRESET (#86473 e #85979). No fim, separa por grau de confiança o que está documentado — sintoma, sentido e retomada — do que ainda não saiu: a explicação oficial da causa e qualquer registro da renomeação no CHANGELOG.

Migrar para o Claude Fable 5.1 não termina quando você troca o ID do modelo. A documentação oficial afirma que três delas são mudanças incompatíveis e, dessas três, duas se manifestam longe de onde está a causa. 1) A chamada de ferramenta forçada devolve 400 — os tipos any e tool de tool_choice retornam invalid_request_error. Como o raciocínio deste modelo está sempre ligado, forçar a ferramenta faz o raciocínio ser pulado e a qualidade dos argumentos cair. 2) O bloco de raciocínio fica vinculado ao modelo — conversas que vêm da geração anterior para o Fable 5.1 preservam o raciocínio, mas o sentido inverso o perde. E, por padrão, os blocos ilegíveis são descartados antes de chegar ao modelo, não entram em input_tokens e nem aparecem na cobrança. Em arquiteturas que trocam de modelo com roteadores ou fallbacks, tudo parece funcionar enquanto só o raciocínio some. Para perceber, é preciso o cabeçalho beta thinking-binding-controls-2026-08-01. 3) Editar turnos antigos invalida todos os blocos de raciocínio seguintes — reconstruir o prompt system ou o array tools e inserir lembretes para apagá-los depois entram nessa categoria. Como essa verificação é obrigatória em contas criadas a partir de 31 de agosto de 2026, pode acontecer de um ambiente de testes novo falhar enquanto a produção não falha. Também vale evitar o erro de posicionamento: o Fable 5.1 não é uma troca de carro-chefe, e, no momento da publicação, a documentação oficial dizia que a maioria dos usos começava pelo Opus 5. Não houve aumento de preço; o que mudou foi só a leitura de cache, que caiu de 0.1 para 0.025 vez a entrada base. O efeito depende de quantas vezes o mesmo prefixo é relido, e a Anthropic fala em cerca de 25% de redução em cargas típicas e até cerca de 45% em trabalhos de perfil agêntico. Além disso, sete comportamentos mudam sem você mexer no código (menos chamadas de ferramenta em paralelo, menos narração de progresso, respostas de memória com effort low, prosa mais densa, menos formatação, citações não marcadas ao resumir, reescrita integral em correções pequenas). Os cinco recursos acrescentados e as cinco verificações do roteiro de migração também estão aqui, tudo com base na documentação oficial da Anthropic.

O Remote Control conecta o aplicativo móvel do Claude ou o claude.ai/code a uma sessão do Claude Code que já está rodando na sua própria máquina, e o ponto que a maioria das explicações erra é que nada se muda para a nuvem: a execução do código e o acesso aos arquivos permanecem locais o tempo todo, e o celular é apenas uma janela para essa sessão. Este artigo percorre o que esse desenho compra e o que ele custa. O seu sistema de arquivos local, os servidores MCP, as ferramentas e a configuração do projeto continuam disponíveis (digitar @ autocompleta caminhos do projeto local), a conversa e o progresso dos subagentes ficam sincronizados entre terminal, navegador e celular, e um notebook que hiberna ou uma conexão que cai são sobreviventes porque o Claude Code reconecta e entrega as atualizações enfileiradas assim que se recupera. Os requisitos são mais rígidos do que parecem: Pro, Max, Team ou Enterprise (chaves de API não são suportadas), login no claude.ai em vez de um setup-token, conexão direta com api.anthropic.com e nenhuma das quatro variáveis de ambiente que desligam a telemetria definida, motivo pelo qual quem define DO_NOT_TRACK por privacidade ouve que o recurso não está habilitado na conta. São cobertas as três portas de entrada (/remote-control para levar a conversa atual, claude --remote-control e o modo servidor com suas flags --spawn, --capacity 32 e --continue), além da divisão entre os comandos de barra que funcionam remotamente e os que são somente locais, como /resume, do prazo de cinco minutos das caixas de diálogo que não vale para os pedidos de permissão e dos dois botões de notificação push. Na segurança, o artigo é deliberado: nenhuma porta de entrada é aberta, então a superfície de ataque de rede quase desaparece e o risco se muda para a conta, o QR code é um atalho e não uma autenticação, e o portão padrão é exatamente uma conta com sessão iniciada, o que torna a passkey o passo de maior valor. A retenção das transcrições (5 anos ou 30 dias), o que fazer ao perder o celular, o Trusted Devices com sua janela de 18 horas, o tempo limite de dez minutos do modo servidor, a janela de quatro horas para retomar, a exigência do tmux em máquinas remotas, uma tabela de diagnóstico ligada às mensagens de erro reais e uma comparação com o Dispatch completam o quadro.

O jeito de pensar do Claude passou por uma troca de geração. O antigo pensamento estendido (extended thinking) exigia que você especificasse um orçamento de tokens em cada requisição — thinking: {"type": "enabled", "budget_tokens": N} —, mas o orçamento certo muda de tarefa para tarefa, não dá para adivinhá-lo de antemão, e alterá-lo invalida o cache de prompt. O pensamento adaptativo atual é uma única linha, type: "adaptive": pensar ou não, e com que profundidade, é decisão do próprio modelo com base em quão difícil a requisição parece. A migração foi escalonada: budget_tokens foi descontinuado no Opus 4.6 / Sonnet 4.6 e é rejeitado com erro 400 do Opus 4.7 em diante. Este artigo condensa as regras por modelo em uma tabela — o Fable 5.1 e o Opus 5.5 pensam sempre (não dá para desligar), o Sonnet 5.5 vem com o pensamento ligado por padrão e rejeita disabled com erro 400, mas between_tools desliga só o pensamento inicial (effort high ou abaixo), os modelos Legacy Opus 5 e Sonnet 5 vêm com o pensamento ligado por padrão (no Opus 5, desligar só é permitido com effort high ou abaixo), Opus 4.8 / 4.7 exigem adaptive explícito, e modelos que só suportam pensamento estendido, como Haiku 4.5 / Sonnet 4.5, ainda usam budget_tokens como único modo. O controle de profundidade passou para output_config: {"effort": ...}, com cinco níveis (padrão high na maioria dos modelos, medium no Opus 5.5 e no Haiku 5.5), e mudar o effort estoura o cache do mesmo jeito que mudar o orçamento estourava. A visibilidade é governada por display: o padrão da nova geração é "omitted" (blocos de pensamento vazios), e você paga pelos tokens de pensamento inteiros de qualquer forma — meça com usage.output_tokens_details.thinking_tokens; nenhuma configuração devolve a cadeia de raciocínio bruta. Desligar o pensamento no Opus 5 tem efeitos colaterais documentados (chamadas de ferramenta escritas como texto comum, tags internas vazando na saída), então abaixar o effort é a alavanca de custo mais segura. O pensamento intercalado — raciocinar entre as chamadas de ferramenta — é automático no adaptativo, sem o velho header beta. E, quando a velocidade importa, o fast mode roda o mesmo Opus a cerca de 2,5x pelo dobro do preço (só Opus 5.5/5/4.8, alternado com /fast no Claude Code). Tudo se apoia na documentação oficial da Anthropic: Thinking, Extended thinking e Fast mode.