Toda vez que eu abria uma conversa nova com o Claude pra resolver algo do InovaShot, fazia a mesma coisa: parava, respirava, e começava digitando um parágrafo de contexto. "Minha empresa faz isso, o backend está montado assim, ontem eu tentei resolver de tal jeito e não deu certo." Recebia uma resposta boa, fechava a conversa, e no dia seguinte fazia tudo de novo. Como se fosse a primeira vez que a gente se falava.
Levei um tempo pra perceber que o problema não era o Claude. Era eu, recomeçando do zero toda santa vez.
A solução que encontrei não tem nada de sofisticado. É um arquivo de texto.
O arquivo que a Anthropic recomenda pra qualquer pessoa que usa Claude Code
Chama-se CLAUDE.md. É um arquivo markdown simples, que fica na raiz do projeto, e que o Claude lê automaticamente no início de cada sessão. A própria Anthropic documenta isso oficialmente: o arquivo existe pra guardar contexto persistente que o Claude não consegue simplesmente adivinhar lendo o código — comandos de terminal que você usa sempre, convenções de estilo que fogem do padrão, como rodar os testes, decisões de arquitetura que só fazem sentido se alguém contar a história por trás.
A parte que eu ignorei durante meses: a documentação oficial é enfática sobre manter esse arquivo curto. A regra que a Anthropic sugere é simples de aplicar — pra cada linha do seu CLAUDE.md, pergunte: "se eu tirar essa linha, o Claude vai errar por falta dela?" Se a resposta for não, corta.
Isso contraria a intuição de quem, como eu, começou tratando o arquivo como um diário técnico. Fui empilhando contexto até virar um documento gigante — e foi exatamente aí que as coisas pioraram, não melhoraram.
Quando o arquivo é grande demais, ele para de funcionar
Existe um sintoma bem específico disso: você escreve uma regra clara — "nunca faça X sem eu confirmar" — e mesmo assim o Claude faz X. A explicação mais provável não é que o modelo esteja ignorando você de propósito. É que o arquivo ficou tão longo que aquela regra específica se perdeu no meio do ruído.
Um relato que li recentemente descreve exatamente essa dor, só que em código: antes de qualquer disciplina de contexto, o Claude Code tomava liberdades sozinho — reescrevia testes que já funcionavam, adicionava abstrações que ninguém pediu, ignorava o padrão que o resto do projeto seguia havia meses. O autor cita um dado que me fez parar pra pensar: segundo um levantamento da GitClear, times gastam cerca de 2,74 vezes mais tempo revisando código gerado por inteligência artificial em busca de falhas de segurança do que revisando código escrito por um humano. Cada hora "economizada" deixando o modelo codar sozinho pode virar quase três horas de revisão depois. Isso não é ganho de produtividade — é dívida técnica com roupa nova.
Não é só o código que sai chutado. É a marca inteira.
Tem um relato parecido, só que do lado do design, que achei ainda mais impactante. Um designer de produto percebeu que o Claude Code entregava componentes que pareciam certos à primeira vista — cantos arredondados, espaçamento razoável — mas, ao abrir o inspetor do navegador, o azul do botão não era o azul da marca. Era o azul padrão do Tailwind, bem parecido, próximo o suficiente pra ninguém notar em review, longe o suficiente pra o time de marketing notar assim que a página foi ao ar.
E não parou num botão: cantos de modal errados, cinza que parecia vir do sistema de design de outra empresa, peso de fonte que já tinha sido eliminado da identidade visual há um ano voltando como se nunca tivesse saído. A conclusão do autor foi direta: o Claude não estava sendo descuidado. Estava chutando — porque ninguém tinha dado a ele nada confiável em que se basear. A solução foi transformar o design system em tokens: valores nomeados e centralizados que o Claude consulta como fonte da verdade, em vez de adivinhar a cor certa a partir do que parece familiar.
É o mesmo problema do CLAUDE.md, só que aplicado à marca em vez do código: sem uma fonte de verdade explícita, o modelo preenche a lacuna com o padrão mais comum que conhece — que raramente é o seu padrão.
O que aprendi tocando uma SaaS sozinha, pelo celular
Não tenho equipe técnica. Não tenho escritório, nem computador de mesa pra maior parte do trabalho. Construo e mantenho o InovaShot — que transforma vídeo longo em clipe pronto pra postar — inteiramente pelo celular, com SSH, GitHub e Claude como ferramentas.
Isso só é sustentável porque, hoje, meu CLAUDE.md segue o mesmo princípio que a Anthropic recomenda: regras de comportamento curtas e diretas no topo do arquivo — o que fazer, o que nunca fazer sem eu confirmar, como reportar progresso. O contexto mais profundo — histórico de decisões, bugs já resolvidos e por quê, arquitetura do servidor — mora em outro lugar, numa wiki dedicada que o Claude consulta quando a tarefa exige. Regra curta pra disciplina, documentação longa pra memória. Os dois papéis existem, mas não deveriam brigar por espaço no mesmo bloco de texto.
O passo seguinte: Skills
Depois que o CLAUDE.md resolve "quem eu sou e o que você nunca pode fazer sem perguntar", sobra outro problema: mesmo com o contexto certo, uma tarefa específica ainda pode sair genérica. Um relatório esqueleto. Um design que entrega de cara que foi feito no automático.
A própria documentação da Anthropic é clara sobre isso: conhecimento que só é relevante às vezes não deveria estar no CLAUDE.md, porque ele carrega esse arquivo em toda sessão — inclusive nas que não têm nada a ver com aquele assunto. O lugar certo pra isso são as Skills: pacotes de instruções especializados que o Claude carrega só quando aquele tipo específico de tarefa aparece. Hoje, no InovaShot, tenho Skills dedicadas a SEO, a revisão de tom de texto, a automação de design — cada uma treinada no jeito certo de fazer aquele trabalho, não no genérico.
Se o CLAUDE.md é a fundação, as Skills são as ferramentas especializadas que uso em cima dela.
Comece pequeno
Não é preciso nascer com duzentas linhas de regras — e, pelo visto até nas recomendações oficiais, provavelmente nem deveria. O primeiro CLAUDE.md pode ter cinco seções: o que o projeto faz, comandos que você usa sempre, o que já foi tentado e não funcionou, convenções que fogem do padrão, e o que nunca deve ser feito sem sua confirmação explícita.
Depois disso, resista ao impulso de fazer o arquivo crescer sem parar. A cada linha nova, pergunte se ela realmente evita um erro — ou se está ali só porque parecia importante escrever.
Foi assim que uma fundadora solo, sem time técnico, sem escritório, com só um celular na mão, conseguiu manter uma SaaS no ar. Não foi mágica. Foi um arquivo de texto pequeno o suficiente pra ser lembrado de verdade.