andrej-karpathy-skills: O Arquivo CLAUDE.md que Virou Plugin Viral
Se você passou tempo com Claude Code, provavelmente já esbarrou na parede que Andrej Karpathy descreveu publicamente: o modelo faz suposições sem perguntar, transforma uma solução de 50 linhas em 400, ou reescreve metade do seu codebase quando você pediu para arreglar uma única função.
Karpathy foi direto: os LLMs fazem suposições incorretas em seu nome e seguem adiante sem verificar. Não gerenciam sua confusão, não pedem esclarecimentos, não apresentam tradeoffs, não reclamam quando deveriam. E adoram complicar o código: abstrações desnecessárias, dead code acumulado, 1000 linhas onde 100 teriam sido suficientes.
Isso não são bugs reportáveis — são reclamações estruturais sobre como os LLMs abordam código por padrão. Forrest Chang pegou essas observações e fez algo enganosamente simples: converteu-as em um CLAUDE.md. Esse arquivo tem hoje mais de 15.000 estrelas no GitHub.
O que faz exatamente
O plugin andrej-karpathy-skills é um único CLAUDE.md com quatro princípios de comportamento:
1. Think Before Coding — Pense antes de codificar
Antes de escrever uma única linha, Claude deve declarar suas suposições explicitamente. Se existem múltiplas interpretações de uma tarefa, deve surfaceá-las — não escolher uma silenciosamente e sair correndo. Se algo não está claro, deve parar, nomear o que é confuso e perguntar.
2. Simplicity First — O mínimo que resolve o problema
Sem features além do pedido. Sem abstrações para código de uso único. Sem “flexibilidade” ou “configurabilidade” que ninguém solicitou. Sem tratamento de erros para cenários impossíveis. Se escreveu 200 linhas e poderiam ser 50, reescreve. O arquivo inclui até um autocheck: “Um senior engineer diria que isso é muito complicado? Se a resposta é sim, simplifique.”
3. Surgical Changes — Toque apenas o que precisa tocar
Ao editar código existente: não “melhorar” código adjacente, comentários ou formatação. Não refatorar coisas que não estão quebradas. Respeitar o estilo existente mesmo que você faria diferente. Se detectar dead code não relacionado, mencioná-lo — não deletar por iniciativa própria. Cada linha modificada deve rastrear-se diretamente ao pedido do usuário.
4. Goal-Driven Execution — Defina o sucesso, loop até verificar
Transformar tarefas vagas em objetivos verificáveis:
- “Adicione validação” → “Escreva testes para inputs inválidos, depois faça-os passar”
- “Corrija o bug” → “Escreva um teste que o reproduza, depois faça-o passar”
- “Refatore X” → “Garanta que os testes passem antes e depois”
Para tarefas multi-etapa, Claude deve declarar um plano breve com verificações explícitas antes de começar.
Esses quatro princípios contrapõem-se diretamente aos quatro modos de falha que Karpathy identificou: suposições silenciosas, sobrecomplicação, scope creep e critérios de sucesso vagos.
Como instalar
Opção A: via o marketplace de plugins do Claude Code (recomendada)
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
Isso instala as guias como plugin global — disponível em todos seus projetos automaticamente.
Opção B: curl direto para seu projeto
Para um novo projeto:
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
Para adicionar a um CLAUDE.md existente:
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
O arquivo foi projetado para se mesclar com as instruções específicas do seu projeto. Suas regras de negócio vão no topo; as guias de Karpathy vão ao final como camada base de comportamento.
Por que virou viral
Isso não é realmente sobre Claude Code especificamente. É sobre uma constatação cada vez mais generalizada: como você configura seu assistente de coding AI importa tanto quanto qual você escolhe.
O plugin trata os padrões do modelo como um ponto de partida a corrigir — não como comportamento fixo que você precisa contornar com prompts engenhosos sessão após sessão. E isso ressoa. O repo já gerou ports para Cursor (.cursorrules) e VS Code Copilot (.github/copilot-instructions.md), o que diz algo mais amplo: a comunidade está convergindo em um diagnóstico compartilhado dos modos de falha de LLMs em código, independentemente de qual ferramenta usem.
CLAUDE.md, .cursorrules, e os arquivos de instruções do Copilot estão se tornando a nova camada de configuração do AI coding. E as observações de Karpathy estão funcionando como padrão de facto nessa camada.
O que torna possível esse micro-gênero — prompt engineering como projeto open source — é que CLAUDE.md é markdown puro que qualquer LLM pode ler. Isso significa que um arquivo bem construído pode ser versionado, forkado, discutido e iterado como qualquer outro projeto de código. Com estrelas, forks, pull requests e debate comunitário. Exatamente o que está acontecendo.
Vale a pena?
O próprio README é honesto sobre o tradeoff: “These guidelines bias toward caution over speed. For trivial tasks, use judgment.” Esse é o framing correto. Para um fix de uma linha, você provavelmente não precisa que o modelo pare para enumerar suposições. Mas para qualquer trabalho não trivial — qualquer coisa onde uma suposição incorreta custa uma hora revertendo mudanças — os princípios fazem sentido.
A métrica que o plugin propõe: menos mudanças desnecessárias nos diffs, menos rewrites por sobrecomplicação, perguntas de esclarecimento antes de implementar em vez de desculpas depois de errar.
Esse é um padrão razoável. E 15.000 estrelas sugerem que bastantes developers pensam que ele ultrapassa isso.
Links
Você usa CLAUDE.md em seus projetos? Tem suas próprias regras que adiciona às de Karpathy? Compartilhe seu setup nos comentários 