Se você usa o Claude Code todo dia e ainda reconstrói o contexto do zero toda sessão — reexplica o projeto, repete as regras, reensina o que o agente pode e não pode fazer — o problema não é você. É que nunca te contaram que existe uma camada de método dentro do Claude Code que resolve exatamente isso. E esse silêncio não é acidental.
Falta de método, não de ferramenta. Você já tem o Claude Code. O que você não tem é a estrutura que faz ele trabalhar para o seu sistema, não para o sistema de outra pessoa.
O sinal que 14.000 desenvolvedores enviaram ao mesmo tempo
Tem um repositório no GitHub que merece sua atenção. Um desenvolvedor pegou tweets do Andrej Karpathy — um dos pesquisadores de IA mais respeitados do mundo — sobre como usar modelos de linguagem, comprimiu tudo em um único arquivo markdown e chamou de CLAUDE.md. Resultado: quase 14.000 estrelas.
Um arquivo markdown. Com tweets. 14.000 pessoas marcaram como favorito.
Se você leu isso e pensou “interessante” e seguiu em frente, você perdeu o sinal. Esse número não é sobre o Karpathy. É sobre o tamanho da demanda por método estruturado que a comunidade de desenvolvedores e praticantes de IA está sentindo — e não está encontrando em nenhum lugar oficial.
As Big Techs lançam ferramenta em cima de ferramenta em ritmo impossível de acompanhar. Lançaram o Claude Code com uma documentação que ensina o básico e deixam o resto para você descobrir. E enquanto você reconstrói contexto do zero toda sessão, eles lançam mais uma versão, mais um modelo, mais um recurso. O ciclo de dependência continua. Quanto mais confuso você está, menos você questiona a ferramenta.
O que é CLAUDE.md (e por que a maioria dos praticantes ignora)
CLAUDE.md é um arquivo de texto simples que o Claude Code lê automaticamente no início de cada sessão. Você cria ele na raiz do seu projeto — ou na pasta global ~/.claude/ para preferências pessoais — e ele se torna a memória persistente do seu agente.
Pense assim: LLMs são stateless por design. Não guardam nada entre sessões. Toda vez que você abre uma nova conversa, é como se o Claude acabasse de chegar no emprego e não soubesse nada. O CLAUDE.md é o briefing que você dá a ele antes de começar a trabalhar — e você só precisa escrever uma vez.
O que colocar no CLAUDE.md:
- O que é o projeto: stack, estrutura de pastas, componentes principais e suas funções
- Por que as decisões foram tomadas: trade-offs arquiteturais, escolhas não óbvias, contexto histórico
- Como operar: comandos de build, testes, fluxo de deploy, ferramentas obrigatórias
- O que nunca fazer: restrições críticas, arquivos que não podem ser modificados, padrões inegociáveis
O que não colocar:
- Guias de estilo que um linter faz mais rápido e mais barato
- Instruções que só se aplicam a uma tarefa específica (essas pertencem às Skills)
- Histórico de sessões ou decisões pontuais — isso é ruído, não sinal
Pesquisas sobre comportamento de LLMs mostram que modelos frontier lidam de forma confiável com 150-200 instruções. O Claude Code já começa com ~50 instruções no sistema. Cada linha desnecessária no seu CLAUDE.md compete com instruções que realmente importam. Menos de 200 linhas é regra, não sugestão.
O que são Skills (e como diferem de prompts)
Skills são arquivos de instrução especializados — SKILL.md — armazenados em .claude/skills/ do seu projeto ou em ~/.claude/skills/ para uso pessoal. A diferença crítica em relação a prompts comuns: elas não carregam no contexto automaticamente. Elas ficam indexadas, aguardando.
Quando você envia uma mensagem, o Claude compara o que você pediu com as descrições das skills disponíveis. Se há match semântico — “gerar blog post” corresponde à skill de blog, “revisar segurança” corresponde à skill de security review — a skill é carregada no contexto e suas instruções específicas entram em ação. Se não há match, a skill permanece indexada, sem consumir tokens.
Isso resolve um problema real que todo praticante acidental já sentiu: como manter instruções específicas sem sobrecarregar o contexto com regras que só se aplicam a 10% das tarefas?
| Dimensão | Skills | Prompts comuns |
|---|---|---|
| Carregamento | Sob demanda, por match semântico | Sempre ativo ou manual |
| Custo de contexto | Mínimo até ser acionada | Consumo constante |
| Escopo | Expertise por tarefa específica | Orientação geral |
| Reutilização | Versionada, commitada no repositório | Manual, frágil, esquece |
| Time | Todos que fazem pull recebem automaticamente | Cada pessoa recria do zero |
Uma skill bem escrita encapsula raciocínio especializado que levou semanas para desenvolver. Em vez de repetir o mesmo prompt toda vez — “revise este código considerando segurança, performance e compatibilidade com a versão X do framework” — você codifica esse raciocínio uma vez. O agente aplica consistentemente.
Como os dois funcionam juntos: a camada de método dentro do Claude Code
CLAUDE.md e Skills não competem — são camadas complementares com responsabilidades diferentes:
- CLAUDE.md = contexto universal — o que o agente precisa saber em todas as sessões, independente da tarefa
- Skills = conhecimento especializado — o que o agente precisa saber apenas quando uma categoria de tarefa é requisitada
Pense no CLAUDE.md como o onboarding de um novo colaborador: explicação da empresa, dos processos, das regras não escritas. E nas Skills como os SOPs — procedimentos operacionais padrão que ele consulta quando enfrenta um tipo específico de situação.
Vinicius, que tem rede comercial e quer monetizar IA sem saber por onde começar, poderia criar um repositório com um CLAUDE.md que explica o contexto do cliente, as restrições de entrega e os padrões de comunicação. E skills para cada tipo de deliverable: relatório executivo, análise competitiva, proposta comercial. Cada skill carrega o raciocínio especializado daquele entregável. Quando ele pede o relatório, a skill certa entra. O resto fica indexado.
Nicole, que quer entregar projetos com IA mas trava na execução técnica, poderia ter skills de revisão de código, skills de geração de testes, skills de documentação. Cada uma com as regras específicas do projeto, o nível de cobertura esperado, os padrões de formatação do cliente. O CLAUDE.md guarda o contexto do cliente. As skills guardam a expertise de entrega.
O que acontece quando você usa Claude Code sem essa camada
Você reconstrói. Todo dia. Toda sessão.
Reexplica o que o projeto faz. Repete as restrições. Lembra o agente dos padrões que você passou horas estabelecendo na sessão anterior. E o Claude, que é estateless por design, começa do zero como se fosse a primeira vez que vocês se encontram.
O custo não é só tempo — é a degradação de qualidade. Cada sessão começa com um agente sem contexto que vai tomar decisões baseadas nos padrões que ele aprendeu no treinamento, não nos padrões que você estabeleceu para o seu sistema. Você debugga erros que não deveriam acontecer. Você reverte decisões que já havia tomado. Você sente que “o Claude está te deixando maluco” quando o problema não é o Claude — é que a sessão está voando sem instrumentos.
A Big Tech que construiu a ferramenta não tem incentivo para você usar ela de forma autônoma. Quanto mais dependente do prompt manual, mais você está preso ao ciclo deles: nova versão, novo comportamento, novo onboarding, novo prompt. A camada de método — CLAUDE.md + Skills — quebra esse ciclo. E é por isso que esse conhecimento não aparece na primeira página da documentação.
Como começar hoje: 3 passos concretos
Não espere ter o sistema perfeito. Comece com o que você já sabe sobre o seu projeto.
Passo 1: Crie um CLAUDE.md com o que você repete
Abra o terminal no diretório do seu projeto e crie o arquivo:
touch .claude/CLAUDE.mdEscreva as três ou quatro coisas que você mais frequentemente precisa explicar pro Claude no início de uma sessão. O stack, a estrutura, a regra mais importante. Isso já é suficiente para começar. Refinamento vem com o uso.
Passo 2: Identifique uma tarefa que você repete
Qual é a tarefa que você mais executa no Claude Code? Revisão de código? Geração de documentação? Análise de dados? Essa é a candidata para sua primeira skill.
Crie .claude/skills/minha-primeira-skill/ e dentro um arquivo SKILL.md com o nome, a descrição (campo mais importante — determina quando a skill é carregada) e as instruções específicas para aquela tarefa.
Passo 3: Observe e itere
Na próxima sessão, abra o Claude Code no mesmo projeto. Observe o que ele já sabe sem você precisar explicar. Observe quando a skill é acionada automaticamente pelo match semântico. Adicione uma linha no CLAUDE.md quando perceber que reexplicou algo que não estava lá. A cada iteração, o sistema fica mais autônomo.
Quando você entende esse mecanismo, o Claude para de ser um chatbot que você precisa guiar linha por linha e começa a ser um agente que opera dentro do seu sistema. E quando vier a próxima versão, o próximo modelo, a próxima ferramenta — você já sabe como atravessar. O método é o mesmo. A ferramenta muda. Quem tem método não se perde.
Perguntas frequentes
Qual a diferença entre CLAUDE.md global e CLAUDE.md de projeto?
O CLAUDE.md global fica em ~/.claude/CLAUDE.md e se aplica a todos os projetos — é o lugar certo para preferências pessoais e padrões de trabalho universais. O CLAUDE.md de projeto fica em .claude/CLAUDE.md dentro do repositório e se aplica apenas àquele contexto. Se ambos existem, o Claude combina os dois. Use o global para o seu jeito de trabalhar; use o de projeto para o contexto específico daquele sistema.
Skills consomem contexto mesmo quando não são acionadas?
Não. Esse é o design central das Skills. O Claude indexa os nomes e descrições das skills disponíveis (custo mínimo de tokens) e só carrega o conteúdo completo quando há match semântico com o que você pediu. Skills não acionadas ficam indexadas, não no contexto ativo. É isso que permite ter dezenas de skills sem degradar a qualidade das respostas.
Skills de projeto são compartilhadas com o time automaticamente?
Sim. Skills commitadas em .claude/skills/ no repositório são distribuídas automaticamente para qualquer pessoa que fizer pull. Todo membro do time recebe o mesmo conjunto de capacidades sem precisar configurar nada individualmente. Isso é particularmente valioso para padronizar entregáveis e garantir que raciocínio especializado desenvolvido por um membro beneficie toda a equipe.
O que vai no CLAUDE.md versus o que vai numa Skill?
Regra prática: se é algo que o agente precisa saber em 100% das sessões, vai no CLAUDE.md. Se é algo que ele só precisa quando executa uma categoria específica de tarefa, vai em uma Skill. Contexto do projeto vai no CLAUDE.md. Procedimento de revisão de código vai em uma Skill. Stack tecnológico vai no CLAUDE.md. Regras de geração de relatório para o cliente X vão em uma Skill.
Posso usar CLAUDE.md e Skills com outros modelos além do Claude?
CLAUDE.md e Skills são funcionalidades nativas do Claude Code (Anthropic). Outros agentes e IDEs têm mecanismos análogos com nomes diferentes, mas a implementação específica e o comportamento de match semântico das Skills são do Claude Code. O conceito — separar contexto universal de expertise modular — é transferível para qualquer sistema. A implementação técnica aqui é específica do Claude Code.
