Título original: As 4 regras do CLAUDE de Karpathy reduzem os erros do Claude de 41% para 11%. Após 30 bases de código, adicionei mais 8
Autor original: @Mnilax
Compilado por: Peggy, BlockBeats

Prefácio: Em janeiro de 2026, Andrej Karpathy reclamou do modo como Claude escreve código, o que levou à criação de um arquivo aparentemente simples, mas extremamente crucial no fluxo de trabalho de programação AI: CLAUDE.md. Forrest Chang então organizou essas reclamações em 4 regras de comportamento, tentando limitar erros comuns do Claude na codificação: suposições silenciosas, engenharia excessiva, danos a código irrelevante e falta de critérios claros de sucesso.

Porém, meses depois, o cenário de uso do Claude Code já não se limitava a “fazer o modelo escrever um trecho de código”. Com agentes de múltiplos passos, gatilhos em cadeia, carregamento de habilidades e colaboração entre múltiplos repositórios se tornando norma, novos padrões de falha começaram a surgir: o modelo perde controle em tarefas longas, passa nos testes sem validar a lógica real, ignora silenciosamente erros após migração, e estilos de código diferentes são misturados erroneamente.

O autor testou 30 repositórios em 6 semanas e, com base nas 4 regras originais de Karpathy, adicionou mais 8 regras, tentando cobrir os novos problemas que surgiram na transição do AI de uma única conclusão para colaboração em agentes.

A seguir, o texto original:

No final de janeiro de 2026, Andrej Karpathy publicou uma série de tweets reclamando do modo como Claude escreve código. Ele apontou três problemas típicos: fazer suposições erradas sem explicação, complexidade excessiva e danos irrelevantes ao código que não deveria ser alterado.

Forrest Chang viu essa série de tweets, organizou as reclamações em 4 regras de comportamento, escreveu-as em um arquivo separado chamado CLAUDE.md e publicou no GitHub. O projeto, no seu primeiro dia, recebeu 5.828 estrelas, foi salvo 60.000 vezes em duas semanas, e hoje possui 120.000 estrelas, tornando-se o repositório de arquivo único de crescimento mais rápido em 2026.

Depois, em 6 semanas, testei com 30 repositórios.

Essas 4 regras realmente funcionam. Os erros que antes ocorriam com cerca de 40% de probabilidade caíram para menos de 3% em tarefas onde essas regras são aplicáveis. Mas o problema é que esse template foi inicialmente criado para resolver os erros que surgiram em janeiro, quando Claude escrevia código.

Até maio de 2026, o ecossistema Claude Code enfrentava problemas diferentes: conflitos entre agentes, gatilhos em cadeia, conflitos no carregamento de habilidades e interrupções em fluxos de trabalho multi-etapas entre sessões.

Por isso, adicionei mais 8 regras. A seguir, a versão completa do CLAUDE.md com 12 regras: por que cada uma vale a pena, e onde o template original de Karpathy falha silenciosamente em 4 pontos.

Se preferir pular a explicação e copiar direto, o arquivo completo está ao final.

Por que isso é importante

O CLAUDE.md do Claude Code é o arquivo mais subestimado de toda a pilha de tecnologia de programação AI. A maioria dos desenvolvedores comete três tipos de erro:

Primeiro, tratá-lo como uma lixeira de preferências, colocando todos os seus hábitos lá dentro, até que o arquivo ultrapasse 4000 tokens, fazendo a taxa de conformidade cair para 30%.

Segundo, simplesmente não usá-lo, sempre recomeçando o prompt do zero. Isso gera um desperdício de tokens em torno de 5 vezes maior e falta de consistência entre sessões.

Terceiro, copiar um template e nunca mais mexer nele. Pode funcionar por duas semanas, mas à medida que o repositório muda, ele se torna obsoleto sem que você perceba.

A documentação oficial da Anthropic afirma claramente: CLAUDE.md é apenas uma recomendação. Claude segue aproximadamente 80% das regras. Quando o arquivo ultrapassa 200 linhas, a conformidade cai visivelmente, pois as regras importantes se perdem no ruído.

O template de Karpathy resolve esse problema: um arquivo, 65 linhas, 4 regras. Essa é a base mínima.

Mas o limite pode ser aumentado. Com as 8 regras adicionais abaixo, ele cobre não só os problemas de escrita de código de janeiro de 2026, mas também os problemas de orquestração de agentes que só surgiram em maio de 2026 — problemas que ainda não existiam na versão original.

As 4 regras originais

Se você ainda não viu o repositório de Forrest Chang, comece por essa versão básica:

Regra 1: Pense antes de codificar.

Não faça suposições silenciosas. Explique suas hipóteses, exponha trade-offs. Antes de adivinhar, pergunte. Quando houver uma solução mais simples, proponha uma objeção.

Regra 2: Priorize simplicidade.
Use o mínimo de código capaz de resolver o problema. Não adicione funcionalidades imaginadas. Não crie abstrações para código pontual. Se um engenheiro sênior achar excessivo, simplifique.

Regra 3: Modificações cirúrgicas.
Altere apenas o que for necessário. Não otimize código, comentários ou formatação adjacentes sem motivo. Não refatore o que não está quebrado. Mantenha o estilo existente.

Regra 4: Execute com foco no objetivo.
Defina critérios de sucesso primeiro, depois itere até validar. Não diga ao Claude como fazer cada passo, diga qual deve ser o resultado final, e deixe que ele itere por conta própria.

Essas 4 regras resolvem cerca de 40% dos padrões de falha que vejo em sessões não supervisionadas de Claude Code. Os outros 60% estão nas áreas que seguem abaixo.

As 8 regras adicionais e por quê

Cada uma delas surge de uma situação real: as 4 regras originais de Karpathy já não eram suficientes. Primeiro, explicarei o cenário, depois as regras correspondentes.

Regra 5: Não deixe o modelo fazer tarefas não linguísticas

Pode usar Claude para: classificação, rascunho, resumo, extração de informações de textos não estruturados.
Não use Claude para: roteamento, tentativas de reexecução, manipulação de códigos de status, transformações determinísticas.
Se um código de status já respondeu à sua pergunta, deixe o código normal responder.

A regra de Karpathy não cobria isso. Assim, o modelo começou a decidir questões que deveriam ser tratadas por código determinístico: se re-tentar uma API, como roteá-la, quando fazer upgrade. O resultado era uma lógica de decisão instável, cobrada a cada token a US$0,003.

Naquele momento: havia um trecho de código que chamava Claude para “decidir se deve re-tentar ao receber 503”. Funcionou bem por duas semanas, até que ficou instável, pois o modelo começou a incluir o corpo da requisição na decisão. A estratégia de re-tentativa virou aleatória, pois o prompt também era aleatório.

Regra 6: Defina um limite rígido de tokens, sem exceções

Limite de tokens por tarefa: 4.000. Limite de tokens por sessão: 30.000.
Se uma tarefa estiver perto do limite, resuma o estado atual e reinicie. Não insista. Expor claramente o limite é melhor do que ultrapassá-lo silenciosamente.

Sem limites, o CLAUDE.md é como um cheque em branco. Cada ciclo pode se transformar numa sobrecarga de 50.000 tokens no contexto, sem que o modelo pare por conta própria.

Naquele momento: uma sessão de debug durou 90 minutos. O modelo ficou repetindo a mesma sequência de 8 KB de erro, esquecendo o que já tinha tentado. No final, propôs 40 soluções que eu já tinha rejeitado. Com limite de tokens, essa sessão deveria ter sido encerrada na 12ª minuto.

Regra 7: Exponha conflitos, não faça média

Se duas abordagens no repositório forem contraditórias, não misture.
Escolha uma, preferencialmente a mais recente ou testada, explique o motivo, e marque a outra para limpeza futura.
Tentar satisfazer ambas ao mesmo tempo é a pior prática de código.

Quando há conflitos, o Claude tenta agradar os dois lados, gerando código incoerente.

Naquele momento: um repositório tinha duas abordagens de tratamento de erro: async/await com try/catch explícito, e um erro global. O Claude misturou as duas, fazendo o tratamento duas vezes, e eu levei 30 minutos para entender por que os erros eram silenciados duas vezes.

Regra 8: Leia antes de escrever

Antes de adicionar código a um arquivo, leia suas exportações, os chamadores diretos e funções auxiliares relacionadas.
Se não entender a organização atual, pergunte antes de acrescentar.
“Para mim, isso não é relevante” é uma das frases mais perigosas nesse contexto.

O “cirurgião” de Karpathy ensina a não modificar código adjacente, mas não ensina a entender o código existente primeiro. Sem isso, o Claude pode criar código conflitante com o que já existe há meses.

Naquele momento: Claude criou uma função idêntica ao lado de uma existente, sem ler a original. Os dois fazem a mesma coisa, mas, por causa da ordem de importação, a nova substituiu a antiga, que já era padrão há 6 meses.

Regra 9: Testes não são opcionais, mas o teste não é o objetivo

Cada teste deve explicar “por que esse comportamento é importante”, não apenas “o que ele faz”.
Testes como expect(getUserName()).toBe(‘John’) são inúteis se a função recebe um ID fixo.
Se você não consegue criar um teste que falhe com mudanças na lógica, a função está errada.

“Executar com foco no objetivo” de Karpathy sugere que testes sejam critérios de sucesso. Mas, na prática, o Claude muitas vezes vê “passar no teste” como o objetivo final, criando código que passa testes superficiais, mas destrói lógica importante.

Naquele momento: Claude escreveu 12 testes para uma função de autenticação, todos passando, mas a lógica de produção estava quebrada. Os testes apenas verificavam se a função retornava algo, não se retornava o valor correto. A função passava porque retornava uma constante.

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

Em tarefas multi-etapas, após cada passo, resuma o que foi feito, o que foi validado e o que falta.
Não continue de um estado que você não consegue explicar. Se estiver perdido, pare e reitere o estado atual.

O template de Karpathy assume interação única. Na prática, o trabalho de Claude é muitas vezes multi-etapas: refatorar 20 arquivos, construir funcionalidades em uma sessão, depurar em vários commits. Sem checkpoints, um erro em uma etapa pode invalidar todo o progresso anterior.

Naquele momento: uma refatoração de 6 passos falhou na quarta etapa. Quando percebi, o Claude já tinha avançado na quinta e sexta, com o erro. Reparar leva mais tempo do que refazer tudo. Com checkpoints, o erro na quarta etapa seria detectado imediatamente.

Regra 11: Convenções vêm antes de inovação

Se o repositório usa snake_case, use snake_case.
Se usa componentes baseados em classes, use componentes baseados em classes.
Divergências geram conflitos. Dentro do repositório, a consistência é prioridade.
Se uma convenção é realmente prejudicial, proponha explicitamente, não crie ramificações silenciosas.

Quando Claude introduz uma nova abordagem em um repositório já consolidado, mesmo que “melhor”, isso pode gerar mais problemas do que soluções.

Naquele momento: Claude tentou usar hooks em um projeto React baseado em componentes de classe. Funcionou, mas quebrou testes que dependiam de componentDidMount. Demorei horas para remover e reescrever.

Regra 12: Falha explícita, não silenciosa

Se você não tem certeza de que algo foi bem-sucedido, declare explicitamente.
Se 30 registros foram ignorados silenciosamente, não diga “migração concluída”.
Se algum teste foi pulado, não diga “teste passou”.
Se você não verificou casos de borda, não diga “funcionalidade disponível”.
Exponha a incerteza, não a esconda.

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 pulando 14% das entradas com conflitos; um teste “passou”, mas por um erro na asserção.

Naquele momento: Claude afirmou que a migração do banco de dados “terminou com sucesso”. Mas, na verdade, pulou silenciosamente 14% dos registros que violavam restrições. O problema só foi descoberto 11 dias depois, quando os relatórios começaram a mostrar anomalias.

Resultados

Em 6 semanas, acompanhei 50 tarefas representativas, cobrindo 30 repositórios, com 3 configurações diferentes.

Erro é a necessidade de correção ou reescrita para alinhar com a intenção original. Inclui suposições silenciosas, engenharia excessiva, danos irrelevantes, falhas silenciosas, violações de convenções, conflitos de compromisso e omissões de checkpoints.

Taxa de conformidade é a probabilidade de uma regra ser aplicada explicitamente pelo Claude quando ela é relevante.

O resultado mais interessante não é só a redução do erro de 41% para 3%. Mas, ao expandir de 4 para 12 regras, a conformidade caiu de 78% para 76%, e o erro diminuiu em 8 pontos percentuais. As novas regras cobrem falhas que as 4 originais não abordavam, sem competir pelo mesmo orçamento de atenção.

Onde o template de Karpathy falha silenciosamente

Mesmo sem adicionar novas regras, o template original de 4 regras é insuficiente em pelo menos 4 áreas.

Primeiro, tarefas de agente de longa duração.
As regras de Karpathy focam no momento de escrever código. Mas, quando Claude executa um pipeline de múltiplos passos, o que acontece? O template não tem regras de limite de tokens, checkpoints ou “falha explícita”. Assim, o pipeline se desvia lentamente.

Segundo, consistência entre múltiplos repositórios.
“Combinar estilos existentes” assume um único estilo. Mas, em um monorepo com 12 serviços, Claude precisa escolher qual estilo seguir. O template não orienta essa decisão. Como resultado, ele pode escolher aleatoriamente ou misturar estilos, gerando incoerência.

Terceiro, qualidade dos testes.
“Executar com foco no objetivo” trata “passar no teste” como sucesso, mas não explica que o teste deve ser significativo. Assim, Claude pode criar testes que quase não verificam nada, levando a uma falsa sensação de segurança.

Quarto, diferenças entre ambiente de produção e protótipo.
As 4 regras podem evitar engenharia excessiva em produção, mas podem atrasar protótipos, que às vezes precisam de 100 linhas de código exploratório. A regra de simplicidade de Karpathy pode ser excessiva em fases iniciais.

Essas 8 regras adicionais não substituem as originais de Karpathy, mas as complementam. O template de 2026 de janeiro cobre cenários de preenchimento automático, enquanto o de maio lida com ambientes de múltiplos passos e colaboração entre agentes, que não existiam na versão inicial.

Métodos que não funcionaram

Antes de definir as 12 regras finais, tentei outras abordagens.

Incluir regras que vi no Reddit/X.
A maioria delas era apenas reformulação das 4 regras originais ou regras específicas de domínio, como “sempre usar Tailwind”. No final, foram descartadas.

Mais de 12 regras.
Testei até 18. Acima de 14, a conformidade caiu de 76% para 52%. O limite de 200 linhas é real. Além disso, após esse limite, o Claude começa a reconhecer “aqui há regras” ao invés de lê-las uma a uma.

Dependência de ferramentas específicas.
Por exemplo, “sempre usar eslint”. Se o projeto não usa eslint, a regra falha silenciosamente. Substituí por regras mais genéricas, como “seguir o estilo já imposto na base de código”.

Colocar exemplos no CLAUDE.md ao invés de regras.
Exemplos consomem mais contexto, quase o mesmo que 10 regras, e o Claude tende a overfitar nos exemplos. Regras são abstratas, exemplos são específicos. Portanto, regras são preferíveis.

“Seja mais cuidadoso”, “Pense com atenção”, “Foque mais”.
São ruído. Essas instruções têm conformidade de cerca de 30%, pois não podem ser verificadas. Substituí por comandos mais concretos, como “explique claramente suas hipóteses”.

Dizer ao Claude para agir como um “engenheiro sênior”.
Não adianta. Claude já se acha um engenheiro sênior. O problema não é a autoimagem, mas a execução. Comandos explícitos ajudam, prompts de identidade não.

Versão completa das 12 regras do CLAUDE.md

A seguir, a versão completa que pode ser copiada e colada diretamente.

Por ora, não é possível exibir fora do documento do Feishu.

Salve como CLAUDE.md na raiz do seu repositório. Abaixo das 12 regras, adicione regras específicas do seu projeto, como stack, comandos de teste, padrões de erro. Não ultrapasse 200 linhas, ou a conformidade cairá.

Como instalar

Dois passos:

1. Adicione as 4 regras básicas de Karpathy ao seu CLAUDE.md
   curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

2. Cole as regras 5 a 12 abaixo no arquivo

Salve na raiz do repositório. O “>>” é importante: ele acrescenta às regras existentes, não sobrescreve.

Modelo mental

CLAUDE.md não é uma lista de desejos, mas um contrato de comportamento para bloquear falhas específicas observadas.

Cada regra deve responder: “Qual erro ela previne?”

As 4 regras de Karpathy evitam falhas de janeiro de 2026: suposições silenciosas, engenharia excessiva, danos irrelevantes, critérios de sucesso fracos. São a base, não pule.

As 8 regras adicionais previnem novos padrões de falha de maio de 2026 em diante: ciclos de agentes sem limite de orçamento, tarefas multi-etapas sem checkpoints, testes superficiais, falhas silenciosas mascaradas de sucesso. São patches incrementais.

Claro, os efeitos variam. Se você não faz pipelines de múltiplos passos, a regra 10 é menos relevante. Se seu repositório tem estilo único e já é validado por lint, a regra 11 é redundante. Após ler as 12, mantenha as que realmente evitam seus erros, descarte o resto.

Uma versão de 6 regras, focada em falhas reais, vale mais que uma de 12 com metade inútil.

Conclusão

A tweet de janeiro de 2026 de Karpathy foi uma reclamação. Forrest Chang transformou em 4 regras. Hoje, 120 mil devs deram estrelas. A maioria ainda usa só essas 4.

O modelo evoluiu, o ecossistema mudou. Múltiplos passos, gatilhos, habilidades, colaboração — tudo isso não existia na época do tweet. As regras originais não cobrem esses cenários. Não estão erradas, estão incompletas.

Adicione as 8 regras, teste com 30 repositórios em 6 semanas, erro de 41% caiu para 3%.

Salve este artigo hoje, cole as 12 regras no seu CLAUDE.md. Se ajudar a evitar uma semana de erro, compartilhe.

[Link para o original]

Clique para saber mais sobre as vagas na律动BlockBeats

Participe do grupo oficial da律动BlockBeats:

Telegram: https://t.me/theblockbeats

Telegram: https://t.me/BlockBeats_App

Twitter: https://twitter.com/BlockBeatsAsia