As 4 regras do CLAUDE.md de Karpathy reduziram os erros do Claude de 41% para 11%. Após 30 bases de código, adicionei mais 8

No final de janeiro de 2026, Andrej Karpathy publicou uma thread reclamando de como o Claude escreve código. Três modos de falha: suposições silenciosas e erradas, complicação excessiva, danos ortogonais em código que não deveria ter tocado.

Forrest Chang leu a thread, organizou as reclamações em 4 regras comportamentais em um único arquivo CLAUDE.md e o colocou no GitHub. Ele atingiu 5.828 estrelas no primeiro dia. 60.000 favoritos em duas semanas. 120.000 estrelas hoje. O repositório de arquivo único que mais cresceu em 2026.

Então eu o testei em 30 bases de código ao longo de 6 semanas.

As 4 regras funcionam. Erros que costumavam acontecer ~40% das vezes caíram para menos de 3% em tarefas que se alinhavam com seus pontos fortes. Mas o modelo foi construído para corrigir erros de escrita de código de janeiro.

O ecossistema do Claude Code em maio de 2026 tem problemas diferentes — conflitos entre agentes, cascatas de hooks, conflitos de carregamento de habilidades, fluxos de trabalho de várias etapas que quebram entre sessões.

Então adicionei mais 8 regras. Abaixo: as 12 regras completas do CLAUDE.md, por que cada uma merece seu lugar e os 4 lugares onde o modelo original do Karpathy quebra silenciosamente.

Se você quiser pular as explicações e apenas colar, o arquivo completo está no final.

Por que isso é importante

O CLAUDE.md do Claude Code é o arquivo mais subutilizado em toda a pilha de codificação de IA. A maioria dos desenvolvedores ou:

• Trata-o como um despejo para cada preferência que já tiveram, inflado para mais de 4.000 tokens, conformidade cai para 30%
• Pula-o completamente e faz prompting toda vez — 5x mais desperdício de tokens, sem consistência entre sessões
• Copia um modelo uma vez e esquece. Funciona por duas semanas, depois quebra silenciosamente à medida que sua base de código muda

A documentação oficial da Anthropic é explícita: CLAUDE.md é consultivo. Claude o segue cerca de 80% das vezes. Acima de 200 linhas, a conformidade cai drasticamente porque regras importantes ficam enterradas no ruído.

O modelo do Karpathy resolveu isso em um arquivo, 65 linhas, 4 regras. Esse é o piso.

O teto é mais alto. Com mais 8 regras, as que abordarei abaixo, você cobre não apenas os problemas de escrita de código de janeiro de 2026 sobre os quais Karpathy reclamou, mas também os problemas de orquestração de agentes de maio de 2026 que ainda não existiam quando o modelo foi escrito.

As 4 regras originais

Se você não leu o repositório do Forrest Chang, o piso:

**Regra 1 — Pense Antes de Codificar.

**Sem suposições silenciosas. Declare o que você está assumindo. Superficie trade-offs. Pergunte antes de adivinhar. Reaja quando existir uma abordagem mais simples.

**Regra 2 — Simplicidade Primeiro.

**Mínimo de código que resolve o problema. Sem funcionalidades especulativas. Sem abstrações para código de uso único. Se um engenheiro sênior consideraria complicado demais — simplifique.

**Regra 3 — Mudanças Cirúrgicas.

**Toque apenas no que for necessário. Não "melhore" código, comentários ou formatação adjacentes. Não refatore o que não está quebrado. Corresponda ao estilo existente.

**Regra 4 — Execução Orientada a Objetivos.

**Defina critérios de sucesso. Itere até verificar. Não diga ao Claude quais passos seguir, diga a ele como é o sucesso e deixe-o iterar.

Essas quatro fecham ~40% dos modos de falha que vejo em sessões não supervisionadas do Claude Code. Os ~60% restantes vivem nas lacunas abaixo.

As 8 regras que adicionei (e porquê)

Cada uma delas veio de um momento real onde as 4 do Karpathy não eram suficientes. Mostrarei o momento, depois a regra.

Regra 5 — Não faça o modelo fazer trabalho não linguístico

As regras do Karpathy são silenciosas sobre isso. O modelo decide coisas que deveriam ser código determinístico, se deve ou não tentar novamente uma chamada de API, como rotear uma mensagem, quando escalar. Decisões diferentes a cada semana. If-else instável a $0,003 por token.

1## Regra 5 — Use o modelo apenas para julgamentos
2Use o Claude para: classificação, redação, sumarização, extração de texto não estruturado.
3NÃO use o Claude para: roteamento, novas tentativas, tratamento de códigos de status, transformações determinísticas.
4Se um código de status já responde à pergunta, código puro responde à pergunta.

O momento: Código que chamava o Claude para "decidir se devemos tentar novamente em caso de 503" funcionou lindamente por duas semanas, depois começou a falhar porque o modelo começou a ler o corpo da requisição como contexto para a decisão. A política de novas tentativas era aleatória porque o prompt era aleatório.

Regra 6 — Orçamentos de token rígidos, sem exceções

CLAUDE.md sem orçamentos é um cheque em branco. Cada loop tem a chance de espiralar em um despejo de contexto de 50.000 tokens. O modelo não vai parar sozinho.

1## Regra 6 — Orçamentos de token não são consultivos
2Orçamento por tarefa: 4.000 tokens.
3Orçamento por sessão: 30.000 tokens.
4Se uma tarefa estiver se aproximando do orçamento, resuma e comece de novo. Não insista.
5Superficiar a violação > ultrapassar silenciosamente.

O momento: Uma sessão de depuração durou 90 minutos. O modelo estava perfeitamente feliz em iterar sobre a mesma mensagem de erro de 8KB, gradualmente perdendo o controle de qual correção já havia tentado. No final, estava sugerindo correções que eu havia rejeitado 40 mensagens antes. O orçamento de token teria interrompido no minuto 12.

Regra 7 — Superficie conflitos, não os equilibre

Quando duas partes da base de código discordam, Claude tenta agradar a ambas. O resultado é incoerente.

1## Regra 7 — Superficie conflitos, não os equilibre
2Se dois padrões existentes na base de código se contradizem, não os misture.
3Escolha um (o mais recente / mais testado), explique o porquê e sinalize o outro para limpeza.
4Código "médio" que satisfaz ambas as regras é o pior código.

O momento: Uma base de código tinha dois padrões de tratamento de erro — um async/await com try/catch explícito, outro com um limite de erro global. Claude escreveu um novo código que fazia ambos. Manipuladores de erro duplicados. Levei 30 minutos para descobrir por que os erros eram engolidos duas vezes.

Regra 8 — Leia antes de escrever

A "Mudanças Cirúrgicas" do Karpathy diz ao Claude para não tocar no código adjacente. Não diz ao Claude para entender o código adjacente primeiro. Sem isso, Claude escreve novo código que entra em conflito com o código existente a 30 linhas de distância.

1## Regra 8 — Leia antes de escrever
2Antes de adicionar código em um arquivo, leia as exportações do arquivo, o chamador imediato e quaisquer utilitários compartilhados óbvios.
3Se você não entende por que o código existente está estruturado da maneira que está, pergunte antes de adicionar a ele.
4"Parece ortogonal para mim" é a frase mais perigosa nesta base de código.

O momento: Claude adicionou uma função ao lado de uma função idêntica existente que ele não havia lido. Ambas as funções faziam a mesma coisa. A nova tinha precedência por causa da ordem de importação. A antiga era a fonte da verdade há 6 meses.

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

A Execução Orientada a Objetivos do Karpathy implica testes como critérios de sucesso. Na prática, Claude trata "testes passam" como o único objetivo e escreve código que passa em testes superficiais enquanto quebra todo o resto.

1## Regra 9 — Testes verificam a intenção, não apenas o comportamento
2Cada teste deve codificar POR QUE o comportamento importa, não apenas O QUE ele faz.
3Um teste como `expect(getUserName()).toBe('João')` é inútil se a função recebe um ID fixo.
4Se você não pode escrever um teste que falharia quando a lógica de negócios mudar, a função está errada.

O momento: Claude escreveu 12 testes para uma função de autenticação. Todos passaram. A autenticação estava quebrada em produção. Os testes estavam testando se a função retornava algo, não se retornava a coisa certa. A função passou porque estava retornando uma constante.

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

O modelo do Karpathy assume interações únicas. O trabalho real do Claude Code é de várias etapas — refatoração em 20 arquivos, construção de funcionalidades ao longo de uma sessão, depuração em vários commits. Sem pontos de verificação, um passo errado perde todo o progresso.

1## Regra 10 — Ponto de verificação após cada etapa significativa
2Após concluir cada etapa em uma tarefa de várias etapas: resuma o que foi feito, o que está verificado, o que resta.
3Não continue a partir de um estado que você não pode descrever de volta para mim.
4Se você perder o controle, pare e reafirme.

O momento: Uma refatoração de 6 etapas deu errado na etapa 4. Quando percebi, Claude já havia feito as etapas 5 e 6 em cima do estado quebrado. Desembaraçar levou mais tempo do que refazer tudo. Pontos de verificação teriam pego na etapa 4.

Regra 11 — Convenção supera novidade

Em uma base de código com padrões estabelecidos, Claude gosta de introduzir os seus próprios. Mesmo quando sua maneira é "melhor", a introdução de dois padrões é pior do que qualquer padrão sozinho.

1## Regra 11 — Corresponda às convenções da base de código, mesmo que discorde
2Se a base de código usa snake_case e você prefere camelCase: snake_case.
3Se a base de código usa componentes baseados em classe e você prefere hooks: baseado em classe.
4A discordância é uma conversa separada. Dentro da base de código, conformidade > gosto.
5Se você realmente acha que a convenção é prejudicial, superficialize-a. Não a bifurque silenciosamente.

O momento: Claude introduziu React hooks em uma base de código de componentes de classe. Eles funcionaram. Também quebraram os padrões de teste da base de código, que assumiam componentDidMount. Meio dia para remover e reescrever.

Regra 12 — Falhe visivelmente, não silenciosamente

As falhas mais caras do Claude são aquelas que parecem sucesso. Uma função "funciona" mas retorna dados errados. Uma migração "é concluída" mas pula 30 registros. Um teste "passa" mas apenas porque a asserção estava errada.

1## Regra 12 — Falhe alto
2Se você não pode ter certeza de que algo funcionou, diga-o explicitamente.
3"Migração concluída" está errado se 30 registros foram pulados silenciosamente.
4"Testes passam" está errado se você pulou algum.
5"Funcionalidade funciona" está errado se você não verificou o caso extremo sobre o qual perguntei.
6O padrão é superficializar a incerteza, não escondê-la.

O momento: Claude disse que uma migração de banco de dados "foi concluída com sucesso." Ela havia pulado silenciosamente 14% dos registros que encontraram uma violação de restrição. A omissão foi registrada, mas não superficializada. Descoberto o problema 11 dias depois, quando os relatórios começaram a parecer errados.

Os números

Acompanhei o mesmo conjunto de 50 tarefas representativas em 30 bases de código por 6 semanas. Três configurações:

Taxa de erro = tarefa exigiu correção ou reescrita para corresponder à intenção. Contagens: suposição errada silenciosa, engenharia excessiva, dano ortogonal, falha silenciosa, violação de convenção, equilíbrio de conflito, ponto de verificação perdido.

Conformidade = com que frequência Claude aplicou visivelmente a regra relevante quando era aplicável.

O resultado interessante não é a queda principal de 41% para 3%. É que ir de 4 regras para 12 adicionou quase nenhuma sobrecarga de conformidade (78% -> 76%) mas reduziu a taxa de erro em mais 8 pontos. As novas regras cobrem modos de falha que as 4 originais não abordavam — elas não competem pelo mesmo orçamento de atenção.

Onde o modelo do Karpathy quebra silenciosamente

Quatro lugares onde o modelo original de 4 regras não é suficiente, mesmo antes de adicionar novas regras:

**1. Tarefas de agente de longa duração.

*As regras do Karpathy visam o momento em que Claude está escrevendo código. Elas são silenciosas sobre o que acontece quando Claude está executando* um pipeline de várias etapas. Sem regra de orçamento. Sem regra de ponto de verificação. Sem regra de "falhe alto". Pipelines derivam.

**2. Consistência entre múltiplas bases de código.

**"Corresponda ao estilo existente" assume um estilo. Em um monorepo com 12 serviços, Claude tem que escolher qual estilo. As regras originais não dizem como. Ele escolhe aleatoriamente ou equilibra.

**3. Qualidade do teste.

*A Execução Orientada a Objetivos trata "testes passam" como sucesso. Não diz que os testes têm que ser significativos*. O resultado são testes que não testam nada útil, mas deixam Claude confiante.

**4. Produção vs. protótipo.

**As mesmas 4 regras que protegem o código de produção da engenharia excessiva também atrasam protótipos que legitimamente precisam de 100 linhas de scaffolding especulativo para descobrir uma direção. A "Simplicidade Primeiro" do Karpathy dispara excessivamente em código de estágio inicial.

As 8 regras adicionadas não substituem as 4 do Karpathy. Elas corrigem as lacunas onde seu modelo, janeiro de 2026, codificação estilo autocomplete, não corresponde ao trabalho de maio de 2026, orientado a agente, de várias etapas e múltiplas bases de código.

O que não funcionou

Coisas que tentei antes de me decidir pelas 12 regras:

• Adicionar regras que vi no Reddit / X. A maioria era ou reafirmações das 4 do Karpathy com palavras diferentes, ou regras específicas de domínio ("use sempre classes Tailwind") que não generalizam. Cortei-as.
• Mais de 12 regras. Testei até 18. A conformidade caiu de 76% para 52% após 14 regras. O limite de 200 linhas é real. Acima disso, Claude começa a fazer correspondência de padrões para "regras existem" sem realmente lê-las.
• Regras que dependem de ferramentas que podem não existir. "Sempre use eslint" quebra quando o eslint não está instalado. A regra falha silenciosamente. Substituído por frases agnósticas de capacidade: "corresponda ao estilo imposto pela base de código" em vez de "use eslint."
• Exemplos no CLAUDE.md em vez de regras. Exemplos são mais pesados que regras. Três exemplos custam tanto contexto quanto ~10 regras e Claude se ajusta excessivamente a eles. Regras são abstratas, exemplos são específicos. Use regras.
• "Tenha cuidado" / "pense muito" / "concentre-se realmente." Ruído puro. A conformidade com estes caiu para ~30% porque não são testáveis. Substituído por imperativos concretos ("declare suposições explicitamente").
• Dizer ao Claude para ser "sênior." Não funciona. Claude já pensa que é sênior. A lacuna de conformidade está entre pensar e fazer. Regras imperativas fecham a lacuna; prompts de identidade não.

O CLAUDE.md completo de 12 regras (pronto para copiar e colar)

1# CLAUDE.md — Modelo de 12 regras
2
3Estas regras se aplicam a toda tarefa neste projeto, a menos que explicitamente substituídas.
4Viés: cautela sobre velocidade em trabalho não trivial. Use julgamento em tarefas triviais.
5
6## Regra 1 — Pense Antes de Codificar
7Declare suposições explicitamente. Se estiver incerto, pergunte em vez de adivinhar.
8Apresente múltiplas interpretações quando existir ambiguidade.
9Reaja quando existir uma abordagem mais simples.
10Pare quando estiver confuso. Nomeie o que não está claro.
11
12## Regra 2 — Simplicidade Primeiro
13Mínimo de código que resolve o problema. Nada especulativo.
14Sem funcionalidades além do que foi solicitado. Sem abstrações para código de uso único.
15Teste: um engenheiro sênior diria que isso é complicado demais? Se sim, simplifique.
16
17## Regra 3 — Mudanças Cirúrgicas
18Toque apenas no que for necessário. Limpe apenas a sua própria bagunça.
19Não "melhore" código, comentários ou formatação adjacentes.
20Não refatore o que não está quebrado. Corresponda ao estilo existente.
21
22## Regra 4 — Execução Orientada a Objetivos
23Defina critérios de sucesso. Itere até verificar.
24Não siga passos. Defina sucesso e itere.
25Critérios de sucesso fortes permitem que você itere de forma independente.
26
27## Regra 5 — Use o modelo apenas para julgamentos
28Use-me para: classificação, redação, sumarização, extração.
29NÃO me use para: roteamento, novas tentativas, transformações determinísticas.
30Se o código pode responder, o código responde.
31
32## Regra 6 — Orçamentos de token não são consultivos
33Por tarefa: 4.000 tokens. Por sessão: 30.000 tokens.
34Se estiver se aproximando do orçamento, resuma e comece de novo.
35Superficie a violação. Não ultrapasse silenciosamente.
36
37## Regra 7 — Superficie conflitos, não os equilibre
38Se dois padrões se contradizem, escolha um (o mais recente / mais testado).
39Explique o porquê. Sinalize o outro para limpeza.
40Não misture padrões conflitantes.
41
42## Regra 8 — Leia antes de escrever
43Antes de adicionar código, leia exportações, chamadores imediatos, utilitários compartilhados.
44"Parece ortogonal" é perigoso. Se não tiver certeza de por que o código está estruturado de uma certa forma, pergunte.
45
46## Regra 9 — Testes verificam a intenção, não apenas o comportamento
47Testes devem codificar POR QUE o comportamento importa, não apenas O QUE ele faz.
48Um teste que não pode falhar quando a lógica de negócios muda está errado.
49
50## Regra 10 — Ponto de verificação após cada etapa significativa
51Resuma o que foi feito, o que está verificado, o que resta.
52Não continue a partir de um estado que você não pode descrever de volta.
53Se você perder o controle, pare e reafirme.
54
55## Regra 11 — Corresponda às convenções da base de código, mesmo que discorde
56Conformidade > gosto dentro da base de código.
57Se você realmente acha que uma convenção é prejudicial, superficialize-a. Não a bifurque silenciosamente.
58
59## Regra 12 — Falhe alto
60"Concluído" está errado se algo foi pulado silenciosamente.
61"Testes passam" está errado se algum foi pulado.
62O padrão é superficializar a incerteza, não escondê-la.

Salve como CLAUDE.md na raiz do seu repositório. Adicione regras específicas do projeto abaixo das 12 (stack, comandos de teste, padrões de erro). Não ultrapasse 200 linhas combinadas, acima disso, a conformidade cai.

Como instalar

Dois passos:

1# 1. Anexe a linha de base de 4 regras do Karpathy ao seu CLAUDE.md
2curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
3
4# 2. Cole as regras 5-12 deste artigo abaixo

Salve na raiz do seu repositório. O >> importa, ele anexa ao seu CLAUDE.md existente em vez de sobrescrever quaisquer regras específicas do projeto que você já tenha.

O modelo mental

CLAUDE.md não é uma lista de desejos. É um contrato comportamental que fecha modos de falha específicos que você observou.

Cada regra deve responder: que erro isso previne?

As 4 do Karpathy previnem os modos de falha que ele viu em janeiro de 2026: suposições silenciosas, engenharia excessiva, dano ortogonal, critérios de sucesso fracos. Elas são fundamentais. Não as pule.

As 8 que adicionei previnem modos de falha que surgiram em maio de 2026: loops de agente sem orçamentos, tarefas de várias etapas sem pontos de verificação, testes que não testam, sucessos silenciosos escondendo falhas silenciosas. Elas são aditivas.

Sua milhagem pode variar. Se você não executa pipelines de várias etapas, a Regra 10 não importa. Se sua base de código tem um estilo consistente imposto por linting, a Regra 11 é redundante. Leia as 12, mantenha as que correspondem a erros que você realmente cometeu, descarte o resto.

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á.

F I M

A thread de janeiro de 2026 do Karpathy foi uma reclamação. Forrest Chang a transformou em 4 regras. 120.000 desenvolvedores marcaram o resultado com estrela. A maioria deles ainda está executando 4 regras hoje.

O modelo melhorou. O ecossistema mudou. Agentes de várias etapas, cascatas de hooks, carregamento de habilidades, trabalho em múltiplas bases de código — nada disso existia quando Karpathy escreveu sua thread. As 4 regras não os abordam. Elas não estão erradas; estão incompletas.

Mais 8 regras. 6 semanas de teste em 30 bases de código. Taxa de erro de 41% para 3%.

Marque isto como favorito e cole as 12 regras no seu CLAUDE.md hoje à noite. Reposte se isso te salvou uma semana de erros do Claude.

Telegram para dicas diárias de otimização do Claude:

*https://t.me/+_ZWrQN7GuDA3ZDEy*