As 4 regras 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 um tópico reclamando de como o Claude escreve código. Três modos de falha: suposições incorretas silenciosas, complicação excessiva e danos colaterais em código que não deveria ter sido alterado.

Forrest Chang leu o tópico, transformou as reclamações em 4 regras comportamentais em um único arquivo CLAUDE.md e o publicou no GitHub. Alcançou 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 cerca de 40% das vezes caíram para menos de 3% em tarefas que se alinhavam com seus pontos fortes. Mas o template foi criado 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 múltiplas etapas que quebram entre sessões.

Então adicionei mais 8 regras. Abaixo: o CLAUDE.md completo com 12 regras, por que cada uma merece seu lugar e os 4 pontos onde o template original do Karpathy falha 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 com IA. A maioria dos desenvolvedores ou:

• Trata-o como um depósito para todas as preferências que já tiveram, inflado para mais de 4.000 tokens, com conformidade caindo para 30%
• Ignora-o completamente e faz o prompt toda vez — 5x mais desperdício de tokens, sem consistência entre sessões
• Copia um template uma vez e esquece. Funciona por duas semanas, depois quebra silenciosamente à medida que a base de código muda

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

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

O teto é mais alto. Com mais 8 regras, as que vou mostrar abaixo, você cobre não apenas os problemas de escrita de código de janeiro de 2026 que Karpathy reclamou, mas também os problemas de orquestração de agentes de maio de 2026 que ainda não existiam quando o template 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. Mostre as compensações. Pergunte antes de adivinhar. Conteste quando existir uma abordagem mais simples.

**Regra 2 — Simplicidade Primeiro.

**Código mínimo 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 adjacente, comentários ou formatação. Não refatore o que não está quebrado. Siga o 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 como é o sucesso e deixe-o iterar.

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

As 8 regras que adicionei (e por quê)

Cada uma delas veio de um momento real onde as 4 do Karpathy não eram suficientes. Vou mostrar o momento e 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 repetir 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, repetições, tratamento de códigos de status, transformações determinísticas.
4Se um código de status já responde à pergunta, código simples responde à pergunta.

O momento: Código que chamava o Claude para "decidir se devemos repetir 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 repetição era aleatória porque o prompt era aleatório.

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

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

1## Regra 6 — Orçamentos de tokens 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.
5Informar o estouro é melhor do que 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, perdendo gradualmente 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 tokens teria interrompido no minuto 12.

Regra 7 — Mostre conflitos, não os misture

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

1## Regra 7 — Mostre conflitos, não os misture
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 erros — um com async/await e try/catch explícito, outro com um limite de erro global. O 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, o 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 daquela forma, pergunte antes de adicionar algo.
4"Parece ortogonal para mim" é a frase mais perigosa nesta base de código.

O momento: O 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 devido à 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, o 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 é importante, 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 consegue escrever um teste que falharia quando a lógica de negócios mudar, a função está errada.

O momento: O 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 passava porque estava retornando uma constante.

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

O template 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 de uma tarefa de várias etapas: resuma o que foi feito, o que está verificado e o que falta.
3Não continue a partir de um estado que você não consegue 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, o Claude já havia feito as etapas 5 e 6 em cima do estado quebrado. Desembaraçar levou mais tempo do que refazer tudo. Os pontos de verificação teriam detectado o problema na etapa 4.

Regra 11 — Convenção supera novidade

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

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

O momento: O 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 isso 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 que eu perguntei.
6Por padrão, mostre a incerteza, não a esconda.

O momento: O 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 foi mostrada. O problema foi descoberto 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 incorreta silenciosa, engenharia excessiva, dano colateral, falha silenciosa, violação de convenção, mistura de conflitos, ponto de verificação perdido.

Conformidade = com que frequência o 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 quase não adicionou sobrecarga de conformidade (78% -> 76%), mas reduziu a taxa de erro em mais 8 pontos percentuais. 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 template do Karpathy falha silenciosamente

Quatro lugares onde o template 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 o Claude está escrevendo código. Elas são silenciosas sobre o que acontece quando o 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.

**"Siga o estilo existente" assume um único estilo. Em um monorepo com 12 serviços, o Claude precisa escolher qual estilo. As regras originais não dizem como. Ele escolhe aleatoriamente ou faz uma média.

**3. Qualidade do teste.

*A Execução Orientada a Objetivos trata "testes passam" 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 engenharia excessiva também atrasam protótipos que legitimamente precisam de 100 linhas de andaime 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 o modelo dele, de janeiro de 2026, codificação estilo autocomplete, não corresponde ao trabalho de maio de 2026, orientado a agentes, 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 apenas reformulaçõ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, o 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. "Use sempre eslint" quebra quando o eslint não está instalado. A regra falha silenciosamente. Substituí por frases agnósticas de capacidade: "siga o 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 o 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 essas caiu para ~30% porque não são testáveis. Substituí por imperativos concretos ("declare suposições explicitamente").
• Dizer ao Claude para ser "sênior." Não funciona. O Claude já acha 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 com 12 regras (pronto para copiar e colar)

1# CLAUDE.md — Template de 12 regras
2
3Estas regras se aplicam a todas as tarefas neste projeto, a menos que explicitamente substituídas.
4Viés: cautela sobre velocidade em trabalhos não triviais. 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 houver ambiguidade.
9Conteste quando existir uma abordagem mais simples.
10Pare quando estiver confuso. Nomeie o que não está claro.
11
12## Regra 2 — Simplicidade Primeiro
13Código mínimo 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 adjacente, comentários ou formatação.
20Não refatore o que não está quebrado. Siga o estilo existente.
21
22## Regra 4 — Execução Orientada a Objetivos
23Defina critérios de sucesso. Itere até verificar.
24Não siga passos. Defina o 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, repetições, transformações determinísticas.
30Se o código pode responder, o código responde.
31
32## Regra 6 — Orçamentos de tokens 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.
35Informe o estouro. Não ultrapasse silenciosamente.
36
37## Regra 7 — Mostre conflitos, não os misture
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 souber 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 é importante, 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 e o que falta.
52Não continue a partir de um estado que você não consegue descrever de volta.
53Se perder o controle, pare e reafirme.
54
55## Regra 11 — Siga as convenções da base de código, mesmo que discorde
56Conformidade > gosto pessoal dentro da base de código.
57Se você realmente acha que uma convenção é prejudicial, sinalize-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.
62Por padrão, mostre a incerteza, não a esconda.

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 no total, acima disso, a conformidade cai.

Como instalar

Dois passos:

1# 1. Anexe a 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 a 12 deste artigo abaixo

Salve na raiz do seu repositório. O >> é importante, 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 colateral, 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 experiência 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 é melhor do que um de 12 regras com 6 regras que você nunca vai precisar.

F I M

O tópico 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á usando 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 seu tópico. As 4 regras não abordam isso. Elas não estão erradas; estão incompletas.

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

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

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

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