O CLAUDE.md de Karpathy alcançou o 1º lugar no GitHub com 82.000 estrelas porque a maioria dos desenvolvedores usa o Claude Code de forma errada.

Um único arquivo de texto acabou de mudar para sempre a forma como os desenvolvedores usam IA para codar.

Não é um novo modelo.

Não é um IDE caro.

Não é outra startup de "agente de IA".

Apenas um arquivo:

CLAUDE.md

E ele se tornou silenciosamente uma das configurações de desenvolvedor que mais cresce no GitHub.

Mais de 82.000 estrelas.

Milhares de forks.

Engenheiros, de startups a equipes empresariais, copiando-o para seus projetos da noite para o dia.

Porque os desenvolvedores finalmente perceberam algo:

O Claude Code não falha porque o modelo é fraco.

Ele falha porque toda sessão começa com amnésia.

Toda vez que você abre o Claude Code, ele esquece:

• sua stack

• suas decisões de arquitetura

• suas convenções de nomenclatura

• seus padrões de codificação

• o que já falhou na semana passada

• o que NUNCA deve ser alterado

• por que você escolheu um framework em vez de outro

• quais arquivos são arriscados demais para mexer

Então o modelo faz o que toda IA faz sem contexto:

Ele chuta.

E esses chutes se tornam incrivelmente caros.

Você pede para corrigir uma função.

Ele reescreve três arquivos.

Renomeia variáveis que você escolheu intencionalmente.

Refatora código que funciona.

Sugere ferramentas incompatíveis com sua arquitetura.

Exclui coisas "para limpeza".

Altera formatação que ninguém pediu para tocar.

Então você passa a próxima hora desfazendo a "ajuda".

Esse é o imposto oculto da codificação com IA que ninguém menciona.

Um gerente de engenharia estimou que sua equipe estava perdendo quase 8 horas por semana apenas com:

→ reexplicar o contexto do projeto

→ reverter alterações não autorizadas

→ corrigir suposições erradas

→ reensinar decisões de arquitetura

→ conter o aumento não autorizado de escopo

Isso não é um problema de IA.

É um problema de memória.

E o CLAUDE.md resolve isso da maneira mais simples possível.

É apenas um arquivo de texto simples colocado na raiz do seu projeto.

Mas o Claude o lê automaticamente no início de cada sessão.

Ou seja, sua IA finalmente começa com contexto em vez de caos.

A diferença é imensa.

Sem CLAUDE.md:

"Assistente de IA"

Com CLAUDE.md:

"Engenheiro que já conhece seu projeto."

O arquivo geralmente contém 3 camadas.

━━━━━━━━━━━━━━━

1. REGRAS PADRÃO

━━━━━━━━━━━━━━━

Esta seção ensina ao Claude como você trabalha.

Quão detalhadas as respostas devem ser.

Qual é a sua stack.

Como você se comunica.

Quanto contexto você já sabe.

Qual estilo de escrita usar.

O que NÃO fazer.

Coisas como:

→ não use frases de preenchimento

→ mantenha as respostas proporcionais à complexidade da tarefa

→ pergunte antes de fazer suposições

→ nunca explique demais conceitos básicos

→ corresponda exatamente ao meu estilo de codificação

→ siga as restrições do projeto automaticamente

Parece pequeno.

Mas ao longo de centenas de prompts?

Isso elimina uma repetição massiva.

A maioria dos desenvolvedores gasta, sem saber, 20 a 40 minutos todos os dias reensinando contexto à IA.

Toda. Única. Sessão.

Agora multiplique isso por uma equipe de engenharia.

São milhares de dólares por mês desperdiçados apenas se repetindo.

━━━━━━━━━━━━━━━

1. CONTROLE DE COMPORTAMENTO

━━━━━━━━━━━━━━━

Esta é a seção que os desenvolvedores desejam ter tido meses atrás.

Porque é aqui que você impede o Claude de se tornar "criativamente destrutivo".

Você define limites rígidos como:

→ toque apenas em arquivos diretamente relacionados à tarefa

→ nunca refatore código não relacionado

→ pergunte antes de excluir qualquer coisa

→ confirme antes de ações destrutivas

→ não reescreva a estrutura existente sem aprovação

→ sempre mostre exatamente o que mudou

→ nunca faça deploy ou execute migrações automaticamente

Esta única seção evita a maioria das histórias de terror com codificação em IA.

Chega de reescritas surpresa.

Chega de desvio de arquitetura.

Chega de desastres do tipo "limpei isso para você".

A IA se torna previsível.

Que é exatamente o que os engenheiros realmente querem.

━━━━━━━━━━━━━━━

1. MEMÓRIA + CÉREBRO DO PROJETO

━━━━━━━━━━━━━━━

É aqui que as coisas ficam genuinamente poderosas.

Os desenvolvedores começaram a emparelhar o CLAUDE.md com arquivos como:

MEMORY.md

ERRORS.md

Agora o Claude pode lembrar:

• decisões que sua equipe já tomou

• abordagens que falharam

• ferramentas rejeitadas

• incidentes de produção

• restrições técnicas

• tradeoffs de arquitetura

• regras específicas do cliente

Ou seja, a IA para de recomendar coisas que você já descartou há meses.

Ela para de esquecer.

Isso muda tudo.

Porque o verdadeiro gargalo na codificação com IA não é mais a geração de código.

É o contexto persistente.

E a maioria das pessoas ainda não percebeu isso.

━━━━━━━━━━━━━━━

AS 4 REGRAS QUE FIZERAM ISSO VIRAL

━━━━━━━━━━━━━━━

A configuração explodiu depois que os desenvolvedores começaram a compartilhar 4 regras simples inspiradas na abordagem de Andrej Karpathy para trabalhar com sistemas de IA.

Elas parecem enganosamente básicas:

1. Pergunte antes de supor.
2. Use a solução mais simples primeiro.
3. Não toque em código não relacionado.
4. Sinalize incerteza imediatamente.

É só isso.

Mas essas 4 regras resolvem a maioria das falhas de codificação com IA.

Porque o maior dano geralmente vem da IA agindo com confiança sem contexto suficiente.

Os desenvolvedores que obtêm os melhores resultados não estão usando "mais IA".

Eles estão reduzindo a ambiguidade.

E depois que você vê isso, não consegue mais desver.

━━━━━━━━━━━━━━━

A VERDADEIRA DIVISÃO NA CODIFICAÇÃO COM IA

━━━━━━━━━━━━━━━

Agora existem basicamente dois tipos de desenvolvedores usando o Claude Code.

Grupo 1:

Começa cada sessão do zero.

Repete o contexto diariamente.

Limpa alterações indesejadas.

Luta constantemente contra o aumento de escopo.

Trata a IA como um autocomplete temporário.

Grupo 2:

Usa instruções persistentes.

Bloqueia regras de comportamento.

Mantém a memória do projeto.

Controla o escopo rigidamente.

Trata a IA como um colaborador de engenharia de longo prazo.

Mesmo modelo.

Resultados completamente diferentes.

É por isso que este arquivo se espalhou tão rápido.

Porque depois que o Claude tem:

• regras

• memória

• consciência da stack

• restrições comportamentais

• contexto do projeto

…ele para de parecer um chatbot.

E começa a parecer infraestrutura.

━━━━━━━━━━━━━━━

COMEÇE AQUI

━━━━━━━━━━━━━━━

Abra seu projeto.

Crie um arquivo chamado:

CLAUDE.md

Em seguida, cole estas 4 regras primeiro:

• Pergunte antes de supor

• Solução mais simples primeiro

• Não toque em código não relacionado

• Sinalize incerteza explicitamente

Só isso já vai melhorar como o Claude se comporta imediatamente.

Depois, expanda-o lentamente ao longo do tempo:

→ sua stack

→ padrões de codificação

→ regras de arquitetura

→ ações proibidas

→ registros de decisões

→ memória do projeto

A maioria dos desenvolvedores ainda não fez isso.

O que significa que a lacuna entre a codificação média assistida por IA e a codificação de elite assistida por IA está se tornando menos sobre modelos…

…e mais sobre quem sabe estruturar o contexto adequadamente.

Salve isto.

Porque daqui a seis meses, a memória persistente de projetos de IA provavelmente será tão normal quanto os repositórios do GitHub são hoje.