0. Resumo (TL;DR)
Este artigo resulta de seis meses de uso intenso do Claude Code e lições aprendidas gastando US$ 40/mês em duas contas. Espero fornecer insights valiosos para todos.
Inicialmente, usei como ChatBot, mas logo percebi que algo estava errado: o contexto ficava confuso, as ferramentas aumentavam mas a eficácia diminuía, e as regras eram ignoradas mesmo sendo mais longas. Após pesquisar o Claude Code, percebi que não era um problema de Prompt, mas sim de design do sistema.
Quero discutir: como o Claude Code funciona internamente, por que o contexto fica confuso e como governá-lo, como projetar Skills e Hooks, o uso correto de Subagentes, o impacto arquitetural do Prompt Caching e como escrever um CLAUDE.md realmente útil.
A forma mais direta de entender é dividir o Claude Code em seis camadas:
Fortalecer apenas uma camada causa desequilíbrio. Se o CLAUDE.md for longo demais, polui o contexto; muitas ferramentas causam confusão; muitos subagentes levam à deriva de estado; pular a verificação impossibilita encontrar onde falhou.
1. Como funciona internamente
O núcleo do Claude Code não é "responder", mas um loop agêntico repetitivo:
1Coletar Contexto → Agir → Verificar Resultado → [Finalizar ou Repetir]2 ↑ ↓3 CLAUDE.md Hooks / Permissões / Sandbox4 Skills Ferramentas / MCP5 Memória
Percebi que gargalos raramente são por inteligência insuficiente do modelo, mas sim por fornecer contexto errado ou não ter como julgar se a saída está correta ou reverter.
Cinco camadas para focar:
Analisar essas camadas facilita a solução de problemas. Resultados instáveis? Verifique a ordem de carregamento do contexto. Automação descontrolada? Verifique a camada de controle. Qualidade em declínio em sessões longas? Produtos intermediários poluíram o contexto; iniciar uma nova sessão é melhor que ajustar prompts.
2. Limites Conceituais: MCP / Plugin / Ferramentas / Skills / Hooks / Subagentes
Regra simples: Use Ferramentas/MCP para novas ações, Skills para fluxos de trabalho, Subagentes para ambientes isolados, Hooks para restrições/auditoria obrigatórias e Plugins para distribuição entre projetos.
3. Engenharia de Contexto: A Restrição Mais Importante do Sistema
Muitos tratam contexto como "problema de capacidade", mas o gargalo geralmente é ruído. Informações úteis se perdem em conteúdo irrelevante.
Composição Real de Custo de Contexto
O contexto de 200K do Claude Code não está totalmente disponível:
1200K Total de Contexto2├── Carga Fixa (~15-20K)3│ ├── Instruções do sistema: ~2K4│ ├── Descritores de Skill: ~1-5K5│ ├── Definições de ferramentas MCP Server: ~10-20K ← Maior vilão oculto6│ └── Estado LSP: ~2-5K7│8├── Semifixa (~5-10K)9│ ├── CLAUDE.md: ~2-5K10│ └── Memória: ~1-2K11│12└── Dinâmica Disponível (~160-180K)13 ├── Histórico do chat14 ├── Conteúdo de arquivos15 └── Resultados de ferramentas
Um MCP Server típico (como GitHub) contém 20-30 definições de ferramentas, cada uma ~200 tokens, totalizando 4.000 a 6.000 tokens. Conectar 5 servidores consome 25.000 tokens (12,5%). Isso é crítico ao ler grandes quantidades de código.
Camadação Recomendada de Contexto
1Sempre Residente → CLAUDE.md: Contrato do projeto / comandos de build / proibições2Baseada em Caminho → rules: Regras específicas de idioma / diretório / tipo de arquivo3Sob Demanda → Skills: Fluxos de trabalho / conhecimento de domínio4Isolado → Subagentes: Exploração em larga escala / pesquisa paralela5Fora do Contexto → Hooks: Scripts determinísticos / auditoria / bloqueio
Não carregue coisas que você usa apenas ocasionalmente.
Melhores Práticas de Contexto
- Mantenha o CLAUDE.md curto, direto e executável. O da própria Anthropic tem ~2.5K tokens.
- Mova documentos de referência grandes para arquivos de suporte das Skills.
- Use .claude/rules/ para regras de caminho/idioma.
- Use /context para monitorar consumo.
- Use /clear para trocar de tarefas e /compact para novas fases.
- Escreva Instruções Compactas no CLAUDE.md para controlar o que é preservado.
Ruído de Saída de Ferramentas: Outro Vilão Oculto
Saídas dinâmicas de ferramentas (como cargo test ou git log) podem facilmente preencher o contexto. Claude não precisa ver tudo.
RTK (Rust Token Killer) é uma boa abordagem: filtra a saída de comandos antes de chegar ao Claude. Por exemplo, pode condensar milhares de linhas de saída de teste em uma única mensagem de sucesso.
Armadilhas de Compressão
A compressão padrão pode excluir decisões de arquitetura e restrições.
Solução: Especifique Instruções Compactas no CLAUDE.md para priorizar decisões de arquitetura, arquivos modificados, status de verificação e TODOs.
Outra solução proativa: Peça ao Claude para escrever um HANDOFF.md antes de iniciar uma nova sessão, explicando progresso e becos sem saída.
Valor de Engenharia do Modo Plano
O Modo Plano separa exploração da execução.
Para refatorações complexas, isso é melhor que correr para o código. Dica avançada: Use um Claude para escrever o plano e outro como "Engenheiro Sênior" para revisá-lo.
4. Design de Skills: Fluxos de Trabalho Carregados Sob Demanda
Skills são conhecimento e fluxos de trabalho sob demanda.
O que faz uma boa Skill
- A descrição deve dizer "quando me usar", não "o que faço".
- Tenha etapas completas, entradas, saídas e condições de parada.
- Mantenha o corpo principal para navegação e restrições centrais; mova detalhes para arquivos de suporte.
- Defina disable-model-invocation: true para skills com efeitos colaterais.
Divulgação Progressiva
O Claude Code enfatiza "divulgação progressiva": primeiro forneça índices e navegação, então busque detalhes conforme necessário.
Três Tipos Típicos de Skill
- Checklist (Portão de Qualidade): ex., release-check.
- Fluxo de Trabalho (Operações Padronizadas): ex., config-migration com rollback.
- Especialista de Domínio (Framework de Decisão): ex., runtime-diagnosis.
Mantenha descritores curtos para economizar espaço de contexto.
5. Design de Ferramentas: Ajudando Claude a Escolher Corretamente
Ferramentas para agentes devem focar em facilidade de uso correto, não em completude de funcionalidades.
Ferramentas Boas vs. Ruins
Princípios de design: Use prefixos (github_pr_*), suporte formatos concisos, forneça mensagens de erro úteis e evite expor muitas ferramentas fragmentadas.
Evolução das Ferramentas Internas
A evolução da ferramenta "AskUserQuestion" mostra que uma ferramenta dedicada é mais estável que formatação markdown ou parâmetros de saída.
Ferramentas de Todo se tornaram uma "amarra" conforme os modelos ficaram mais fortes. Ferramentas de busca evoluíram de RAG para Grep para melhor flexibilidade e "divulgação progressiva."
6. Hooks: Lógica Obrigatória Antes/Depois de Operações
Hooks recuperam controle determinístico sobre processos como formatação, proteção de arquivos e notificações.
Adequados para Hooks
Bloquear arquivos protegidos, formatar automaticamente após edições, injetar contexto dinâmico (branch Git) e notificações.
Detecção Precoce de Erros
Instâncias Independentes de Claude
Subagentes fornecem isolamento. Tarefas como escanear repositórios ou executar testes produzem saídas massivas que não devem poluir a thread principal.
Restrições Explícitas
Limite ferramentas, escolha o modelo certo (Haiku para exploração, Opus para revisão) e defina maxTurns.
Cache de Prompt: O Núcleo da Arquitetura do Claude Code
O Claude Code é construído em torno do Cache de Prompt. Altas taxas de acerto economizam dinheiro e aumentam limites de taxa.
Layout de Prompt para Cache
A ordem importa para correspondência de prefixo: Prompt do Sistema → Definições de Ferramentas → Histórico do Chat → Entrada do Usuário.
Não Troque de Modelo no Meio da Sessão
Trocar de modelo quebra o cache. Use Subagentes para transferências.
Implementação de Compressão
A compressão usa um fork para resumir o histórico a 1/10 do custo devido aos acertos de cache.
Loops de Verificação: Sem Verificador, Sem Agente de Engenharia
"Claude diz que está pronto" é inútil sem verificação. Defina verificação explicitamente no Prompt, Skill e CLAUDE.md.
Comandos de Alta Frequência
Comandos como /context, /clear, /compact e /memory ajudam a gerenciar o contexto ativamente.
Governança e Paralelismo
<payload-block><payload-block id="blk_18" type="upload" />
Comandos ocultos úteis: /simplify (revisão de código), /rewind (checkpointing), /btw (perguntas paralelas), /insight (analisar sessão para atualizações do CLAUDE.md).
Como Escrever um Bom CLAUDE.md
É um contrato, não uma base de conhecimento.
<nsagem>Inclua comandos de build/teste, limites de arquitetura, convenções de código, barreiras de segurança e Instruções Compactas. Peça ao Claude para atualizar o CLAUDE.md após corrigir seus erros.
Experiências Recentes
Lições da construção do Kaku (Rust + Lua): transparência do ambiente é vital (use um comando 'doctor'), e Hooks são ótimos para projetos multilíngües.
Anti-padrões
Verificação de Saúde
Use npx skills add tw93/claude-health para verificar sua configuração.
Conclusão
O foco muda de "como usar recursos" para "como deixar o agente rodar sob restrições". Se você não consegue definir "pronto", a tarefa não está pronta para um agente.
