Um arquivo CLAUDE.md supostamente usado por Andrej Karpathy está circulando nas comunidades de desenvolvedores. A primeira linha já define o tom:
Estas não são sugestões. São regras. Siga-as, e o código que você produzirá não precisará ser reescrito. Ignore-as, e seu código pode parecer impressionante — e quebrar em produção.
Parece um veterano experiente de mil post-mortems de dívida técnica dando bronca em um contratado novo. Só que o contratado novo não é humano. O documento foi escrito para o Claude Code.
Para quem não conhece: o CLAUDE.md é o arquivo de instruções de nível de projeto da Anthropic para o Claude Code e editores integrados ao Claude. Basta colocá-lo na raiz do projeto e o Claude o lê automaticamente ao trabalhar. Você diz a ele “este projeto usa React, prefere fetch em vez de axios, prefere function components”, e ele lembra. A versão que circulou sob o nome de Karpathy se espalhou em parte pela fama dele — mas principalmente porque faz algo que muitos desenvolvedores sentiram vagamente e nunca souberam expressar sistematicamente: ela transforma as falas sistêmicas da geração de código por LLMs em um manual de diagnóstico com um plano de governança de processos correspondente.
O Problema Central: O Modelo Não Se Considera Parte do Time
A maioria dos desenvolvedores faz pair programming com IA todos os dias, e o que realmente machuca não é a incapacidade da IA de escrever código. É que o código que ela escreve é sempre meio torto de algum jeito. Sintaticamente correto. Logicamente correto. E, ainda assim, inserido no seu projeto, sutilmente errado de uma forma que você percebe antes de conseguir nomear.
O documento identifica a origem desse erro com precisão: quando um LLM escreve código, ele está fazendo correspondência de padrões — recuperando os fragmentos dos dados de treinamento mais próximos da requisição atual e gerando a partir deles. Ele não leu o seu codebase primeiro. Isso é fundamental. Um desenvolvedor humano que herda um projeto começa lendo o código, estudando a estrutura de arquivos, absorvendo os padrões existentes. A única passagem de inferência do LLM não contém nenhuma etapa de “escanear o repositório”. Por isso você vê os sintomas clássicos: axios introduzido em um codebase que usa só fetch; variáveis em camelCase em um projeto em snake_case; um padrão decorator em um codebase que nunca usou um. Os dados de treinamento estão cheios desses padrões, e a entrada atual simplesmente os disparou.
A primeira regra do documento — antes de escrever qualquer código, leia os arquivos que você está prestes a modificar — ataca exatamente essa causa raiz. Não está ensinando o modelo a ler; está forçando que “carregar o contexto do codebase” seja o passo um de toda escrita.
Cada Regra Mapeia um de Cinco Modos de Falha
Lido superficialmente, o documento é uma pilha de instruções práticas cobrindo tudo, desde ler código até escrever mensagens de commit. Por baixo, a pilha mira cinco modos sistêmicos de falha dos LLMs:
Falha um: cegueira de contexto — gerar sem ler o codebase. Sintomas: código sintaticamente válido em estilo incompatível, dependências desnecessárias, padrões copiados de projetos que não existem aqui. A regra: leia antes de escrever — verifique os imports, verifique os testes, verifique como este projeto já faz.
Falha dois: tomada de decisão invisível — adivinhar em vez de decidir em voz alta. Sintomas: o usuário diz “adicione autenticação” e o model escolhe uma abordagem em silêncio; o usuário descobre o que recebeu só depois de receber o código. A regra: declare suas suposições, declare seus tradeoffs, nunca decida em silêncio por outra pessoa.
Falha três: abstração prematura — engenharia excessiva desde o primeiro dia. Sintomas: um EmailService com padrão strategy para um produto que envia um único tipo de e-mail; uma classe base abstrata para uma única implementação. A regra: mantenha simples — escreva o código mínimo primeiro, abstraia quando a abstração for de fato merecida.
Falha quatro: viés de confirmação — verificar às cegas. Sintomas: ver um erro e gerar uma correção pelo tipo de erro sem ler a mensagem; mudar três lugares sem saber qual resolveu o bug. A regra: reproduza primeiro. Mude uma coisa por vez. Leia o stack trace. Escreva o teste antes da correção.
Falha cinco: alucinação de conhecimento — inventar o que não existe. Sintomas: uma API que nunca existiu, um parâmetro removido duas versões atrás, recursos de biblioteca que existem apenas na imaginação do modelo. A regra: diga quando não tiver certeza. Consulte a documentação. Leia o código-fonte de verdade.
Nenhuma dessas falhas é aleatória. Elas são a aparência que a arquitetura de um LLM assume ao colidir com programação: contexto limitado, raciocínio sem retrocesso, confiança descorrelacionada da precisão. O CLAUDE.md não é mágica. É uma compensação de processo desenhada após admitir honestamente esses limites.
O Framework: De Geração de Código a Desenvolvimento de Código
O aprendizado mais valioso de todo o documento não é nenhuma regra específica. É a premissa oculta: o que os LLMs de hoje carecem não é capacidade de geração de código — é a consciência de participar do desenvolvimento como membro do time. Abstraia as regras em um framework e três estágios aparecem. Estágio um: ler o código — absorver o contexto, os padrões e as restrições do projeto. Estágio dois: tomar decisões — esclarecer suposições, requisitos e tradeoffs; planejar antes de executar. Estágio três: escrever o código — mudanças mínimas, correção verificada, comunicação clara. A maioria dos desenvolvedores que usam um LLM entra direto no estágio três. O resultado é o replay interminável das falhas do estágio um: o código é escrito, e só então todo mundo descobre a biblioteca errada, o estilo errado, a solução melhor que já existia no codebase. O que o CLAUDE.md fundamentalmente tenta é converter ler → pensar → escrever — o fluxo de trabalho que todo engenheiro humano internalizou — em etapas explícitas e executáveis que o modelo roda antes de cada geração.
E funciona de forma mensurável. Um projeto comunitário, andrej-karpathy-skills no GitHub, montado a partir das reclamações públicas de Karpathy, relata a queda da taxa de erro do código do Claude de 41 para 11 por cento. Isso não é milagre — quando o modelo lê o codebase antes de escrever, a geração de código ruim realmente cai.
Onde Mais o Framework Explica o Que Você Está Vendo
A mesma análise atravessa outras ferramentas. Modo Tab versus modo Chat no Cursor: o contexto da conclusão por Tab é o arquivo atual, por isso ela se destaca em completions consistentes com o estilo; o Chat atravessa arquivos, mas sem uma instrução explícita de ler o codebase primeiro, ele se desvia. Problemas de estilo e qualidade do Copilot CLI: times que substituíram o Claude Code pelo Copilot CLI internamente descobriram que a troca raramente é por capacidade bruta — é porque as conversas de múltiplos turnos se desviam do estilo do projeto. Um arquivo de restrições de nível de projeto eliminaria boa parte desse desperdício de tokens. Por que os melhores engenheiros mantêm seu próprio CLAUDE.md: não porque conhecem alguma arte secreta de ajuste de IA, mas porque entendem que o estilo de código de um projeto é um hábito de time sedimentado e uma convenção social — algo que “código correto” não captura — e estão tornando esse conhecimento tácito explícito. Depois de internalizar o framework ler-pensar-escrever, o teto da “programação assistida por IA” fica em foco: nunca foi quão complexo um programa o LLM consegue escrever. É se o LLM consegue se pensar como parte do codebase. O CLAUDE.md é a ponte que permite que ele tente.
O Que Fazer Nesta Semana
Se você escreve código com o Claude Code: dedique trinta minutos para escrever um CLAUDE.md para o seu projeto. Não copie o de Karpathy por inteiro — use-o como um checklist. Quais bibliotecas, qual estilo, quais convenções. Você notará que a disposição do modelo de ler antes de escrever melhora imediatamente.
Se você usa outra ferramenta de codificação com IA: verifique se ela tem um mecanismo de restrição de nível de projeto. Se não tiver, adicione manualmente uma frase ao início das suas sessões: “Leia primeiro a raiz do projeto e os arquivos-fonte mais recentes, me diga quais bibliotecas e estilo este projeto usa, e então começamos a escrever código.”
Se você é um desenvolvedor independente ou líder de time: incorpore o CLAUDE.md à sua documentação de onboarding. Os problemas que ele resolve — estilo do projeto, convenções, preferências de stack — sempre deveriam viver no README ou no guia de contribuição. Ninguém lia aquilo. A IA lê. Escrever a versão destinada à máquina força você, como efeito colateral, a registrar o conhecimento que nunca documentou para humanos.
Uma passagem do documento original merece releitura:
O modo de falha atual é este: o LLM gera um pedaço de código “correto” completamente alheio ao codebase em que ele foi inserido. Ele roda. Mas parece que outra pessoa escreveu — porque outra entidade escreveu. O desenvolvedor humano agora precisa ou reescrevê-lo para adequar ao estilo do projeto, ou conviver com a inconsistência para sempre. Ambos os desfechos são ruins.
Quando uma ferramenta escreve um código 100 por cento correto e reduz a manutenibilidade do codebase em 30 por cento, ela está te ajudando ou te atrapalhando? O valor central do CLAUDE.md é mover essa questão do post-mortem para o planejamento prévio. Estas não são apenas regras para uma IA obedecer. São o manual de operação de todo o paradigma de programação assistida por IA.
Fontes: 36Kr; Synced (o artigo original em chinês); o projeto andrej-karpathy-skills no GitHub.