Claude Code - Dicas para otimizar o uso de tokens

Hoje eu vou apresentar algumas dias para otimizar o uso de tokens no Claude Code. Afinal token é dinheiro...!!!

Você sabia que o Claude não possui memória interna persistente entre interações; ele depende do histórico da conversa que é reenviado ao modelo a cada nova mensagem ?

Na prática, durante uma sessão:

O Claude mantém o contexto porque o sistema reenvia o histórico;
Ele consegue lembrar decisões tomadas anteriormente;
Consegue continuar uma tarefa complexa;
Consegue referenciar arquivos lidos anteriormente.

Mas isso ocorre porque o histórico está sendo reenviado, não porque o modelo armazenou algo internamente.

O consumo de tokens não é causado apenas pelo que você digitou. Muitos desenvolvedores acreditam que um prompt de 20 palavras custa apenas 20 palavras.

Na realidade, quando a sessão já contém:
  10 arquivos carregados;
  30 respostas anteriores;
  resultados de ferramentas;
  especificações;
  CLAUDE.md;

Aquele prompt de 20 palavras pode provocar o reenvio de centenas de milhares de tokens.

É exatamente por isso que comandos como /compact, sessões novas e bons arquivos CLAUDE.md costumam gerar economia significativa de tokens.

Desta forma, toda vez que você envia uma mensagem, a conversa inteira é reenviada do zero: seus prompts, as respostas do Claude e todos os resultados das ferramentas. Tudo isso, todas as vezes. Ele não está lendo um log; está literalmente reprocessando todo o histórico a cada interação.

É assim que os transformers funcionam.

Portanto, a contagem de tokens das mensagens não é apenas "o que você digitou". É o total acumulado de tudo o que já foi dito ou lido na sessão, reenviado repetidamente.

Então o que eu devo fazer para evitar isso ?

Muitas pessoas ignoram isso:  A ação de maior impacto que você pode realizar antes de escrever uma única linha de código é executar o comando /init para gerar um arquivo CLAUDE.md na raiz do projeto.

O Claude lê este arquivo automaticamente no início de cada sessão.

Pense nele como suas instruções permanentes — aquelas coisas que você normalmente explicaria do zero todas as vezes.

Existem vários locais de busca, verificados nesta ordem:

~/.claude/CLAUDE.md — carregado para todos os projetos, em todas as sessões (global)
/seu/projeto/CLAUDE.md — carregado quando você inicia o Claude Code nesse diretório
Arquivos CLAUDE.md em subdiretórios — carregados à medida que o Claude navega por essas pastas

O modelo de custo em tokens

O CLAUDE.md é carregado em toda sessão e permanece na janela de contexto durante toda a sessão. Ele não é carregado sob demanda nem removido quando não está sendo utilizado.

Um arquivo CLAUDE.md de 2.000 tokens custa 2.000 tokens, independentemente de você enviar 2 ou 200 mensagens.

Cada instrução adicionada é paga em todas as sessões para sempre. Um CLAUDE.md inchado (5.000+ tokens) reduz significativamente seu contexto efetivo de trabalho.

Arquivos em subdiretórios se acumulam. Isso é útil em monorepositórios. Divida seu CLAUDE.md por projeto em vez de ter apenas um. Eles não são carregados simultaneamente; são carregados conforme o Claude navega pelos diretórios.

Um CLAUDE.md bem estruturado para um projeto real geralmente possui entre 300 e 600 tokens. Se o seu ultrapassa 2.000 tokens, provavelmente você está armazenando estado de tarefas ou documentação que não deveria estar ali.

Exemplo de um CLAUDE.md:

# CLAUDE.md

## Stack

- .NET 10
- ASP.NET Core
- C#
- Entity Framework Core
- SQL Server ou SQLite
- Blazor Web App quando aplicável

## Testes

- xUnit
- FluentAssertions
- Moq

## Arquitetura

- Controllers chamam Services
- Services contêm regras de negócio
- Repositórios são responsáveis pelo acesso a dados
- Nunca acessar o DbContext diretamente a partir de Controllers
- Sempre usar Injeção de Dependência
- Respeitar o princípio da responsabilidade única (SRP)

## Restrições

- Nunca usar `dynamic` sem justificativa explícita
- Habilitar Nullable Reference Types
- Evitar lógica de negócio em Controllers, Components ou Pages
- Evitar métodos excessivamente longos (preferir métodos pequenos e focados)
- Evitar duplicação de código
- Priorizar código legível sobre soluções excessivamente complexas

## Entity Framework Core

- Utilizar migrations para alterações de banco de dados
- Preferir consultas assíncronas
- Evitar consultas N+1
- Utilizar `AsNoTracking()` para consultas somente leitura
- Configurações Fluent API devem ficar em classes separadas

## Convenções de Nomenclatura

- Classes: PascalCase
- Interfaces: prefixo `I` (`IClienteService`)
- Métodos: PascalCase
- Propriedades: PascalCase
- Campos privados: `_camelCase`
- Variáveis locais e parâmetros: `camelCase`
- Constantes: PascalCase
- Arquivos: mesmo nome da classe principal

## Blazor

- Componentes em PascalCase
- Lógica complexa deve ser movida para Services
- Evitar código excessivo dentro de arquivos `.razor`
- Preferir componentes reutilizáveis
- Utilizar renderização adequada ao cenário (SSR, Server, WebAssembly ou Auto)

## Código

- Gerar código seguindo os padrões oficiais da Microsoft
- Priorizar simplicidade e manutenibilidade
- Sempre considerar performance, segurança e testabilidade
- Explicar decisões arquiteturais quando elas não forem óbvias

Para projetos usando Blazor Web App (.NET 9/10), eu adicionaria também uma seção específica para renderização e compartilhamento de código:

A seguir vou apresentar algumas dicas para otimizar o uso de tokens que podem variar dependendo da ferramenta usada. Estamos focando no Claude Code.

1. Use /context para mostrar o uso da janela de contexto

Você pode executar /context e o Claude mostrará tudo que está ocupando sua janela de contexto: arquivos abertos, documentos anexados, definições de ferramentas, mensagens da conversa e o prompt de sistema.

Ele retorna uma visão estruturada com a contagem de tokens por elemento e o uso acumulado em relação ao limite da janela.

O Claude frequentemente carrega arquivos para o contexto que já não são mais necessários. Assim este comando é útil para :

- Identificar arquivos que foram carregados sem necessidade
- Descobrir quando uma conversa ficou longa demais
- Decidir entre compactar ou começar uma nova sessão
- Entender melhor o que está acontecendo

Pense nisso como um profiler de memória da sua sessão.

2. Use /compact para salvar a sua sessão

A solução prática é mais simples do que parece: "Comece em uma nova aba do terminal."

Além disso, evite colar arquivos inteiros quando apenas um trecho é relevante. Quando uma sessão ficar longa, resuma o que importa e leve apenas isso para uma nova conversa.

Para isso, execute /compact.

Ele resumirá toda a conversa em uma representação compacta e estruturada, registrando decisões tomadas, código escrito, questões em aberto e o estado atual da tarefa. Depois, continua a partir desse resumo como uma nova base.

A compactação é propositalmente com perdas.

O que é Preservado:
  Decisões arquiteturais e justificativas
  Arquivos modificados e alterações realizadas
  Estado atual da tarefa e próximos passos
  Erros encontrados e como foram resolvidos
  Bloqueios pendentes

O que é Descartado:
  Cadeias intermediárias de raciocínio
  Abordagens abandonadas
  Saídas brutas das ferramentas

Um erro comum é usar /compact apenas quando o Claude já começou a esquecer as coisas.
Isso está errado.

Uma sessão saudável produz um resumo melhor do que uma sessão degradada. Execute /compact ao concluir uma fase distinta do trabalho, não quando perceber degradação.

Se você terminou completamente uma tarefa e vai iniciar algo sem relação com ela, use /clear e não /compact.

 3. Use comandos customizados e pare de repetir a si mesmo

Os comandos customizados definem atalhos nomeados para sequências de instruções com múltiplas etapas.

Quando invocado, o Claude executa toda a sequência sem precisar reinterpretar a intenção em linguagem natural.

Os comandos são armazenados como definições estruturadas (nome, descrição e etapas), que o Claude lê no início da sessão junto com o CLAUDE.md.

Os Prompts em linguagem natural são probabilísticos. O mesmo prompt pode gerar comportamentos ligeiramente diferentes a cada execução.

Exemplo de comando customizado :   /test-and-fix

Em vez de escrever sempre um prompt longo como:

Execute todos os testes do projeto.
Corrija os erros de compilação encontrados.
Corrija os avisos do analisador.
Execute novamente os testes.
Mostre um resumo das alterações.

Você define um comando: test-and-fix e associa a ele essa sequência de instruções.

O Claude Code suporta Custom Commands através de arquivos Markdown dentro da pasta .claude/commands.

Por exemplo, você poderia criar:

.claude/
└── commands/
         └── test-and-fix.md

E criar um arquivo markdown assim:

Depois você poderia executar : /test-and-fix e o Claude executa esta sequência.

Onde você poderia aplicar o uso de comandos customizados ?

Executar testes + corrigir erros de tipo + rodar lint em sequência
Gerar componentes seguindo minhas convenções de pastas
Escrever mensagens de commit no padrão da equipe
Executar validações antes de deploy (embora hooks também possam ser usados)

4. O modo de raciocínio (reasoning mode) está ativado por padrão

Antes de fornecer qualquer resposta, o Claude executa um processo interno estendido de raciocínio.

Ele trabalha o problema, considera abordagens e avalia alternativas. Esse raciocínio acontece silenciosamente em segundo plano, independentemente de o problema ser pequeno ou grande.

Se você não precisa disso, desative.

a- Sem raciocínio aprofundado

Se você pedir: "Renomeie a variável customerList para customers"
O modelo consegue responder quase imediatamente.
Não precisa analisar arquitetura, dependências ou alternativas.
É uma tarefa simples.

b- Com raciocínio aprofundado

Se você pedir: Analise esta arquitetura Blazor e proponha melhorias
O modelo pode gastar mais tempo:
  avaliando alternativas;
  analisando trade-offs;
  verificando padrões;
  planejando a solução.

Isso produz respostas melhores, mas consome mais recursos.

5. Não interrompa a tarefa principal use /btw

Imagine que você está trabalhando em uma tarefa grande: Implemente a autenticação JWT para esta API ASP.NET Core.

O Claude:
  está lendo arquivos;
  analisando serviços;
  entendendo a arquitetura;
  planejando alterações.

No meio disso você lembra de outra coisa e pergunta:  Aliás, qual a diferença entre IEnumerable e IQueryable?

Agora a conversa principal foi interrompida.

Sem /btw:
  essa pergunta entra no histórico;
  a resposta entra no histórico;
  ambos serão reenviados em todas as mensagens futuras.

Com /btw:
   você obtém a resposta;
   ela não "polui" a conversa principal.

Então a forma correta de fazer é : /btw qual a diferença entre IEnumerable e IQueryable?

6. Escolha o modelo correto

A maioria das pessoas abre o Claude Code, deixa o modelo padrão e nunca mais pensa nisso.

Em março de 2026, o padrão é:
   Sonnet no plano Pro
   Opus no plano Max

Aqui está uma regra simples:
  Opus ->   Cérebro grande, muito caro.
  Use apenas para planejar problemas difíceis no modo de planejamento.

  Haiku -> Cérebro pequeno.
  Bom para tarefas simples ou perguntas rápidas.
  Não é ideal para programação.

  Sonnet -> Cérebro suficientemente bom.
   Use para:
      Implementação de funcionalidades
      Refatorações
      Testes
      Revisões de código

Para alternar entre os modelos use:  /model

7. Pare de ser preguiçoso e escreva especificações, não prompts aleatórios

"Por favor, corrija isso. Não cometa erros." Enter.

A forma como você escreve o prompt afeta diretamente a quantidade de tokens gerados.

Prompts vagos incentivam respostas verbosas e consumo desnecessário de tokens apenas para tentar descobrir a que arquivo você está se referindo.

Se você já tem uma ideia do que precisa fazer — e deveria ter — escreva algo como:

Corrija o bug [descrição curta] em @arquivo que está causando [resultado inesperado] em vez de [resultado esperado]. eles.

8. MCPs não são a 'bala de prata'. Você não precisa capturar todos!

A maioria dos desenvolvedores adiciona servidores MCP conforme os descobre.

Supabase? Adiciona.
GitHub?  Adiciona.
Chrome DevTools? Adiciona.
Figma?  Adiciona.

O problema é que cada servidor MCP conectado carrega todas as suas definições de ferramentas e esquemas para a janela de contexto no início de cada sessão, independentemente de você usá-los ou não.

Essas definições não são pequenas. Às vezes consomem milhares de tokens apenas ficando ali paradas.

Adicione vários MCPs e os números rapidamente se tornam desconfortáveis.
Remova o que não precisa.

9. Trabalhar por "contextos delimitados" e não pela solução inteira

Vejo muitos desenvolvedores fazendo algo assim:

> "Analise minha solução inteira."
ou
> "Implemente a funcionalidade X."

Numa solução com diversas camadas. Isso faz o Claude carregar uma quantidade enorme de arquivos.

Uma estratégia melhor é trabalhar por contexto:

Exemplo ruim   :  
"Implemente o sistema de notícias."

Exemplo melhor  : 
  "Estamos trabalhando apenas no contexto Notícias.
Arquivos permitidos:
  - Noticia.cs
  - INoticiaRepository.cs
  - NoticiaRepository.cs
  - NoticiasService.cs
  Ignore o restante da solução."

Na prática:
  menos arquivos são lidos;
  menos ferramentas são chamadas;
  menos contexto é carregado;
  menos tokens são consumidos.

Para projetos Blazor e ASP.NET Core isso faz muita diferença.

10.  Use especificações hierárquicas (SDD em camadas)

Isso eu vejo poucas pessoas fazendo. Muitos desenvolvedores criam uma spec enorme:

spec.md
  - domínio
  - banco
  - UI
  - API
  - autenticação
  - testes
  - deploy
com milhares de linhas.

O Claude acaba carregando tudo para executar uma tarefa simples.

Uma abordagem melhor:

/specs
   overview.md

   dominio/
     jogadores.md
     partidas.md
     selecoes.md

   frontend/
     dashboard.md
     noticias.md

    backend/
      api.md
      autenticacao.md

Quando for trabalhar em notícias use :  @specs/frontend/noticias.md

Quando for trabalhar em autenticação:   @specs/backend/autenticacao.md

Em vez de carregar 10.000 linhas , você carrega 300 linhas.

Dica bônus

Essa eu considero uma das mais importantes para projetos .NET.
Não peça código imediatamente

Muitas pessoas fazem:' Implemente a funcionalidade.'

O Claude:
  analisa;
  planeja;
  gera código;
  cria testes;
  altera arquivos.

Tudo em uma única interação.

Uma alternativa muito mais econômica:

Etapa 1
   Analise e proponha um plano.
   Não gere código.
Etapa 2
   Implemente apenas a camada Domain
Etapa 3
   Agora implemente apenas Infrastructure.
Etapa 4
   Agora implemente apenas os testes.

O consumo total costuma ser menor porque você evita gerações enormes que depois serão descartadas.

Conclusão 

No fim das contas, economizar tokens não significa apenas reduzir custos ou evitar atingir limites de uso.

Significa trabalhar de forma mais eficiente com a IA. Manter o contexto enxuto, usar boas especificações, organizar instruções permanentes e dividir problemas complexos em etapas menores ajuda o modelo a produzir respostas melhores e mais consistentes.

Quanto mais intencional for o uso do contexto, maior será o valor que você extrai da ferramenta

E estamos conversados...  

"Porque os que são segundo a carne inclinam-se para as coisas da carne; mas os que são segundo o Espírito para as coisas do Espírito.Porque a inclinação da carne é morte; mas a inclinação do Espírito é vida e paz."
Romanos 8:5,6