Nota do editor: Em janeiro de 2026, as críticas de Andrej Karpathy sobre o Claude escrever código trouxeram à tona um arquivo aparentemente pequeno, mas extremamente crucial no fluxo de trabalho de programação com IA: o CLAUDE.md. Forrest Chang posteriormente organizou esses problemas em quatro regras de comportamento, tentando limitar os erros comuns do Claude na programação: suposições silenciosas, superengenharia, danos a código não relacionado e falta de critérios claros de sucesso.

Mas alguns meses depois, os cenários de uso do Claude Code já não se limitam mais a “fazer o modelo escrever um trecho de código”. Com agentes de múltiplos passos, gatilhos em cadeia de hook, carregamento de habilidades e colaboração entre múltiplos repositórios de código tornando-se comuns, novos modos de falha também começaram a surgir: o modelo perde o controle em tarefas longas, os testes passam sem validar a lógica real, a migração é concluída mas erros são ignorados silenciosamente, e estilos de código diferentes são incorretamente misturados.

O autor deste artigo testou 30 repositórios em seis semanas e adicionou oito novas regras às quatro originais de Karpathy, tentando abordar os novos desafios surgidos com a transição da programação por IA de complementações únicas para colaboração baseada em agentes.

A seguir está o texto original:

Na última semana de janeiro de 2026, Andrej Karpathy publicou uma sequência de tweets reclamando sobre a maneira como o Claude escreve código. Ele apontou três tipos típicos de problemas: fazer suposições erradas sem explicação, tornar as coisas excessivamente complexas e causar danos irrelevantes a código que não deveria ser alterado.

Forrest Chang viu esta thread no Twitter, organizou as reclamações em 4 regras de comportamento, escreveu-as em um arquivo separado chamado CLAUDE.md e publicou no GitHub. O projeto recebeu 5.828 stars no primeiro dia, foi salvo 60.000 vezes em duas semanas e agora possui 120.000 stars, tornando-se o repositório de código de único arquivo com o crescimento mais rápido de 2026.

Em seguida, testei-o em 30 repositórios ao longo de 6 semanas.

Essas 4 regras realmente funcionam. O erro, que anteriormente ocorria em cerca de 40% dos casos, caiu para menos de 3% em tarefas adequadas para essas regras terem efeito. Mas o problema é que esse modelo foi originalmente criado para resolver erros que ocorriam quando o Claude escrevia código em janeiro.

Em maio de 2026, os problemas enfrentados pelo ecossistema Claude Code eram diferentes: conflitos entre agentes, gatilhos em cadeia de hooks, conflitos de carregamento de skills e interrupções de fluxos de trabalho multietapas entre sessões.

Então, adicionei mais 8 regras. Aqui está a versão completa de 12 regras do CLAUDE.md: por que cada uma vale a pena ser incluída e em quais 4 lugares o modelo original de Karpathy falha silenciosamente.

Se quiser pular a explicação e copiar diretamente para uso, o arquivo completo está no final.

Por que isso é importante

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

Primeiro, trate-o como uma lixeira de preferências, encha-o com todos os seus hábitos e, por fim, expanda-o para mais de 4.000 tokens, fazendo com que a taxa de adesão às regras caia para 30%.

Em segundo lugar, simplesmente não usar e sempre recriar o prompt. Isso causará um desperdício de 5 vezes os tokens e falta de consistência entre sessões.

Terceiro, copiar um modelo e nunca mais se preocupar com ele. Pode funcionar por duas semanas, mas, à medida que o repositório de código muda, ele pode deixar de funcionar sem que você perceba.

A documentação oficial da Anthropic deixa claro: o CLAUDE.md é meramente sugestivo. O Claude segue-o em aproximadamente 80% do tempo. Após 200 linhas, a taxa de aderência diminui significativamente, pois as regras importantes são sufocadas pelo ruído.

O modelo de Karpathy resolve esse problema: um arquivo, 65 linhas, 4 regras. Este é o mínimo básico.

Mas o limite ainda pode ser maior. Após adicionar estas 8 regras adicionais, ele não cobre mais apenas os problemas de escrita de código reclamados por Karpathy em janeiro de 2026, mas também os problemas de orquestração de Agentes que surgiram apenas em maio de 2026 — problemas que não existiam quando o modelo original foi escrito.

As 4 regras originais

Se você ainda não viu o repositório de Forrest Chang, veja primeiro esta versão básica:

Regra 1: Pense antes de codificar.

Não faça suposições silenciosamente. Declare suas suposições e exponha os pontos de compromisso. Faça perguntas antes de adivinhar. Quando houver uma solução mais simples, levante objeções ativamente.

Regra 2: Priorize a simplicidade.
Use o mínimo de código necessário para resolver o problema. Não adicione funcionalidades imaginárias. Não crie camadas de abstração para código de uso único. Se um engenheiro sênior considerar isso excessivamente complexo, simplifique.

Regra 3: Modificações cirúrgicas.
Mude apenas o que for necessário. Não "otimize" acidentalmente código, comentários ou formato adjacentes. Não refatore coisas que não estão quebradas. Mantenha a consistência com o estilo existente.

Regra 4: Execute com foco no objetivo.
Defina os critérios de sucesso primeiro, depois itere em ciclos até a verificação ser concluída. Não diga ao Claude como fazer cada passo, mas sim o que o resultado de sucesso deve parecer, permitindo que ele itere por conta própria.

Essas 4 regras resolvem cerca de 40% dos padrões de falha que vejo em sessões do Claude Code sem supervisão. Os restantes 60% dos problemas estão escondidos nestes espaços em branco.

I added 8 new rules, and why

Cada regra vem de um momento real: as quatro regras originais de Karpathy já não são suficientes. A seguir, explicarei primeiro o cenário e depois apresentarei a regra correspondente.

As regras de Karpathy não cobrem esse ponto. Assim, o modelo passou a decidir questões que deveriam ser tratadas por código determinístico: se deve tentar novamente uma chamada de API, como rotear uma mensagem e quando atualizar o processamento. O resultado é que os julgamentos semanais são diferentes. Você acaba com um if-else instável, cobrado a US$ 0,003 por token.

Naquele momento, havia um código que chamava o Claude para "decidir se deveria tentar novamente ao encontrar um 503". Inicialmente, funcionava bem por duas semanas, mas depois tornou-se instável, pois o modelo passou a considerar o corpo da requisição como parte do contexto de julgamento. A estratégia de repetição tornou-se aleatória, pois o prompt em si era aleatório.

Sem restrições de orçamento, o CLAUDE.md equivale a um cheque em branco. Cada ciclo pode sair do controle e se tornar um vazamento de 50.000 tokens. O modelo não se parará sozinho.

Naquele momento, uma sessão de depuração durou 90 minutos. O modelo estava constantemente iterando sobre a mesma mensagem de erro de 8 KB e gradualmente esquecendo quais soluções já havia tentado. No final, começou a propor soluções que eu já havia rejeitado 40 mensagens antes. Se houvesse um orçamento de tokens, esse processo deveria ter sido interrompido aos 12 minutos.

Quando duas partes do repositório de código se contradizem, o Claude tenta agradar ambas, resultando em um código confuso e incoerente.

Naquele momento, havia dois modelos de tratamento de erros no repositório de código: um usando async/await com try/catch explícito e outro usando fronteiras globais de erro. O novo código escrito pelo Claude usou ambos. Como resultado, o tratamento de erros foi feito duas vezes. Levei 30 minutos para entender por que os erros foram ignorados duas vezes.

A "modificação cirúrgica" de Karpathy instruiu o Claude a não alterar o código adjacente. Mas não disse ao Claude: primeiro, entenda o código adjacente. Sem isso, o Claude escreverá novo código que entra em conflito com o código existente a 30 linhas de distância.

Naquele momento, Claude adicionou uma nova função idêntica ao lado de uma função já existente, pois não leu primeiro a função original. Ambas as funções realizam a mesma tarefa. No entanto, devido à ordem de importação, a nova função substituiu a antiga, que já havia sido o padrão de fato por seis meses.

A abordagem de "execução orientada por objetivos" de Karpathy sugere que os testes podem servir como critério de sucesso. Mas na prática, o Claude trata "passar nos testes" como o único objetivo, resultando em código que passa em testes superficiais, mas quebra outras partes.

Naquele momento, o Claude escreveu 12 testes para uma função de autenticação, todos aprovados. Mas a lógica de autenticação em produção estava quebrada. Esses testes apenas verificavam se a função "retornava algo", e não se retornava a coisa correta. A função passava nos testes porque retornava uma constante.

O modelo do Karpathy tem interação padrão única. Mas o trabalho real do Claude Code geralmente é multifasado: refatorar em 20 arquivos, construir funcionalidades em uma única sessão, depurar em vários commits. Sem pontos de verificação, um único erro pode fazer com que todo o progresso anterior seja perdido.

Naquele momento, uma tarefa de reestruturação de 6 passos errou no passo 4. Quando percebi, o Claude já havia continuado e concluído os passos 5 e 6 com base no estado incorreto. O tempo gasto para desmontar e corrigir foi maior do que o necessário para refazer toda a tarefa. Se houvesse pontos de verificação, o erro teria sido detectado já no passo 4.

Em um repositório de código com um modelo já estabelecido, o Claude gosta de introduzir sua própria abordagem. Mesmo que sua abordagem seja “melhor”, introduzir um segundo modelo é pior do que qualquer modelo único.

Naquele momento, o Claude introduziu hooks em um código base React baseado em componentes de classe. Funcionava, mas quebrou o padrão de teste existente, pois os testes dependiam do componentDidMount. Levou meio dia para removê-lo e reescrevê-lo.

O fracasso mais caro do Claude é frequentemente aquele que parece um sucesso. Uma função "funciona", mas retorna dados incorretos; uma migração "foi concluída", mas ignorou 30 registros; um teste "passou", mas apenas porque a afirmação em si estava errada.

Naquele momento, Claude disse que a migração do banco de dados foi "concluída com sucesso". Na realidade, ela silenciosamente ignorou 14% dos registros que causavam conflitos com restrições de gatilho. O comportamento de ignorar foi registrado nos logs, mas não foi explicitamente revelado. Onze dias depois, quando os dados dos relatórios começaram a apresentar anomalias, percebemos o problema.

Ao longo de 6 semanas, rastreei o mesmo conjunto de 50 tarefas representativas, cobrindo 30 repositórios de código, testando três configurações.

A taxa de erro refere-se a: tarefas que precisam ser corrigidas ou reescritas para corresponder à intenção original. Os erros contabilizados incluem: suposições silenciosas erradas, superengenharia, destruição irrelevante, falhas silenciosas, violação de convenções, compromissos conflitantes e pontos de verificação omitidos.

A taxa de conformidade refere-se à probabilidade de o Claude aplicar explicitamente uma regra quando ela for aplicável.

O resultado verdadeiramente interessante não é apenas a redução da taxa de erro de 41% para 3%. Mais importante ainda, ao expandir de 4 regras para 12 regras, a carga de conformidade aumentou quase nada, com a taxa de conformidade caindo apenas de 78% para 76%, enquanto a taxa de erro diminuiu mais 8 pontos percentuais. As novas regras abrangem modos de falha não tratados pelas 4 regras originais e não competem pelo mesmo orçamento de atenção.

Onde o modelo Karpathy falhará silenciosamente

Mesmo sem adicionar novas regras, os 4 modelos de regras originais são insuficientes em pelo menos 4 locais.

Primeiro, tarefas de agente de longa duração.
As regras de Karpathy são voltadas principalmente para o momento em que o Claude está escrevendo código. Mas o que acontece quando o Claude executa um pipeline com múltiplos passos? O modelo original não possui regras de orçamento, regras de checkpoint nem regras de "falhar alto". Assim, o pipeline gradualmente se desvia.

Em segundo lugar, consistência entre múltiplos repositórios de código.
“Corresponder ao estilo existente” padrãomente possui apenas um estilo. Mas em um monorepo com 12 serviços, o Claude precisa escolher qual estilo corresponder. A regra original não diz a ele como escolher. Assim, ele ou escolhe aleatoriamente ou mistura os vários estilos uniformemente.

Terceiro, qualidade do teste.
“Executar com foco no objetivo” considera “passar no teste” como sucesso, mas não especifica que o teste em si deve ser significativo. O resultado é que o Claude escreve testes que verificam quase nada, mas que o fazem acreditar que está confiante.

Quarto, a diferença entre o ambiente de produção e a fase de protótipo.
As mesmas 4 regras podem evitar que o código de produção seja excessivamente engenhado, mas também podem retardar o desenvolvimento de protótipos, pois, às vezes, a fase de protótipo realmente exige 100 linhas de estrutura exploratória para definir a direção. A abordagem "simplicidade primeiro" de Karpathy tende a ser excessivamente ativada no código inicial.

Essas 8 novas regras não substituem as 4 regras originais de Karpathy, mas preenchem suas lacunas: o modelo original era adequado para cenários de escrita de código com preenchimento automático, como em janeiro de 2026; já em maio de 2026, o Claude Code entrou em um ambiente impulsionado por Agentes, com múltiplos passos e colaboração entre vários repositórios de código, enfrentando problemas diferentes.

Quais métodos não funcionaram?

Antes de finalizar estas 12 regras, também experimentei outras abordagens.

Adicione as regras que vi no Reddit / X.
A maioria deles simplesmente repetia as quatro regras originais de Karpathy com diferentes palavras, ou eram regras específicas de domínio que não podiam ser generalizadas, como "sempre use classes do Tailwind". Todas foram removidas.

Mais de 12 regras.
Eu testei no máximo 18 regras. Após 14 regras, a taxa de conformidade caiu de 76% para 52%. O limite de 200 linhas é real. Após esse comprimento, o Claude começa a fazer correspondência de padrões como "aqui há regras", em vez de ler realmente cada regra.

Regras que dependem da existência de certas ferramentas.
Por exemplo, “sempre use eslint” — se o projeto não tiver eslint instalado, essa regra falhará silenciosamente. Mais tarde, alterei para uma expressão que não depende de ferramentas específicas, como trocar “use eslint” por “sigam o estilo já obrigatório no repositório”.

No CLAUDE.md, mostre exemplos, não regras.
Exemplos ocupam mais contexto do que regras. Três exemplos consomem aproximadamente o mesmo contexto de 10 regras, e o Claude facilmente se sobrecarrega com exemplos. As regras são abstratas; os exemplos são concretos. Portanto, deve-se usar regras.

Tenha cuidado. Pense com atenção. Fique focado.
Esses são todos ruídos. A taxa de adesão a esse tipo de instrução caiu para cerca de 30%, pois não podem ser verificadas. Mais tarde, substituí-os por regras imperativas mais específicas, como "esclareça as suposições".

Diga ao Claude para agir como um "engenheiro sênior".
Isso não funciona. O Claude já se considera um engenheiro sênior. A questão real não é se ele acha isso, mas se ele age assim. Regras imperativas podem reduzir essa lacuna; prompts de identidade não conseguem.

Versão completa de 12 regras do CLAUDE.md

Aqui está a versão completa pronta para copiar e colar.

Este conteúdo não pode ser exibido fora do documento do Feishu temporariamente

Salve-o como CLAUDE.md no diretório raiz do repositório. Abaixo dessas 12 regras, adicione regras específicas do projeto, como stack técnica, comandos de teste, padrões de erro etc. O conjunto total não deve ultrapassar 200 linhas, pois após isso, a adesão às regras diminui significativamente.

Como instalar

Basta 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–12 deste artigo abaixo

Salve o arquivo na raiz do repositório. Os >> são importantes, pois servem para adicionar ao CLAUDE.md existente, em vez de substituir as regras específicas do projeto que você já escreveu.

CLAUDE.md não é uma lista de desejos, mas um contrato de comportamento destinado a bloquear padrões de falha específicos que você já observou.

Cada regra deve responder a uma pergunta: ela impede qual erro?

As 4 regras de Karpathy visam prevenir os padrões de falha que ele viu em janeiro de 2026: suposições silenciosas, engenharia excessiva, destruição irrelevante e critérios de sucesso fracos. Elas são fundamentais; não pulem.

As 8 novas regras que adicionei visam prevenir novos modos de falha que surgirão após maio de 2026: ciclos de Agentes sem restrição orçamentária, tarefas multipassos sem pontos de verificação, testes que parecem ter sido realizados mas não cobrem a lógica crítica, e a disfarce de falhas silenciosas como sucessos silenciosos. Elas são correções incrementais.

Claro, os efeitos variam de pessoa para pessoa. Se você não executar um pipeline de múltiplos passos, a regra 10 não é tão importante para você. Se o seu repositório de código tiver apenas um estilo uniforme, já aplicado por um linter, a regra 11 é redundante. Após ler estas 12 regras, mantenha apenas aquelas que realmente correspondem a erros que você já cometeu e remova o restante.

Uma versão de 6 regras do CLAUDE.md personalizada para modos de falha reais supera uma versão com 12 regras, das quais 6 você nunca usará.

Conclusão

O tweet de Karpathy em janeiro de 2026 era, essencialmente, uma reclamação. Forrest Chang transformou-o em 4 regras. No final, 120 mil desenvolvedores deram Star a esse resultado. E a maioria deles, hoje ainda usa apenas essas 4 regras.

Os modelos evoluíram e o ecossistema mudou. Agentes com múltiplos passos, gatilhos em cadeia com hook, carregamento de habilidades, colaboração entre múltiplos repositórios de código — tudo isso não existia quando Karpathy escreveu aquele tweet. As quatro regras originais não resolvem esses problemas. Elas não estão erradas, mas são incompletas.

Adicionadas 8 novas regras. 6 semanas de teste cobrindo 30 repositórios de código. A taxa de erro caiu de 41% para 3%.

Salve este artigo para hoje à noite e cole estas 12 regras no seu CLAUDE.md. Se ele o ajudar a economizar uma semana de aprendizado com o Claude, compartilhe.