Karpathy CLAUDE.md Rules + 8 More: The 12-Rule Template Tested Across 30 Codebases

Final de janeiro de 2026: Andrej Karpathy posta uma thread no X reclamando de como o Claude escreve código. Três modos de falha — suposições erradas silenciosas, excesso de complicação, danos ortogonais ao código que não deveria ter sido tocado. Forrest Chang lê a thread, empacota as reclamações em 4 regras de comportamento em um único arquivo CLAUDE.md e o lança no GitHub. 5.828 estrelas no primeiro dia. 60.000 bookmarks em duas semanas. 120.000 estrelas até meados de 2026. O repositório de arquivo único com o crescimento mais rápido do ano. Em 9 de maio de 2026, um desenvolvedor verificado com o handle @mnilax (Mnimiy) postou um artigo longo no X com uma das afirmações de engenharia mais perspicazes do ano: eles testaram o template em 30 codebases por 6 semanas e depois adicionaram mais 8 regras para fechar as lacunas. 2,7 milhões de visualizações, 18.800 bookmarks. Este é o detalhamento completo — e o que isso significa se você estiver rodando o Claude dentro do Antigravity (ou qualquer outra IDE de agente) com um GEMINI.md ou AGENTS.md arquivo.

A publicação original de @mnilax no X que este artigo analisa — 2,7M visualizações, 18,8K favoritos, 9 de maio de 2026.

1. O Momento Viral

A thread original de Karpathy não era prescritiva. Era uma reclamação — do tipo que engenheiros seniores postam após uma tarde ruim. Três modos de falha específicos:

1. Suposições erradas silenciosas. O Claude infere o que você quis dizer, constrói sobre a inferência errada e nunca te avisa.
2. Excesso de complicação. O Claude busca abstrações, camadas, helpers genéricos. A correção de 4 linhas vira 40 linhas.
3. Dano ortogonal. O Claude "melhora" o código que não deveria ter tocado — espaços em branco, nomenclatura, formatação, funções adjacentes que não foram solicitadas.

Forrest Chang leu a thread e fez o trabalho que ninguém mais fez: ele escreveu o que Karpathy estava pedindo implicitamente. Quatro regras curtas e imperativas. Um arquivo. 65 linhas. Repositório público. O ritmo importa — Forrest não adicionou comentários, não transformou em um framework, não monetizou. Apenas as regras.

Isso tocou na ferida. Desenvolvedores que lutavam contra o Claude todos os dias de repente tiveram uma instalação de uma linha: cole este arquivo na raiz do seu repositório. As métricas contam a história — 120.000 estrelas em um arquivo sem nenhum código. A maioria desses desenvolvedores ainda está rodando apenas essas quatro regras hoje.

2. As 4 Regras Originais (Karpathy via Forrest Chang)

Aqui está a base — as regras em sua forma original. Se você não tem nenhum CLAUDE.md hoje, comece com estas:

Dados de Mnimiy: estas quatro fecham ~40% dos modos de falha em sessões não supervisionadas do Claude Code. Os ~60% restantes residem nas lacunas que o template original não aborda.

3. Por Que Foi Necessário Estender

O template foi escrito em janeiro de 2026. O ecossistema do Claude Code em maio de 2026 é uma realidade completamente diferente. O artigo destaca quatro realidades pós-janeiro que as 4 regras originais não cobrem:

• Conflitos entre agentes. Configurações multi-agente onde dois agentes editam os mesmos arquivos e se atropelam. As regras de Karpathy assumem um único loop de autocomplete. A real orquestração multi-agente precisa de regras de propriedade.
• Cascatas de hooks. Os hooks do Claude Code são disparados a cada chamada de ferramenta. Sem orçamentos, um hook prolixo transforma uma requisição de 200 tokens em 8.000 tokens.
• Conflitos de carregamento de habilidades. Múltiplas Skills com descrições sobrepostas confundem o dispatcher de correspondência de descrições. O template original não possui nada sobre como resolver ambiguidades.
• Workflows de múltiplas etapas. Um refactor de 6 etapas que falha na etapa 4 significa que as etapas 5 e 6 serão construídas sobre um estado corrompido. O template original trata cada iteração do Claude como um one-shot.

A tese de Mnimiy: as 4 originais são fundamentais, não erradas. Elas estão incompletas.

4. As 8 Novas Regras (Cada uma com o Momento que a Originou)

Cada uma delas surgiu de um incidente específico no estudo de 30 codebases. O artigo mostra o momento e, em seguida, a regra. Abaixo: mesma estrutura, condensada.

Regra 5 — Não faça o modelo realizar trabalho que não seja de linguagem

Decisões determinísticas pertencem a código determinístico. Políticas de retry, roteamento, limites de escalonamento — não chamadas de LLM. O modelo decide de forma diferente a cada semana.

O momento: Uma chamada de LLM para "decidir se deve fazer retry em um 503" funcionou por duas semanas, depois começou a falhar porque o modelo passou a ler o corpo da requisição como contexto para a decisão. A política de retry tornou-se aleatória porque o prompt era, efetivamente, aleatório.

Regra 6 — Budgets rígidos de tokens, sem exceções

Todo loop tem a chance de espiralar em um dump de contexto de 50.000 tokens. O modelo não vai parar por conta própria. Budgets oferecem um limite rígido.

O momento: Uma sessão de debugging de 90 minutos iterando sobre a mesma mensagem de erro de 8KB. Ao final, o Claude estava sugerindo correções que o usuário já havia rejeitado 40 mensagens antes. Um budget de tokens teria encerrado o loop no minuto 12.

Regra 7 — Exponha conflitos, não faça uma média deles

Quando duas partes da codebase divergem, o Claude tenta agradar a ambas. O resultado é um código incoerente que combina ambos os padrões e não funciona corretamente em nenhum deles.

O momento: Uma codebase tinha dois padrões de tratamento de erro — async/await com try/catch e um global error boundary. O Claude escreveu código que fazia ambos. Os erros foram silenciados duas vezes. 30 minutos para descobrir.

Regra 8 — Leia antes de escrever

As "Surgical Changes" de Karpathy dizem ao Claude para não tocar no código adjacente. Elas não dizem ao Claude para entender o código adjacente. Sem essa adição, o Claude escreve um novo código que conflita com o código existente a 30 linhas de distância.

O momento: Claude added a function next to an existing identical function it hadn't read. The new one won by import order. The original had been the source of truth for 6 months.

Regra 9 — Testes não são opcionais, mas não são o objetivo

A Goal-Driven Execution trata "testes passarem" como sucesso. Na prática, o Claude escreve código que passa em testes superficiais enquanto quebra o comportamento em produção.

O momento: 12 testes para uma função de auth, todos passando, auth quebrada em produção. Os testes verificavam se a função retornava algo, não se ela retornava a coisa certa. A função passou porque estava retornando uma constante.

Regra 10 — Operações de longa duração precisam de checkpoints

O template original assume interações one-shot. O trabalho real com Claude Code é multi-etapa — refactors em 20 arquivos, features ao longo de uma sessão, debugging entre commits. Sem checkpoints, um erro faz perder todo o progresso.

O momento: Um refactor de 6 etapas deu errado no passo 4. O Claude prosseguiu para os passos 5 e 6 sobre o estado quebrado. Desfazer a confusão demorou mais do que refazer todo o refactor.

Regra 11 — Convenção vence a novidade

Em uma codebase com padrões estabelecidos, o Claude gosta de introduzir os seus próprios. Mesmo quando o jeito dele é "melhor," introduzir um segundo padrão é pior do que qualquer um dos padrões isoladamente.

O momento: O Claude introduziu React hooks em uma codebase de class-components. Os hooks funcionaram. Eles também quebraram os padrões de teste da codebase, que assumiam componentDidMount. Meio dia para remover e reescrever.

Regra 12 — Falhe visivelmente, não silenciosamente

As falhas mais caras do Claude parecem sucesso. Uma função "funciona", mas retorna dados errados. Uma migração "conclui", mas ignorou 30 registros. Um teste "passa", mas a asserção estava errada.

O momento: O Claude relatou que uma migração de banco de dados "foi concluída com sucesso." Ele havia ignorado silenciosamente 14% dos registros que atingiram uma violação de restrição. A omissão foi registrada em log, mas não foi exposta. Descoberto 11 dias depois, quando os relatórios começaram a parecer errados.

5. Os Números

Mnimiy acompanhou as mesmas 50 tarefas representativas em 30 codebases ao longo de 6 semanas, em três configurações: sem CLAUDE.md, 4 regras originais, 12 regras completas. A taxa de erro é a parcela de tarefas que exigiram correção ou reescrita para corresponder à intenção — contabilizada em sete tipos distintos de falha (suposição errada silenciosa, over-engineering, dano ortogonal, falha silenciosa, violação de convenção, média de conflitos, checkpoint perdido).

A queda principal (41% → 3%) é o resultado óbvio. O interessante resultado é que passar de 4 regras para 12 adicionou quase nenhum overhead de conformidade (78% → 76%) enquanto reduziu a taxa de erro em mais 8 pontos. As novas regras cobrem modos de falha que as 4 originais não tocavam — elas não competem pelo mesmo orçamento de atenção.

Este é o caso empírico para ir além de 4. Se adicionar regras custasse conformidade proporcionalmente, você pararia em 4. Não custa.

6. Onde o Template Original Quebra Silenciosamente

Quatro cenários onde os 4 de Karpathy não são suficientes — mesmo antes de adicionar regras. O artigo é explícito que o original não está errado, ele está abordando o espaço de problemas de janeiro de 2026:

1. Tarefas de agentes de longa duração. As regras focam no momento em que o Claude escreve código. Elas são omissas sobre pipelines de múltiplas etapas. Nenhuma regra de orçamento. Nenhuma regra de checkpoint. Nenhuma regra de fail-loud. Pipelines sofrem desvios.
2. Consistência entre múltiplas bases de código. "Match existing style" assume um único estilo. Em um monorepo com 12 serviços, o Claude precisa escolher qual estilo seguir. As regras originais não dizem como. Ele escolhe aleatoriamente ou faz uma média.
3. Qualidade dos testes. Goal-Driven Execution trata "testes passarem" como sucesso. Não diz que os testes precisam ser significativos. O resultado são testes que não testam nada útil, mas deixam o Claude confiante.
4. Produção vs protótipo. As mesmas 4 regras que protegem o código de produção contra over-engineering também atrasam protótipos que legitimamente precisam de 100 linhas de scaffolding especulativo para definir uma direção. "Simplicity First" acaba sendo rigoroso demais em códigos de estágio inicial.

7. O que não funcionou (Os experimentos que falharam)

Possivelmente a seção mais útil do artigo — não as regras que foram selecionadas, mas os padrões que explicitamente não foram:

• Regras coletadas de redes sociais. A maioria era apenas uma reescrita dos 4 de Karpathy com palavras diferentes, ou regras específicas de domínio ("sempre use classes Tailwind") que não se generalizam. Cortadas.
• Mais de 14 regras. Mnimiy testou até 18. A conformidade caiu de 76% para 52% após 14. O teto de 200 linhas que a Anthropic documenta é real — passando disso, o Claude faz pattern-matching para "regras existem" sem realmente lê-las.
• Regras dependentes de ferramentas. "Always use eslint" falha silenciosamente quando o eslint não está instalado. Substituído por frases agnósticas à capacidade: "corresponder ao estilo imposto pela base de código."
• Exemplos em vez de regras. Três exemplos custam tanto contexto quanto ~10 regras e o Claude sofre over-fitting com eles. Regras são abstratas, exemplos são específicos. Use regras.
• Intensificadores vagos. "Tenha cuidado," "pense bem," "foque de verdade." Conformidade ~30% porque nada disso é testável. Substituído por imperativos concretos como "declare as premissas explicitamente."
• Prompts de identidade. Dizer ao Claude para ser "senior" não funciona. O Claude já acha que é senior. A lacuna de conformidade está entre o pensar e o fazer. Imperativos fecham essa lacuna; prompts de identidade não.

8. O Modelo Mental

Reduza o artigo à sua frase principal e você terá isto:

Isso muda tudo. A maioria dos desenvolvedores trata o CLAUDE.md como um arquivo de preferências pessoais — uma lista de gostos e desgostos estilísticos que cresce com o tempo. O argumento do artigo é que um arquivo de preferências é o formato errado. O formato correto é uma lista de modos de falha que você realmente encontrou, com uma regra para cada modo.

Isso também explica por que o artigo termina com uma recomendação contraintuitiva:

Um CLAUDE.md de 6 regras ajustado aos seus modos de falha reais supera um de 12 regras com 6 regras que você nunca precisará.

Não cole todas as 12 só porque alguém no X disse para fazer isso. Leia-as, mantenha as que correspondem a erros que você já cometeu e descarte o restante.

9. Mapeando para o Antigravity (GEMINI.md / AGENTS.md)

O artigo é focado no Claude, mas a abstração é portável. O Antigravity lê regras procedimentais de dois arquivos no mesmo formato:

• GEMINI.md — o arquivo de system prompt específico do Gemini. Veja nosso guia do GEMINI.md.
• AGENTS.md — o formato multi-ferramenta (funciona com Claude Code, Cursor, Antigravity). Veja nosso Guia AGENTS.md.

Ambos são recomendativos, não obrigatórios, ambos limitam-se a cerca de 200 linhas antes que a conformidade diminua, e ambos seguem a mesma disciplina de "enuncie a regra, sem exemplos, sem intensificadores vagos". As 12 regras transferem-se essencialmente sem alterações. Considerações específicas do Antigravity:

1. A Regra 6 (orçamentos de tokens) torna-se crítica, não opcional. A cota do Antigravity consome-se mais rápido do que a do Claude Code. Combine a regra com o nosso playbook de redução de tokens.
2. A Regra 10 (checkpoints) mapeia para o Agent Manager do Antigravity. Se uma execução multi-agente falhar no passo 4, você vai querer encerrar o agente e retomar a partir de um artefato anterior, não do zero.
3. A Regra 7 (expor conflitos) ajuda em trocas de modelos. Se você alternar entre Gemini e Claude Opus no meio da sessão (conforme abordado em nossa análise de troca de modelos), o novo modelo frequentemente herda contexto obsoleto do antigo e tenta reconciliar padrões incompatíveis.
4. A Regra 12 (falhe visivelmente) é a mais subestimada para o Autopilot. Se você executar o auto-accept, falhas silenciosas acumulam-se em vários ciclos de Cmd-Enter antes que você as perceba. Force o agente a expor cada etapa ignorada.

Mesmo template, runtime diferente, mesma lógica.

10. O Template Completo de 12 Regras (Pronto para Copiar e Colar)

Salve isto como CLAUDE.md (ou GEMINI.md ou AGENTS.md) na raiz do seu repositório. O artigo original observa: mantenha o tamanho total do arquivo abaixo de 200 linhas combinadas, incluindo quaisquer adições específicas do projeto abaixo; além disso, a conformidade diminui.

Esse é o arquivo. Duas coisas a fazer com ele:

1. Leia as 12 honestamente. Quais delas correspondem a erros que você realmente cometeu este mês? Mantenha essas. Descarte o restante. Um arquivo de 6 regras ajustado aos seus modos de falha é melhor que um arquivo de 12 regras com regras que você nunca acionará.
2. Adicione regras específicas do projeto abaixo. Stack-specific ("always use the Repository pattern"), test-runner ("run pnpm test:unit before reporting done"), error patterns. Keep the total under 200 lines.

11. FAQ