As 18 armadilhas do Claude Code em projeto real

Todas as dezoito estão documentadas na fonte oficial. Nenhuma delas gera erro no console.

Essa combinação é o que as torna caras: o comportamento é esperado, previsto e explicado — só que numa página que você lê depois de perder a tarde. E a documentação descreve o mecanismo, não o sintoma. Quem está no meio do problema não sabe que precisa procurar por "auto-compaction" ou "tool listing budget"; sabe apenas que "o Claude esqueceu o que eu pedi" ou "a skill parou de funcionar".

Esta lista faz a tradução na direção que interessa: do sintoma para a causa.

1. O CLAUDE.md inchou e a aderência caiu

Sintoma: o agente começa a ignorar instruções que ele seguia antes, principalmente em tarefas longas.

Causa: o arquivo é carregado inteiro no contexto de toda sessão. A documentação é direta: arquivos mais longos consomem mais contexto e reduzem a aderência. O alvo oficial é abaixo de 200 linhas.

Correção: corte o que o agente deriva do código sozinho — layout de diretórios, lista de dependências, visão geral de arquitetura. É exatamente o que o /doctor propõe podar. O que sobra vira .claude/rules/ com paths ou skill.

2. A instrução sumiu depois do /compact

Sintoma: algo que estava funcionando para de valer no meio da sessão, sem aviso.

Causa: o CLAUDE.md da raiz do projeto sobrevive à compactação — o agente relê do disco e reinjeta. Mas CLAUDE.md aninhados em subpastas e regras com paths: não são reinjetados automaticamente. Eles só voltam quando o agente ler de novo um arquivo daquela pasta.

Correção: instrução que precisa valer sempre não pertence a arquivo aninhado. Suba para a raiz, ou transforme em hook se precisar de garantia.

3. Duas regras se contradizem e o agente escolhe uma

Sintoma: comportamento inconsistente entre sessões, sem padrão aparente.

Causa: os CLAUDE.md de escopos diferentes se concatenam, não se sobrescrevem. Se duas instruções se contradizem, o agente pode escolher qualquer uma arbitrariamente.

Correção: revise periodicamente o conjunto inteiro (CLAUDE.md de projeto, aninhados e .claude/rules/) procurando conflito. O /context lista o que efetivamente carregou.

4. Em monorepo, você herda o contexto de outro time

Sintoma: o agente aplica convenção que não é do seu módulo.

Causa: o Claude Code sobe a árvore de diretórios a partir do diretório atual e concatena tudo que encontra. Num monorepo, isso inclui CLAUDE.md de times vizinhos.

Correção: claudeMdExcludes no .claude/settings.local.json, com padrão glob apontando para os arquivos que não são seus.

5. Você quebrou o CLAUDE.md em imports e não economizou nada

Sintoma: o contexto continua igual depois de reorganizar tudo.

Causa: imports com @caminho organizam a leitura para humanos, mas os arquivos importados carregam no lançamento do mesmo jeito. Não há economia de token.

Correção: para reduzir contexto de verdade, use .claude/rules/ com frontmatter paths — essas regras só entram quando o agente lê um arquivo que casa com o glob.

As cinco acima estão detalhadas na anatomia de um CLAUDE.md que funciona.

6. A sessão ficou aberta o dia todo

Sintoma: a conta triplica sem que o volume de trabalho tenha mudado.

Causa: o Claude Code envia a conversa inteira em toda requisição. Com prompt caching o histórico é relido em tarifa de cache, mas uma pergunta de uma linha numa sessão aberta desde de manhã ainda consome pelo histórico completo.

Correção: /clear ao trocar de assunto. Use /rename antes, para achar a sessão depois com /resume.

7. A primeira mensagem depois do almoço custou caro

Sintoma: um pico de consumo isolado, sem tarefa grande correspondente.

Causa: cache miss. A vida útil do cache é de uma hora numa assinatura, e cai para cinco minutos quando você passa a consumir usage credits ou usa chave de API. Passou disso, o contexto inteiro é reprocessado.

Correção: em assinatura, ENABLE_PROMPT_CACHING_1H=1 mantém a hora mesmo consumindo créditos. Fora isso, é aceitar o custo ou limpar antes da pausa.

8. O Opus ficou como padrão em tudo

Sintoma: custo por tarefa desproporcional à complexidade dela.

Causa: é uma das duas causas mais comuns de fatura inesperada, junto com sessão nunca limpa.

Correção: Sonnet resolve a maior parte do trabalho de código. Reserve Opus para decisão de arquitetura e raciocínio de vários passos. model: haiku em subagente de tarefa simples corta ainda mais.

9. O extended thinking está ligado em tarefa trivial

Sintoma: consumo de saída maior que o texto produzido.

Causa: o extended thinking vem ligado por padrão, os tokens de raciocínio são cobrados como tokens de saída, e o orçamento padrão pode chegar a dezenas de milhares de tokens por requisição.

Correção: /effort num nível mais baixo para tarefa simples.

10. O /compact também é caro

Sintoma: compactar para economizar contexto gerou um pico de consumo.

Causa: o /compact precisa ler a conversa que vai resumir. Compactar contexto grande é, ele próprio, uma requisição grande.

Correção: quando você quer começar do zero em vez de manter continuidade, /clear não custa nada.

Os números oficiais de custo por desenvolvedor estão no guia de Claude Code em produção.

11. A skill parou de disparar sozinha

Sintoma: o /nome-da-skill funciona, mas o agente nunca a invoca por conta própria.

Causa: a listagem de nomes e descrições tem orçamento de 1% da janela de contexto. Quando estoura, o Claude Code corta as descrições começando pelas skills que você menos invoca — e sem descrição, o agente não tem texto para casar com o seu pedido.

O ciclo se fecha sozinho: skill nova nunca foi usada, perde a descrição primeiro, e sem descrição continua sem ser usada.

Correção: /doctor estima o custo da listagem e mostra os maiores contribuintes. Remova o que você não usa, marque entradas de baixa prioridade como "name-only" em skillOverrides, ou suba o orçamento com skillListingBudgetFraction.

12. O /comando funciona mas o agente ignora a skill

Sintoma: parecido com o anterior, mas acontece mesmo com poucas skills instaladas.

Causa: YAML do frontmatter malformado. Nesse caso o Claude Code carrega o corpo com metadados vazios — o comando continua funcionando, e não existe description para o agente usar.

Correção: rode com --debug para ver o erro de parse.

13. Você moveu tudo do CLAUDE.md para skill e piorou

Sintoma: o agente volta a errar aquilo que a skill deveria resolver.

Causa: duas coisas. A skill só entra no contexto se for invocada — se a descrição não bate com o jeito que você pede, ela nunca é. E há medição pública contra o instinto de esvaziar o arquivo: ao documentar a migração para o Next.js 16, a Vercel afirma que conhecimento de framework deve vir de docs sempre carregados, porque em benchmark próprio contexto sempre disponível superou recuperação sob demanda.

Correção: enxugar o CLAUDE.md é remover o que o agente deriva sozinho. Não é mover para skill tudo que ele precisa em toda tarefa.

14. A skill de um repositório de terceiro se autoconcedeu acesso

Sintoma: nenhum — e esse é o problema.

Causa: confiança de workspace não bloqueia o campo allowed-tools. O allowed-tools de uma skill de projeto é aplicado sempre que ela é invocada, inclusive numa execução -p numa pasta que você nunca marcou como confiável.

Correção: revise o allowed-tools de skills que vêm num repositório antes de rodar Claude Code ali, com o mesmo cuidado de um script de build.

O formato completo, incluindo o orçamento de listagem, está em como escrever a sua primeira Agent Skill.

15. O subagente funciona quando você testa e falha sozinho

Sintoma: comportamento diferente entre execução em primeiro plano e em background.

Causa: subagente em background perde quase todas as ferramentas embutidas. Sobra uma allowlist específica — Read, Grep, Glob, Bash, Edit, Write, WebFetch, WebSearch e mais algumas.

Correção: teste no modo em que ele vai rodar. Se precisar de ferramenta fora da allowlist, force primeiro plano.

16. O subagente ignorou a skill que você acabou de invocar

Sintoma: o subagente se comporta como se a skill não existisse.

Causa: para ele, não existe. Subagente não carrega histórico da conversa, output style, memória automática nem skills invocadas antes.

Correção: o campo skills no frontmatter pré-carrega o que ele precisa.

17. O deploy errado rodou

Sintoma: você tem uma skill e um subagente com o mesmo nome, e o comportamento não é o que você previu.

Causa: a precedência é invertida entre as duas features. Em skill, o escopo pessoal sobrepõe o de projeto. Em subagente, o de projeto sobrepõe o pessoal.

Correção: não é bug, é assimetria documentada. Cheque qual das duas você está invocando antes de investigar o conteúdo.

18. Um time de agentes se formou sem você pedir

Sintoma: consumo muito acima do esperado (até cerca de 7x quando os teammates rodam em plan mode), e um fluxo que espera resultado de subagente trava.

Causa: com CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, um subagente que o Claude nomeia por conta própria é lançado como teammate. E teammate notifica que ficou ocioso sem devolver a saída — então orquestração que espera o resultado fica parada.

Correção: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0 devolve o comportamento de subagente. Não precisa reiniciar a sessão: o Claude Code relê a variável a cada criação.

A comparação completa está em subagentes: quando delegar e quando não.

Se você chegou aqui com um sintoma na mão, esta tabela encurta o caminho.

Três observações sobre a ordem de investigação.

Comece sempre pelo /context. Metade das armadilhas desta lista aparece ali como um número fora do lugar: CLAUDE.md grande demais, linha de Skills inchada, servidor MCP que você não reconhece. É mais rápido olhar do que deduzir.

Desconfie de coincidência temporal. Se o comportamento mudou depois que você instalou algo, adicionou servidor MCP ou atualizou o Claude Code, o culpado quase sempre é essa mudança — e não o modelo tendo um dia ruim.

Não conserte dois de uma vez. Como nenhuma dessas armadilhas dá erro, você não tem sinal de confirmação. Corrigindo uma por vez você sabe qual resolveu; corrigindo três, você só sabe que parou de doer.

Ficaram de fora porque são de integração, não de configuração do agente. Valem o aviso mesmo assim.

O escopo "local" do MCP não é o "local" das configurações. O servidor fica em ~/.claude.json, não no .claude/settings.local.json do projeto. Quem procura no lugar errado conclui que a instalação falhou.

Na precedência de servidor MCP, os campos não se mesclam. Se existe um servidor de mesmo nome em escopo local, ele vence inteiro — os headers que você configurou no .mcp.json do projeto não são herdados.

Variável de ambiente faltando não quebra o .mcp.json. O config carrega, o Claude Code avisa no claude mcp list, e o texto ${VAR} é usado literalmente. O servidor sobe com Bearer ${API_KEY} no header e falha só na primeira chamada.

As três estão detalhadas em MCP na prática.

Nenhuma quebra de uma vez.

Todas degradam ao longo de semanas até você concluir que "o Claude Code piorou". Ele não piorou — o seu contexto engordou, a sua listagem estourou, a sua sessão nunca foi limpa.

É por isso que a manutenção precisa ser calendarizada em vez de reativa. Vinte minutos por mês resolvem:

O /usage sinaliza automaticamente qualquer comportamento que responda por 10% ou mais do consumo recente, como contexto longo ou cache miss. É o exame de sangue do setup.

E o /insights é o menos usado dos quatro, sendo o mais útil para esta lista. Ele analisa até 200 sessões da sua máquina e escreve um relatório sobre como você trabalha, com uma seção de atrito que nomeia os pedidos mal interpretados. Se a mesma classe de tarefa aparece ali toda semana, você achou uma armadilha que não está nesta lista porque é específica do seu projeto.

Se você quer saber o peso de cada uma dessas armadilhas em dinheiro, a medição de custo por padrão de uso traz a conta em 46 mil turnos reais.

Qual dessas armadilhas custa mais dinheiro?

Sessão nunca limpa e Opus como padrão. A documentação cita as duas como as causas mais comuns de gasto inesperado em plano por token. As duas têm correção de dez segundos.

E qual custa mais tempo?

A listagem de skills estourando o orçamento, porque o sintoma não sugere a causa. Você acha que a skill está mal escrita, reescreve a descrição, e o problema é que ela foi truncada antes de chegar ao modelo.

Como sei se estou caindo em alguma dessas agora?

/context mostra o que carregou e o tamanho de cada fonte. Se o seu CLAUDE.md passa de 200 linhas, se a linha de Skills está grande, ou se há servidor MCP que você não reconhece, você já achou pelo menos uma.

Isso muda com versão nova do Claude Code?

Muda. Vários desses comportamentos têm nota de versão na documentação — o de agent teams e o de atribuição de MCP no /usage mudaram recentemente. claude --version e a data de verificação no rodapé deste post são o ponto de partida para conferir.

• Anthropic — Claude Code Docs: Manage costs effectively. Acesso em 19/08/2026.
• Anthropic — Claude Code Docs: How Claude remembers your project. Acesso em 19/08/2026.
• Anthropic — Claude Code Docs: Extend Claude with skills. Acesso em 19/08/2026.
• Anthropic — Claude Code Docs: Sub-agents. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: Orchestrate teams of Claude Code sessions. Acesso em 19/08/2026.
• Anthropic — Claude Code Docs: Connect Claude Code to tools via MCP. Acesso em 20/08/2026.
• Next.js — How to set up your Next.js project for AI coding agents. Acesso em 20/08/2026.

Verificado em 20 de agosto de 2026.

Nota de método: as dezoito são comportamentos documentados nas fontes acima. O que esta lista acrescenta é o mapeamento do sintoma — como cada comportamento se manifesta antes de você saber o que procurar. Nenhum número aqui é estimativa: os limites de 200 linhas, 1% da janela, 7x de tokens em plan mode e 10% de sinalização vêm da documentação oficial, com as mesmas condições que ela declara.

Gatilho de reavaliação: revisar quando qualquer um dos limites citados mudar, quando agent teams deixarem de ser experimentais, ou quando a assimetria de precedência entre skills e subagentes for alinhada.