Trabalhando com o
Claude Code

Contexto · como o modelo pensa · prompt · skills · memória · modelos e effort

Síntese da documentação oficial da Anthropic — novembro de 2026

1. Modelo + harness

O modelo raciocina. O harness faz o resto.

Quem faz o quê

Modelo

Opus · Sonnet · Haiku

  • Raciocina e responde
  • Não tem memória entre sessões
  • Só "sabe" o que está na janela de contexto

Harness

Claude Code

  • Fornece ferramentas
  • Monta o contexto
  • Executa e aplica permissões

Cada sessão começa com a janela vazia. A continuidade vem do que o harness carrega no início: CLAUDE.md, memória, skills, hooks.

2. Janela de contexto

Um orçamento de atenção finito

O que já está lá antes de você digitar

  • System prompt
  • Nomes das tools MCP (definição completa só quando usada)
  • Descriptions de skills e subagents
  • ~/.claude/CLAUDE.md + CLAUDE.md / AGENTS.md do projeto
  • MEMORY.md da auto-memory (até 200 linhas / 25KB)
  • Ambiente + o que os hooks de SessionStart injetam

Durante o trabalho entram: cada arquivo lido, cada saída de comando, as próprias respostas, rules com paths:.

Context rot

Quanto mais tokens, pior a atenção e a recuperação de informação.

  • A meta é o menor conjunto de tokens relevantes que resolve a tarefa
  • Janela de 1M não significa encher até 1M
  • Subagent pesquisa na janela dele e devolve só um resumo

Compaction: o que sobrevive ao resumo

Sobrevive

  • System prompt
  • CLAUDE.md da raiz
  • Rules sem paths
  • Auto-memory
  • Descriptions de skills
  • Plano do plan mode
  • Até 5 arquivos editados

Se perde

  • Contexto injetado por hooks
  • Rules com paths já carregadas
  • Corpo de skill volta limitado a 5k tokens por skill, 25k no total

Comandos de contexto

Comando Função
/context Mostra o que ocupa a janela, por categoria
/clear Limpa a janela — entre tarefas sem relação
/compact foca no bug de auth Resume agora, dizendo o que manter
/rewind ou Esc Esc Volta a um checkpoint (arquivos + conversa)
/btw Pergunta paralela fora do histórico
/memory Mostra memórias carregadas; liga/desliga auto-memory

3. Como a IA "pensa"

Loop agêntico

coletar contexto → agir → verificar → repetir

"Conserta os testes" vira:

  1. Rodar os testes
  2. Ler o erro
  3. Buscar e ler os arquivos
  4. Editar
  5. Rodar de novo

Thinking adaptativo

  • Modelos 5.x sempre raciocinam antes de responder
  • A profundidade depende do effort e da complexidade do pedido
  • Effort baixo + pergunta fácil → pode quase pular o raciocínio
  • O antigo budget_tokens foi descontinuado — o effort substitui

Instrução é contexto, não regra

Lido pelo modelo

pode errar ou ignorar

  • CLAUDE.md
  • Skills
  • Prompts

Aplicado pelo harness

garantido

  • Hooks
  • permissions.deny
  • Managed settings

Se uma linha do CLAUDE.md vive sendo ignorada mesmo com ênfase, ela devia ser um hook.

Como escrever a instrução

  • Ênfase demais atrapalha: IMPORTANT / MUST / CRITICAL fazem os modelos novos aplicarem a regra em excesso
  • Ele generaliza a partir do porquê

❌ "NUNCA use reticências"
✅ "O texto vai para um leitor de voz, então sem reticências"

4. Prompt

Trate o modelo como um funcionário brilhante e novo

8 regras de prompt

  1. Funcionário novo: um colega sem contexto entenderia?
  2. Específico: arquivo, sintoma e como fica "pronto"
  3. Peça ação: "mude a função X" > "pode sugerir?"
  4. Critério de verificação + evidência (comando e saída)
  1. Diga o que ele não vê — só o que ele não acharia lendo o código
  2. Exemplos: 3 a 5, variados; dados longos primeiro, pergunta no fim
  3. Diga o que fazer, não o que evitar
  4. Revisão: "aponte o que afeta a correção, ignore estilo"

5. Camadas de customização

Qual usar quando

Sempre carregados

Mecanismo Carrega Custo Use para
CLAUDE.md / AGENTS.md (raiz) Sempre Alto Build/teste, convenções, armadilhas — < 200 linhas
CLAUDE.md de subpasta Ao mexer lá Baixo Regras daquela parte do repo
Rules .claude/rules/*.md Sempre, ou só nos paths Baixo/médio Regra de uma área específica
Auto-memory MEMORY.md sempre Baixo Fatos que o Claude aprende com você

Sob demanda ou fora do contexto

Mecanismo Carrega Custo Use para
Skill Description sempre, corpo sob demanda Baixo Procedimento: deploy, release, checklist
Subagent Janela separada Isolado Busca grande, logs, revisão independente
Hook Eventos do ciclo de vida ~zero "Sempre que X, faça Y" com garantia
Permissions Harness Zero Bloquear ou liberar tools
MCP Nome sempre, definição sob demanda Baixo Integração com sistema externo

Regras práticas da Anthropic

  • Procedimento de 30 linhas no CLAUDE.md → skill
  • "Sempre faça X" → hook
  • Preferência pessoal → ~/.claude/CLAUDE.md ou CLAUDE.local.md
  • Subagent quando a saída intermediária poluiria a conversa
  • Skill quando você quer ver e conduzir cada passo

Skills em detalhe

  • Pasta com SKILL.md (name + description) e arquivos de apoio
  • Carregamento progressivo: frontmatter sempre → corpo quando invocada → apoio só se precisar
  • Crie quando cola o mesmo procedimento no chat várias vezes
  • Corpo < 500 linhas; referências em arquivos separados

⚠️ As descriptions dividem 1% da janela. Se estourar, as das skills menos usadas somem da listagem, sem aviso.

Campos úteis do frontmatter

Campo Efeito
disable-model-invocation: true Só você chama (/nome) — bom para deploy
user-invocable: false Só o modelo chama
model / effort Troca modelo/effort só durante a skill
context: fork Roda como subagent
paths Só ativa automaticamente em certos arquivos

6. Memória e AGENTS.md

Onde ficam os CLAUDE.md

  • ~/.claude/CLAUDE.md — global
  • ./CLAUDE.md ou ./.claude/CLAUDE.md — do projeto, vai para o git
  • CLAUDE.local.md — pessoal, no .gitignore
  • Carrega todos da pasta atual para cima; os de subpasta quando mexe nelas
  • Imports com @caminho/arquivo.md (até 4 níveis) — não economizam contexto

AGENTS.md

Por padrão, o Claude Code só lê o AGENTS.md se não existir CLAUDE.md na pasta atual ou acima.

Para manter os dois:

  • @AGENTS.md no topo do CLAUDE.md (recomendado)
  • ou /config → Project instructions → claude-md-and-agents-md

Auto-memory

  • Fica em ~/.claude/projects/<repo>/memory/ — uma por repositório
  • MEMORY.md carrega até 200 linhas / 25KB; tópicos sob demanda
  • "Lembra disso" → auto-memory · "coloca no CLAUDE.md" → CLAUDE.md
  • Não é carregada em subagents

Auditoria: /doctor prompt-audit revisa CLAUDE.md, rules, skills e agents atrás de coisa desatualizada ou conflitante.

7. Modelos e effort

Modelo = o que ele consegue fazer
Effort = o quanto ele se esforça

Modelos

Alias Uso
opus (Opus 5.5) / best Raciocínio complexo, arquitetura
sonnet (Sonnet 5.5) Código do dia a dia
haiku (Haiku 5.5) Tarefa simples e rápida, subagent de busca
fable (Fable 5.2) Família à parte
opusplan Opus no plan mode, Sonnet na execução
opus[1m] / sonnet[1m] Janela de 1M

Effort

Padrão do Opus / Sonnet / Haiku 5.5: medium

Nível Quando
low Troca rápida, brainstorm, rename
medium Feature do dia a dia
high Bug, casos de borda
xhigh Raciocínio profundo, mais tokens
max Problema difícil e autônomo — tende a pensar demais

Como ajustar o effort

  • /effort (slider) ou /effort high
  • Setas ← / → dentro do /model
  • claude --effort xhigh
  • effortLevel no settings · CLAUDE_CODE_EFFORT_LEVEL
  • effort: no frontmatter de skill ou subagent
  • ultrathink no prompt — vale para uma mensagem

Effort ou modelo? A regra da Anthropic Academy

Ele sabia, mas não se esforçou

Parou cedo, deixou incompleto

→ Suba o effort um nível

Faltou capacidade

Não conseguiria nem com mais esforço

→ Troque o modelo

Ao trocar de modelo, volte ao effort padrão dele.

Subagents: quando valem

  • model: haiku + tools: Read, Grep, Glob = investigador barato
  • Subagent custa tokens e não deixa a resposta mais inteligente
  • Serve para:
    • paralelismo
    • isolar saída grande
    • revisão independente

8. Começando um trabalho

O fluxo

  1. Contexto limpo — /clear se a tarefa não tem relação com a anterior
  2. Pedido vago → brainstorm: "me entrevista até escrever a spec, salva em SPEC.md" — depois, sessão nova para implementar
  3. Explorar → planejar → codar → commitar — plan mode (Shift+Tab) em mudança grande
  4. Prompt específico com critério de "pronto" verificável
  5. Effort conforme a tarefa: medium padrão, high bug, low mecânico
  6. Pesquisa grande → subagent
  7. Corrija o rumo: Esc interrompe, /rewind volta — 2 correções sem resultado → /clear e prompt melhor
  8. Termine com evidência (teste rodado e saída), depois commit

O que vale guardar

O quê Onde
Regra CLAUDE.md
Fato Memória
Procedimento repetido Skill
"Sempre / nunca" com garantia Hook

Referências