1 Arquivo Que Muda Como Sua Equipe Usa IA Para Codar
Andrej Karpathy — ex-diretor de IA da Tesla, co-fundador da OpenAI, o cara que ensinou milhões de devs a entender redes neurais — passou semanas codando intensamente com Claude Code no começo de 2026.
E saiu frustrado.
Não porque a IA fosse ruim. Mas porque ela cometia 3 erros sistemáticos que transformavam cada tarefa simples numa sessão de arqueologia de código. Você pede pra mudar uma linha e recebe um diff de 200. Pede pra corrigir um bug e ela reescreve metade da classe. Pede algo ambíguo e ela assume a resposta errada sem perguntar.
Um desenvolvedor chamado Jiayuan Zhang pegou essas observações e criou algo ridiculamente simples: um arquivo de texto. Um CLAUDE.md com 4 regras. E esse arquivo tem 9.100+ stars no GitHub e está crescendo centenas por dia.
Se a sua equipe usa IA pra codar — e em 2026, quem não usa? — você precisa entender o que está nesse arquivo.
O que o Karpathy descobriu de errado
Em janeiro de 2026, Karpathy postou algo que viralizou:
“Given the latest lift in LLM coding capability, like many others I rapidly went from about 80% manual+autocomplete coding and 20% agents in November to 80% agent coding and 20% edits+touchups.”
Mas junto com essa mudança, veio a frustração. Ele identificou 3 padrões de erro que todo LLM de código repete:
1. Assume sem perguntar. Você dá uma instrução ambígua e o modelo escolhe uma interpretação sozinho, sem dizer qual. Não pede esclarecimento, não mostra alternativas, não sinaliza que está confuso. Simplesmente sai implementando na direção errada.
2. Overcomplica tudo. Pede uma função? Recebe uma classe abstrata com factory pattern, 4 níveis de herança, e 1.000 linhas onde 100 resolviam. O modelo adora criar “flexibilidade” que ninguém pediu.
3. Mexe no que não devia. Você pede pra corrigir um if/else e a IA aproveita pra renomear variáveis, deletar comentários, reformatar código adjacente, e “melhorar” coisas que estavam funcionando. O diff vira uma baguça impossível de revisar.
Na minha experiência com 300+ software houses, esses 3 problemas são exatamente o que faz CEOs desconfiarem de IA no código. Não é a IA que é o problema — é a falta de regras claras.
Os 4 princípios que resolvem
O andrej-karpathy-skills transforma as observações do Karpathy em 4 princípios acionáveis, escritos num arquivo CLAUDE.md que o Claude Code lê automaticamente:
1. Think Before Coding
Antes de escrever qualquer linha, o modelo deve:
- Declarar explicitamente suas suposições
- Apresentar múltiplas interpretações quando há ambiguidade
- Empurrar de volta quando existe uma abordagem mais simples
- Perguntar em vez de adivinhar
Parece óbvio? Pois sem essa instrução, o modelo NUNCA faz isso. Ele sempre assume.
2. Simplicity First
A regra é: escreva o código mínimo que resolve o problema pedido. Zero features especulativas. Zero abstrações pra “futuro”. Zero tratamento de erro pra cenários impossíveis.
O teste: “Um engenheiro sênior acharia isso overcomplicado?” Se a resposta é sim, simplifique.
3. Surgical Changes
Quando editando código existente:
- Não “melhore” código adjacente não relacionado
- Não refatore código que está funcionando
- Siga o estilo que já existe no projeto
- Cada linha mudada deve rastrear diretamente ao que o usuário pediu
Quando suas mudanças criam itens não utilizados, remova-os. Mas não saia deletando dead code pré-existente que não tem a ver com a tarefa.
4. Goal-Driven Execution
Esse é o insight mais poderoso. Em vez de dar instruções imperativas (“corrija o bug”), transforme em critérios de sucesso verificáveis:
- “Adicione validação” → “Escreva testes para inputs inválidos, depois passe neles”
- “Corrija o bug” → “Escreva teste que reproduz, depois corrija”
- “Refatore X” → “Garanta que testes passam antes e depois”
Como Karpathy observou: “LLMs are exceptionally good at looping until they meet specific goals.” Não diga o que fazer — dê o critério de sucesso e deixe o modelo iterar.
Como instalar em 30 segundos
Tem duas formas:
Via Plugin Marketplace (recomendado):
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skillsVia curl (qualquer projeto):
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.mdSe já tem um CLAUDE.md no projeto, só append:
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.mdPronto. Na próxima sessão de Claude Code, o comportamento muda.
O que muda na prática da sua software house
Vou ser direto com 5 cenários reais:
1. Diffs menores nas PRs
O princípio “Surgical Changes” sozinho já corta o tamanho médio dos diffs. Menos código mexido = menos risco, review mais rápido, deploy mais seguro. Se sua equipe faz code review (e deveria), isso economiza horas por semana.
2. Onboarding mais rápido
Dev novo entrou? Copia o CLAUDE.md pro projeto. Ele já começa escrevendo código no padrão da equipe, sem precisar de 3 semanas absorvendo convenções. As regras estão no arquivo — e o Claude segue.
3. Menos retrabalho
Na minha experiência, o maior desperdício quando equipes usam IA é o ciclo “gera → revisa → joga fora → regera”. As regras do Karpathy atacam a raiz desse ciclo: o modelo para de inventar e passa a perguntar.
4. Combina com tudo
O CLAUDE.md é aditivo. Você pode ter suas regras específicas de projeto (stack, patterns, convenções) E os princípios do Karpathy no mesmo arquivo. Eles se complementam.
5. Argumento de vendas
“Nossa equipe usa guidelines de coding com IA validadas pelo Andrej Karpathy.” Num mercado onde software house compete por credibilidade técnica, isso conta.
Quem criou e por que importa
O repositório foi criado por Jiayuan Zhang (@forrestchang), fundador e CEO da Multica — uma startup focada em “AI agents as team members.”
Zhang não é um dev qualquer. Ele criou o devv.ai (search engine para devs, 1.5K stars), o readpilot (análise de artigos com IA, 1.1K stars), e até uma linguagem de programação implementada pelo GPT-4 chamada gptlang.
O cara claramente entende a interseção entre IA e developer experience. E o fato de ter transformado um tweet do Karpathy num plugin instalável mostra a diferença entre consumir conteúdo e criar ferramentas.
Minha opinião sincera
Vou te falar o que penso: esse é o tipo de projeto que parece bobo demais pra funcionar. “Um arquivo de texto com 4 regras? Sério?”
Sim. Sério.
Porque o problema nunca foi a capacidade do modelo. O Karpathy deixou isso claro. O modelo SABE escrever código limpo. Ele só não faz porque ninguém mandou. É como contratar um desenvolvedor brilhante e não dar contexto nenhum sobre o projeto — ele vai produzir, mas vai produzir errado.
O CLAUDE.md é o contexto. São as regras do jogo. E quando você define regras claras, o resultado muda dramaticamente.
Eu vejo muita SH investindo em ferramentas caras, treinamentos complexos, e processos burocráticos pra “controlar a qualidade do código gerado por IA.” E a solução mais efetiva que vi até agora custa zero reais e leva 30 segundos pra instalar.
9.100 stars em 2 meses. 634 forks. E crescendo. Tem um motivo.
Conclusão
O Andrej Karpathy mudou de 20% pra 80% de coding com agentes em dois meses. E quando encontrou os problemas, documentou. Um desenvolvedor pegou essa documentação e criou uma ferramenta.
Isso é o ecossistema open-source funcionando no seu melhor: um dos maiores nomes de IA do mundo identifica o problema, a comunidade constrói a solução, e todo mundo se beneficia.
Se você tem uma equipe usando Claude Code (ou qualquer AI coding tool), instala esse CLAUDE.md hoje. Não custa nada, não quebra nada, e os resultados aparecem no primeiro diff.
Sou Thulio, mentoro 300+ SHs desde 2016.
Links:
