Claude Code: Gerenciamento de Contexto

Última atualização: 2026-08-31

O contexto é a "memória de trabalho" do Claude Code — gerenciar contexto bem significa gerenciar a capacidade de compreensão do Claude Code e sua fatura de API.

📋 Pré-requisitos: Capítulo 9 - Guia de Uso do CLAUDE.md

1. O Que Você Vai Aprender

• Mecanismo de janela de contexto
• Análise e otimização de consumo de Tokens
• Estratégias de contexto para projetos grandes
• Métodos manuais de controle de contexto
• Equilíbrio entre custo e qualidade

2. Mecanismo de Janela de Contexto

(1) Composição do Contexto

(2) Ciclo de Vida do Contexto

Início da sessão → Carregar CLAUDE.md + prompt do sistema
              → Ler arquivos relevantes baseado nas instruções
              → Cada rodada acumula histórico
              → Conteúdo antigo truncado ao se aproximar do limite
              → Sessões longas podem degradar em qualidade

▶ Exemplo 1: Ver Uso de Contexto

> /cost

Token usage:
  System prompt:     4,230 tokens
  CLAUDE.md:         1,850 tokens
  Project files:    52,400 tokens (12 files)
  Conversation:     28,600 tokens (8 turns)
  Code output:       8,920 tokens
  ─────────────────────────────────
  Total:            96,000 / 200,000 tokens (48%)
  Estimated cost:    $1.82

3. Estratégias de Otimização de Tokens

(1) Reduzir Leituras Desnecessárias de Arquivos

(2) Comparação de Precisão de Instruções

# Alto consumo (lê projeto inteiro)
> Help me refactor this project

# Consumo médio (escopo limitado)
> Refactor all services under src/services/

# Baixo consumo (arquivos precisos)
> Refactor src/services/user.service.ts, extract validation logic to separate file

▶ Exemplo 2: Comparação de Consumo de Tokens

# Instrução vaga: ~80K tokens, $1.60
> Add a user search endpoint to the project

# Instrução precisa: ~25K tokens, $0.50 (70% de economia)
> In src/routes/user.ts, add GET /api/users/search endpoint,
> using searchUsers method from src/services/user.service.ts,
> following the search endpoint format in src/routes/product.ts

4. Estratégias de Contexto para Projetos Grandes

(1) Trabalho Particionado

<!-- Limitar escopo de trabalho no CLAUDE.md -->
## Current Work Scope
- Principal: diretório src/api/
- Models: diretório src/models/
- Tarefa atual: Módulo de permissões de usuário

## Not Currently Relevant
- src/frontend/ (desenvolvimento frontend independente)
- src/migrations/ (migração de BD completa)
- docs/ (documentação mantida separadamente)

(2) Carregamento Sob Demanda

# Não carregar todos os arquivos de uma vez
> ❌ "Read all route files and refactor"
> ✅ "Read src/routes/user.ts and add pagination support"

# Continuar após completar
> "Now read src/routes/order.ts and add same pagination"

(3) Segmentação de Sessões

# Dividir tarefas longas em sessões curtas

# Sessão 1: Design do modelo
claude "Design user permission DB model, only read prisma/schema.prisma"
# Ctrl+D sair

# Sessão 2: Middleware
claude "Based on the permission model, implement RBAC middleware"

# Sessão 3: Integração de rotas
claude "Integrate RBAC middleware into all routes needing permission checks"

5. Controle Manual de Contexto

(1) Comandos na Sessão

▶ Exemplo 3: Antes/Depois da Otimização

# Antes: Instrução vaga — 156K tokens ($3.12)
> Fix all test failures

# Depois: Instrução precisa — 32K tokens ($0.64)
> Run npm test, only fix 3 failing tests in auth module,
> don't read frontend files

Economia: 80%

❓ Perguntas Frequentes

P: E se 200K tokens não forem suficientes? R: Use /clear para resetar a conversa, ou divida em múltiplas sessões curtas. 200K geralmente é suficiente para tarefas únicas; apenas sessões longas podem exceder.

P: /compact reduz a qualidade? R: Levemente. A compressão mantém informação chave mas perde detalhes da conversa. Recomenda-se /clear na mudança de tópico em vez de /compact.

P: Como saber quais arquivos o Claude Code leu? R: O Claude Code exibe caminhos de arquivo para cada operação. Também use /files para ver arquivos atualmente carregados.

P: Posso impedir o Claude Code de ler certos arquivos? R: Escreva "não ler diretório xxx" no CLAUDE.md, mas a conformidade não é 100%. Use .claudeignore para arquivos sensíveis.

P: O que acontece quando o contexto está quase cheio? R: O Claude Code pode começar a esquecer conteúdo anterior da conversa; a qualidade das respostas degrada. Hora de /clear ou iniciar nova sessão.

P: É normal a grande variação de consumo de Tokens? R: Sim. Consultas simples podem usar 5K tokens, refatorações complexas 100K+. A precisão das instruções é o maior fator.

📖 Resumo

• Janela de contexto de 200K tokens; arquivos do projeto e histórico de conversa são os principais consumidores
• Instruções precisas podem reduzir 30-70% do consumo de Tokens
• Projetos grandes usam CLAUDE.md para limitar escopo de trabalho, processamento particionado
• Sessões curtas + checkpoints git superam sessões ultra-longas
• /clear, /compact, /cost são os três comandos centrais de gerenciamento de contexto

📝 Exercícios

1. Básico (⭐): Execute /cost em um projeto, registre o consumo de Tokens para uma tarefa simples vs complexa.
2. Intermediário (⭐⭐): Complete a mesma tarefa com instruções vagas e precisas, compare consumo de Tokens e qualidade.
3. Avançado (⭐⭐⭐): Desenhe estratégia de gerenciamento de contexto para um projeto com 50+ arquivos, alcançando 50% de redução de Tokens.

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós