0. TL;DR
Este artigo é fruto de seis meses de uso intensivo do Claude Code e das lições aprendidas ao gastar $40/mês em duas contas. Espero fornecer uma contribuição valiosa para todos.
Inicialmente, usei como ChatBot, mas logo percebi que as coisas estavam dando errado: o contexto ficava confuso, as ferramentas aumentavam mas a eficácia diminuía, e as regras eram ignoradas apesar de serem mais longas. Depois de pesquisar o próprio 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 verdadeiramente útil.
A maneira mais direta de entender é dividir o Claude Code em seis camadas:
Fortalecer apenas uma camada causa desequilíbrio. Se o CLAUDE.md for muito longo, polui o contexto; muitas ferramentas causam confusão; muitos subagentes levam à deriva de estado; pular a verificação impossibilita encontrar onde as coisas falharam.
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 os gargalos raramente são devidos ao modelo não ser inteligente o suficiente, mas sim por fornecer o contexto errado ou não ter como julgar se a saída está correta ou reverter.
Cinco camadas para focar:
Olhar para essas camadas facilita a resolução de problemas. Resultados instáveis? Verifique a ordem de carregamento do contexto. Automação fora de controle? Verifique a camada de controle. Qualidade decaindo em sessões longas? Produtos intermediários poluíram o contexto; iniciar uma nova sessão é melhor do 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 o contexto como uma "questão de capacidade", mas o gargalo geralmente é o ruído. Informações úteis são enterradas em conteúdo irrelevante.
Composição Real do Custo do Contexto
O contexto de 200K do Claude Code não está totalmente disponível:
1200K Contexto Total2├── Sobrecarga Fixa (~15-20K)3│ ├── Instruções do sistema: ~2K4│ ├── Descritores de Skill: ~1-5K5│ ├── Definições de ferramentas do servidor MCP: ~10-20K ← O maior vilão oculto6│ └── Estado LSP: ~2-5K7│8├── Semifixo (~5-10K)9│ ├── CLAUDE.md: ~2-5K10│ └── Memória: ~1-2K11│12└── Dinâmico Disponível (~160-180K)13 ├── Histórico do chat14 ├── Conteúdo de arquivos15 └── Resultados de ferramentas
Um servidor MCP típico (como GitHub) contém 20-30 definições de ferramentas, cada uma com ~200 tokens, totalizando 4.000-6.000 tokens. Conectar 5 servidores consome 25.000 tokens (12,5%). Isso é crítico ao ler grandes quantidades de código.
Camadas de Contexto Recomendadas
1S="text">2Sempre Residente → CLAUDE.md: Contrato do projeto / comandos de build / proibições3Baseado em Caminho → rules: Regras específicas de idioma / diretório / tipo de arquivo4Sob Demanda → Skills: Fluxos de trabalho / conhecimento de domínio5Isolado → Subagentes: Exploração em larga escala / pesquisa paralela6Fora 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 o consumo.
- Use /clear para trocar de tarefa 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
A saída dinâmica de ferramentas (como cargo test ou git log) pode facilmente preencher o contexto. O Claude não precisa ver tudo.
RTK (Rust Token Killer) é uma boa abordagem: ele filtra a saída do comando 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 para explicar o progresso e becos sem saída.
Valor de Engenharia do Modo Plano
O Modo Plano separa a exploração da execução.
Para refatorações complexas, isso é melhor do que sair programando. 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 eu faço".
- Tenha etapas completas, entradas, saídas e condições de parada.
- Mantenha o corpo principal para navegação e restrições principais; mova detalhes para arquivos de suporte.
- Defina disable-model-invocation: true para skills com efeitos colaterais.
Divulgação Progressiva
O Claude Code enfatiza a "divulgação progressiva": primeiro forneça índices e navegação, depois 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 (Estrutura de Decisão): ex.: runtime-diagnosis.
Mantenha os descritores curtos para economizar espaço no contexto.
5. Design de Ferramentas: Ajudando o Claude a Escolher Corretamente
Ferramentas para agentes devem focar na facilidade de uso correto, não na 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 do 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óris Antes/Depois das Operações
Hooks recuperam o controle determinístico sobre processos como formatação, proteção de arquivos e notificações.
Adequados para Hooks
Bloqueio de arquivos protegidos, autoformatação após edições, injeção de contexto dinâmico (branch Git) e notificações.
Detecção Precoce de Erros
7. Subagentes: Instâncias Independentes do Claude
Subagentes fornecem isolamento. Tarefas como escanear repositórios ou executar testes produzem saídas massivas que não devem poluir o thread principal.
Restrições Explícitas
Limite ferramentas, escolha o modelo certo (Haiku para exploração, Opus para revisão) e defina maxTurns.
8. Prompt Caching: O Núcleo da Arquitetura do Claude Code
O Claude Code é construído em torno do Prompt Caching. Altas taxas de acerto economizam dinheiro e aumentam os limites de taxa.
Layout do 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 Modelos no Meio da Sessão
Trocar de modelos quebra o cache. Use Subagentes para transferências.
Implementação da Compactação
A compactação usa um fork para resumir o histórico a 1/10 do custo devido a acertos de cache.
9. Loops de Verificação: Sem Verificador, Sem Agente de Engenharia
"Claude diz que está pronto" é inútil sem verificação. Defina a verificação explicitamente no Prompt, Skill e CLAUDE.md.
10. Comandos de Alta Frequência
Comandos como /context, /clear, /compact e /memory ajudam a gerenciar o contexto ativamente.
Governança e Paralelismo
Comandos ocultos úteis: /simplify (revisão de código), /rewind (checkpointing), /btw (perguntas paralelas), /insight (analisar sessão para atualizações do CLAUDE.md).
11. Como Escrever um Bom CLAUDE.md
É um contrato, não uma base de conhecimento.
Inclua comandos de build/teste, limites da arquitetura, convenções de código, barreiras de segurança e Instruções Compactas. Peça ao Claude para atualizar o CLAUDE.md depois de corrigir seus erros.
12. Experiências Recentes
Lições da construção do Kaku (Rust + Lua): a transparência do ambiente é vital (use um comando 'doctor'), e Hooks são ótimos para projetos multilíngues.
13. Antipadrões
14. Verificação de Saúde
Use npx skills add tw93/claude-health para verificar sua configuração.
15. Conclusão
O foco muda de "como usar recursos" para "como deixar o agente operar sob restrições". Se você não consegue definir "pronto", a tarefa não está pronta para um agente.
