Título original: As 4 regras do CLAUDE de Karpathy reduzem 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, levando à descoberta de um arquivo aparentemente pequeno, mas extremamente crucial no fluxo de trabalho de programação AI: CLAUDE.md. Forrest Chang então organizou essas questões em 4 regras de comportamento, tentando limitar erros comuns do Claude ao codificar: 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 do uso do Claude Code já não se resumia 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, 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, pula silenciosamente erros após migração, estilos de código diferentes são misturados incorretamente.

Nos próximos 6 semanas, testei 30 repositórios de código e adicionei 8 regras às 4 originais de Karpathy, buscando 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 incorretas sem explicação, complexidade excessiva e danos irrelevantes ao código que não deveria ser alterado.

Forrest Chang viu esses tweets, organizou as reclamações em 4 regras de comportamento, escreveu um arquivo separado CLAUDE.md e publicou no GitHub. O projeto, no 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 código mais rápido a crescer 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 criado inicialmente para os erros que aconteciam em janeiro de 2026, 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 com 12 regras do CLAUDE.md: por que cada uma vale a pena, e onde o template original de Karpathy pode falhar silenciosamente em 4 pontos.

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

Por que isso é importante

O CLAUDE.md de 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á, o que faz o limite de tokens subir para mais de 4000, e a taxa de conformidade cair para 30%.

Segundo, simplesmente não usar, sempre recomeçando o prompt do zero. Isso gera 5 vezes mais desperdício de tokens e falta de consistência entre sessões.

Terceiro, copiar um template e nunca mais mexer nele. Pode funcionar por duas semanas, mas com o tempo, mudanças no repositório fazem-no se tornar obsoleto sem que você perceba.

A documentação oficial da Anthropic explica claramente: CLAUDE.md é apenas uma recomendação. Claude segue aproximadamente 80% das regras. Quando passa de 200 linhas, a taxa de conformidade cai visivelmente, pois 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 ainda maior. 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 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 soluções mais simples, proponha-as.

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 experiente 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 ao acaso. Não refatore sem motivo. Mantenha o estilo existente.

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

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

As 8 regras adicionais e por que

Cada regra surge de uma situação real: as 4 regras de Karpathy de janeiro de 2026 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

Claude pode lidar com classificação, rascunho, resumo, extração de informações de textos não estruturados.
Não use Claude para roteamento, tentativas, manipulação de códigos de status ou transformações determinísticas.
Se uma resposta de código de status já responde à sua dúvida, deixe o código normal responder.

Karpathy não cobria esse ponto. Assim, o modelo começou a decidir questões que deveriam ser tratadas por código determinístico: se deve tentar novamente uma API, como roteá-la, quando fazer upgrade. O resultado era uma decisão variável, com custos de 0,003 dólares por token, instável.

Por exemplo: uma rotina que decide se deve tentar novamente uma chamada API ao receber um erro 503. Funcionou bem por duas semanas, mas depois ficou instável, pois o modelo começou a incluir o corpo da requisição na decisão. A estratégia de retry virou aleatória, pois o prompt também ficou 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 estiver perto do limite, resuma o estado atual e reinicie. Não insista. Exponha claramente o limite ultrapassado, melhor do que ignorá-lo.

Sem limites, o CLAUDE.md vira uma folha em branco. Cada ciclo pode se transformar em uma troca de 50.000 tokens, sem controle. O modelo não para sozinho.

Por exemplo: uma sessão de debug de 90 minutos, com o modelo repetindo várias vezes a mesma mensagem de erro de 8KB, esquecendo o que já tentou. No final, propôs 40 soluções que já tinha rejeitado antes. Com limite de tokens, essa sessão deveria ser interrompida na 12ª minuto.

Regra 7: Exponha conflitos, não faça compromissos

Se duas abordagens no código conflitam, não tente mesclá-las. Escolha uma, preferencialmente a mais recente ou testada, explique o motivo, marque a outra para limpeza futura.
Código que tenta satisfazer duas regras ao mesmo tempo é o pior.

Quando há conflitos, Claude tenta agradar ambos, gerando código incoerente.

Por exemplo: um repositório com duas formas de tratamento de erro — uma com async/await + try/catch, outra com erro global. Claude mistura as duas, causando dupla captura de erros. Demorei 30 minutos para entender por que erros eram silenciados duas vezes.

Regra 8: Leia antes de escrever

Antes de adicionar código, leia as exportações do arquivo, os pontos de chamada direta e funções auxiliares relacionadas.
Se não entender a organização atual, pergunte antes de acrescentar.
“Para mim, isso não é relevante” é uma frase perigosa nesse contexto.

O “cirurgião” de Karpathy orienta Claude a não alterar código adjacente, mas não ensina a entender esse código antes. Sem essa leitura, Claude pode criar funções conflitantes com as existentes.

Por exemplo: Claude adicionou uma função idêntica ao lado de uma já existente, sem ler a original. Ambas fazem a mesma coisa, mas por causa da ordem de importação, a nova sobrescreveu a antiga, que já era padrão há meses.

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

Cada teste deve explicar “por que esse comportamento importa”, 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” sugere que testes são critérios de sucesso. Mas, na prática, Claude muitas vezes vê “passou no teste” como o único objetivo, criando código que passa testes superficiais, mas destrói lógica importante.

Por exemplo: Claude escreveu 12 testes para uma função de autenticação, todos passando, mas a lógica no ambiente de produção estava quebrada. Os testes só verificavam se a função retornava algo, não se era o valor correto. A função passava porque retornava um valor 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, o que falta.
Não continue de um estado que você não consegue explicar. Se estiver perdido, pare e reavalie.

O template de Karpathy assume interação única. Na prática, Claude trabalha em múltiplas etapas: refatorações em 20 arquivos, construção de funcionalidades em uma sessão, depuração em vários commits. Sem checkpoints, um erro em uma etapa pode invalidar todo o progresso anterior.

Por exemplo: uma refatoração de 6 passos falhou na quarta. Quando percebi, Claude já tinha feito o quinto e o sexto, com erro. Reparar leva mais tempo do que refazer tudo. Com checkpoints, o erro na quarta 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 projeto, a consistência é prioridade.
Se acha que uma convenção é ruim, proponha mudança, não crie ramificações silenciosas.

Claude tende a introduzir seu próprio estilo em repositórios já estabelecidos. Mesmo que seja “melhor”, criar uma segunda abordagem é pior do que manter uma única.

Por exemplo: Claude introduziu hooks em um projeto React baseado em classes. Funciona, mas quebrou testes que dependiam de componentDidMount. Demorei horas para remover e reescrever.

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

Se não tiver certeza de que algo funcionou, diga claramente.
Se 30 registros foram ignorados silenciosamente, não diga “migração concluída”.
Se você pulou testes, não diga “funcionalidade OK”.
Se não verificou limites, não diga “funciona”.
Exponha a incerteza, não 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 pulou 14% das entradas com conflitos; um teste “passou”, mas por erro na asserção.

Por exemplo: Claude afirmou que a migração do banco de dados terminou com sucesso, mas na verdade ignorou silenciosamente 14% das entradas que violavam restrições. O problema só foi descoberto 11 dias depois, quando os relatórios começaram a mostrar inconsistências.

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 indica 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 que, ao expandir de 4 para 12 regras, a conformidade caiu de 78% para 76%, enquanto o erro caiu 8 pontos percentuais. As novas regras cobrem falhas que as 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 longo prazo.
As regras de Karpathy focam no momento de escrever código. Mas, ao rodar um pipeline multi-etapas, 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. Assim, ele pode escolher aleatoriamente ou misturar estilos, gerando incoerência.

Terceiro, qualidade dos testes.
“Executar com foco no objetivo” trata “passou no teste” como sucesso, mas não exige que o teste seja relevante. Assim, Claude pode criar testes que quase não verificam nada, levando a 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 atrapalham protótipos que precisam de exploração rápida. A regra de simplicidade, por exemplo, pode ser acionada demais na fase inicial.

Essas 8 regras adicionais não substituem as originais de Karpathy, mas as complementam: enquanto as primeiras eram voltadas para o cenário de preenchimento automático de janeiro de 2026, as novas lidam com ambientes orquestrados por agentes, multi-etapas e múltiplos repositórios, que só surgiram depois.

Métodos que não funcionaram

Antes de consolidar as 12 regras, tentei outras abordagens.

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

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 tem regra” ao invés de ler cada uma.

Dependência de ferramentas específicas.
Exemplo: “sempre usar eslint”. Se o projeto não usa eslint, a regra falha silenciosamente. Substituí por “seguir o estilo já imposto na base de código”.

Incluir exemplos no CLAUDE.md ao invés de regras.
Exemplos ocupam mais espaço de contexto do que regras, e o Claude tende a fazer overfitting a eles. Regras são mais abstratas e seguras.

Frases como “Tenha cuidado”, “Pense com atenção”, “Seja mais sério”.
Têm baixa conformidade (~30%) por serem vagas. Substituí por comandos mais específicos, como “Explique claramente suas hipóteses”.

Mandar Claude agir como “Engenheiro Sênior”.
Inútil. Claude já se acha assim. O que importa é como ela age, não como ela se vê. Comandos específicos ajudam, identidade não.

Versão completa das 12 regras do CLAUDE.md

A seguir, a versão pronta para copiar e usar.

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

Salve como CLAUDE.md na raiz do repositório. Acrescente regras específicas do projeto abaixo, como stack, comandos de teste, padrões de erro. Não ultrapasse 200 linhas, ou a conformidade cai.

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: “Que erro ela evita?”

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 o mínimo.

As 8 regras adicionais evitam falhas que surgiram após maio de 2026: ciclos de agente sem limite de orçamento, tarefas multi-etapas sem checkpoints, testes superficiais, falhas silenciosas mascaradas de sucesso. São patches incrementais.

Claro, o efeito varia. Se você não roda pipelines multi-etapas, 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 fazem sentido para você, descarte o resto.

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

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 nesse resultado, e a maioria ainda usa só essas 4.

O modelo evoluiu, o ecossistema mudou. Múltiplos passos, gatilhos, habilidades, colaboração entre repositórios — 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 extras. Em 6 semanas, testei 30 repositórios. O erro caiu de 41% para 3%.

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

[Link do artigo original]

Clique para saber mais sobre as vagas na BlockBeats

Participe do grupo oficial da BlockBeats no Telegram:
https://t.me/theblockbeats

Grupo de discussão no Telegram:
https://t.me/BlockBeats_App

Conta oficial no Twitter:
https://twitter.com/BlockBeatsAsia