🍔 O problema: CLAUDE.md inchado
Novo aqui? Você já viu na Trilha 0 que o CLAUDE.md é o "cérebro" que o agente lê no início de cada sessão. O problema: se você começar a colar ali dentro instruções detalhadas de cada ferramenta MCP que instalar, ele vira um arquivo gigante — e arquivo gigante custa mais (é lido inteiro toda hora) e fica difícil de manter.
Novo aqui? Quando dizemos que um arquivo grande "custa mais", é literal: todo agente de código lê o CLAUDE.md inteiro no início de cada conversa, e esse texto vira parte do que chamamos de contexto — a "memória de curto prazo" que o modelo carrega enquanto trabalha com você. Contexto maior significa duas coisas ruins: você paga por mais texto processado a cada mensagem, e o agente tem mais chance de "perder o fio" entre uma regra e outra, porque está competindo por atenção com o resto da conversa.
O padrão comum é previsível: você instala um servidor MCP, cola no CLAUDE.md um parágrafo explicando quando usar cada uma das suas ferramentas. Semana seguinte, instala outro servidor, cola mais um parágrafo. Depois de 4 ou 5 servidores instalados, o arquivo que devia caber numa tela virou um documento de rolagem infinita — e a maior parte dele é lida em toda mensagem, mesmo quando o assunto daquela conversa não tem nada a ver com scraping, banco de dados ou e-mail.
Legenda: quanto mais servidores MCP você instala sem separar as instruções em arquivos à parte, mais o CLAUDE.md incha — até virar um arquivo caro de ler e difícil de manter.
💡 Dica Prática
Antes de colar qualquer explicação de ferramenta nova no CLAUDE.md, pergunte-se: "isso é uma regra geral do projeto, ou é detalhe de UMA ferramenta específica?". Se for detalhe de uma ferramenta, ele pertence a um cheat sheet, não ao CLAUDE.md — é exatamente o que o próximo tópico resolve.
✗ CLAUDE.md inchado
- • 5 servidores MCP, cada um com um parágrafo colado
- • Toda mensagem lê regras que não têm nada a ver com o assunto
- • Achar uma regra específica vira busca em texto corrido
✓ CLAUDE.md enxuto
- • Só regras gerais do projeto, cabe numa tela
- • Cada servidor MCP tem seu próprio cheat sheet
- • O agente só abre o cheat sheet quando o assunto aparece
📋 A solução: um arquivo cheat sheet à parte
Legenda: o CLAUDE.md fica curto e só aponta pro cheat sheet; é o cheat sheet que traz, com exemplos, qual ferramenta escolher em cada situação — assim o agente acerta sem você repetir a explicação toda vez.
Novo aqui? Cheat sheet — em
português, "cola de prova" — é um arquivo markdown à parte, dedicado só a ensinar o agente a escolher a
ferramenta certa dentro de um domínio (por exemplo, scraping). O CLAUDE.md fica com uma linha só: "para
dúvidas sobre scraping, ver cheat-sheet.md". O agente só abre esse arquivo quando o assunto
aparece — mantendo tudo enxuto no dia a dia.
🔍 Ver por dentro: por que isso funciona
Nada de mágico acontece — é só uma questão de leitura sob demanda. O CLAUDE.md carrega em toda mensagem; o cheat sheet só é aberto quando o agente decide que precisa dele, geralmente quando você pede algo relacionado (por exemplo "baixa essa página"). Nas conversas onde você não toca em scraping, o cheat sheet fica parado no disco, sem custar nada de contexto. É o mesmo princípio de carregamento sob demanda que a Trilha 3 vai chamar de carregamento progressivo — carregar o essencial primeiro, os detalhes só quando o assunto aparece.
Isso também significa que o cheat sheet pode crescer bastante sem problema — ele só "custa" quando é lido, e é lido raramente, sempre no momento certo.
🧱 Anatomia de um bom cheat sheet
Um cheat sheet eficiente tem três partes: uma tabela comparando as opções, uma regra de decisão em uma frase ("se X, use Y") e exemplos reais de pedido → ferramenta escolhida. Nada de parágrafos longos — o objetivo é consulta rápida, não leitura corrida.
Tabela comparativa
As opções lado a lado — quando usar cada uma, em uma frase por linha.
Regra de decisão
Uma frase curta tipo "se o pedido menciona 1 página só, use scrape; se menciona 'todo o site', use crawl".
Exemplos reais
2-3 pares "pedido do usuário → ferramenta escolhida", pra fixar o padrão.
A diferença entre um cheat sheet que funciona e um que só existe no papel está nos detalhes de redação. Compare os dois exemplos abaixo, para o mesmo servidor de scraping:
✗ Cheat sheet fraco
- ✗"Use a ferramenta certa para cada tipo de scraping" — vago, não diz qual é qual
- ✗Parágrafo de 8 linhas explicando a filosofia por trás de cada ferramenta
- ✗Nenhum exemplo de pedido real do usuário
✓ Cheat sheet forte
- ✓"1 página → scrape · lista de páginas → map · site inteiro → crawl"
- ✓Tabela de 3 linhas, cada uma com a ferramenta e quando usar
- ✓"quero o texto dessa página" → scrape (exemplo real)
✍️ Escrevendo seu primeiro cheat sheet
Você pode pedir pro próprio agente escrever o rascunho do cheat sheet, revisando depois. Comece pedindo pra ele documentar as ferramentas de um servidor MCP que você acabou de instalar, no formato de tabela + regra de decisão.
Objetivo: ter um cheat sheet real no seu projeto. Como verificar: o arquivo cheat-sheet.md aparece na pasta com uma tabela e o CLAUDE.md ganha uma linha nova apontando pra ele.
⚠️ Erros comuns ao pedir o cheat sheet
- O agente inventa ferramentas que não existem: se ele nunca
"conversou" com o servidor MCP antes (nunca chamou nenhuma ferramenta), pode chutar nomes. Peça pra ele
listar as ferramentas disponíveis primeiro — geralmente com um comando tipo
/mcp— antes de documentar. - Cheat sheet vira cópia da documentação oficial: colar a documentação inteira do servidor não ajuda — ela já é longa demais pra "consulta rápida". Peça explicitamente pelo formato tabela + regra de decisão + exemplos, não um resumo genérico.
- CLAUDE.md não é atualizado: às vezes o agente cria o cheat sheet mas esquece de adicionar a linha de referência no CLAUDE.md. Confira os dois arquivos, não só o novo.
🔗 CLAUDE.md aponta, não repete
A regra de ouro: o CLAUDE.md aponta pros arquivos de referência, nunca os repete. Isso vale pra cheat sheets de MCP e vai valer pra skills na Trilha 3 — é o mesmo princípio de carregamento progressivo: só carrega o detalhe quando o assunto realmente aparece.
🔍 Por dentro
É o mesmo motivo por trás de pastas organizadas em vez de um único arquivo gigante — informação fica disponível, mas só custa "espaço" quando é lida de verdade.
Legenda: o CLAUDE.md fica pequeno e no centro, apontando para arquivos separados por assunto — cada um só é lido quando o assunto correspondente aparece na conversa.
✗ Repete
- • Cola a lista de ferramentas MCP inteira dentro do CLAUDE.md
- • Toda mensagem lê o conteúdo completo, use ou não use
- • Atualizar significa editar um arquivo gigante
✓ Aponta
- • Uma linha só: "para MCP, ver cheat-sheet.md"
- • Conteúdo detalhado só é lido quando o assunto aparece
- • Atualizar é editar o arquivo pequeno e específico
🔄 Mantendo o cheat sheet vivo
Toda vez que você instalar um servidor MCP novo, ou perceber que o agente escolheu a ferramenta errada mais de uma vez, é sinal de atualizar o cheat sheet — acrescentar uma linha na tabela ou deixar a regra de decisão mais clara. É um documento vivo, não um arquivo que se escreve uma vez e esquece.
Pense no cheat sheet como uma planta que precisa de água de vez em quando, não como um monumento que se constrói uma vez e fica pronto pra sempre. Os três gatilhos mais comuns pra revisar são: instalar um servidor MCP novo, perceber uma escolha de ferramenta errada repetida, e o próprio servidor mudar (ferramentas renomeadas, novos parâmetros).
Servidor MCP novo instalado
Peça pro agente documentar as ferramentas dele num cheat sheet novo, ou numa seção nova de um existente.
Escolha errada, mais de uma vez
Se você já corrigiu "não, use X" duas vezes pro mesmo tipo de pedido, a regra de decisão do cheat sheet está fraca — reescreva-a mais explícita.
O servidor mudou
Ferramenta renomeada ou parâmetro novo quebra o exemplo antigo — vale revisar o cheat sheet depois de atualizar qualquer servidor MCP.
💡 Dica Prática
Sempre que corrigir o agente na conversa ("não, use crawl aqui, não scrape"), peça pra ele mesmo já atualizar o cheat sheet com esse aprendizado.
✗ Deixando morrer
- • Cheat sheet escrito uma vez, nunca mais aberto
- • Ferramentas novas do servidor não aparecem nele
- • Agente continua errando a mesma escolha há semanas
✓ Mantendo vivo
- • Revisado a cada servidor novo ou erro repetido
- • O próprio agente já sugere a atualização quando corrigido
- • Regra de decisão fica mais clara a cada rodada