O CLAUDE.md de Karpathy, explicado: um arquivo por trás de uma Skills Search

No Google Trends, em todo o mundo, nos últimos sete dias e consultado em 23 de outubro de 2026, "karpathy skills" aparece como uma consulta em ascensão sob o termo semente "claude skills". Qualquer pessoa que siga essa busca chega ao mesmo lugar: github.com/multica-ai/andrej-karpathy-skills, um repositório que exibia 222.612 estrelas no GitHub, consultado em 23 de outubro de 2026. Sua descrição não contém a palavra skill de forma alguma. Ela diz: "Um único arquivo CLAUDE.md para melhorar o comportamento do Claude Code, derivado das observações de Andrej Karpathy sobre armadilhas de codificação com LLMs."

A diferença entre a consulta e o objeto não é uma pequena tecnicalidade. Uma skill e um arquivo CLAUDE.md são mecanismos diferentes que fazem trabalhos diferentes, e quase toda afirmação que as pessoas fazem sobre este repositório ou depende de saber qual dos dois é, ou assume silenciosamente o errado. A orientação lá dentro é um único arquivo. O repositório em torno desse arquivo também carrega um manifesto de plugin e uma pasta em skills, que é provavelmente de onde vem a palavra na barra de pesquisa. Separar a embalagem da carga útil é o primeiro passo útil aqui.

Os números, todos do GitHub e lidos em 23 de outubro de 2026: 222.612 estrelas, 22.321 forks, criado em 27 de janeiro de 2026, último push em 20 de abril de 2026, licença MIT. Esse último par é o interessante. O repositório não recebeu nenhum push em cerca de seis meses, e a contagem de estrelas continuou subindo mesmo assim.

O arquivo faz o trabalho; a embalagem explica o termo de busca.

Abra o repositório e a listagem de arquivos deixa a discrepância fácil de perceber. Há CLAUDE.md na raiz e, ao lado dele, CURSOR.md, EXAMPLES.md, uma pasta .cursor/rules contendo as mesmas diretrizes como uma regra de projeto do Cursor, uma pasta .claude-plugin e um diretório skills/karpathy-guidelines. A rota de instalação recomendada no README é o marketplace de plugins, e ele descreve o resultado como tornar "a habilidade disponível em todos os seus projetos".

Então o termo de pesquisa não é tanto errado quanto impreciso. Há uma pasta de skills. Há um plugin. O que não há é um conjunto de skills separadas, cada uma realizando uma tarefa diferente, que é o formato que as pessoas geralmente querem dizer com pacote de skills: uma pasta contendo um SKILL.md e quaisquer arquivos de apoio de que essa capacidade precise, invocada para uma tarefa. Aqui, toda a orientação é um único documento de instruções permanentes, e o plugin existe para entregar esse documento a um projeto.

Se essa distinção é importante para você depende do que você queria da busca. Se você procurava uma caixa de ferramentas, esta não é uma. Se você queria um pequeno manual de regras que muda o comportamento de um agente de programação em um projeto, é exatamente isso, e vale a pena entender por que alguém o escreveria como um arquivo em vez de como habilidades.

As reclamações contra as quais foi escrito

A fonte indicada no README é um post de Andrej Karpathy no X, que o README cita para três críticas sobre como os modelos escrevem código. Vale a pena lê-las na íntegra, porque os quatro princípios correspondem a elas quase um a um.

O primeiro: os modelos "fazem suposições erradas em seu nome e simplesmente seguem com elas sem verificar", e "não gerenciam sua confusão, não buscam esclarecimentos, não expõem inconsistências, não apresentam trade-offs, não fazem objeção quando deveriam." Observe o que está sendo descrito. Não é uma reclamação sobre respostas erradas. É uma reclamação sobre respostas erradas fluentes entregues sem hesitação, em que a incerteza que deveria ter produzido uma pergunta, em vez disso, produziu código confiante.

A segunda: eles "gostam muito de complicar demais o código e as APIs, inflar abstrações, não limpar código morto… implementar uma construção inchada com mais de 1000 linhas quando 100 bastariam." Essa é familiar para qualquer pessoa que já pediu um recurso e recebeu um framework.

O terceiro é mais sutil e, para qualquer pessoa que revise diffs, o mais custoso: eles "ainda às vezes alteram/removem comentários e código que não entendem suficientemente como efeitos colaterais, mesmo que sejam ortogonais à tarefa". Uma edição ortogonal em um único comentário é pequena por si só. Multiplicada por toda uma base de código, é assim que uma fila de revisão se enche de mudanças que ninguém pediu e que um comentário explicando uma solução alternativa desaparece antes que alguém descubra por que a solução alternativa existia.

Quatro princípios, e o teste que cada um deixa para trás

O arquivo codifica quatro princípios. Cada um vem com um curto conjunto de regras, e dois deles explicitam um teste de uma linha que você pode aplicar a um diff sem instalar nada. As regras são onde o caráter do arquivo se revela.

Pense antes de codificar

A instrução do título é "Não presuma. Não esconda a confusão. Exponha os trade-offs." Sob ele: declare suposições explicitamente e pergunte em vez de adivinhar; apresente múltiplas interpretações quando a solicitação for ambígua; conteste quando existir uma abordagem mais simples; pare quando estiver confuso, nomeie o que não está claro e peça esclarecimentos. Isso é direcionado diretamente à primeira reclamação. O mecanismo não é "ter mais cuidado" — é converter escolhas silenciosas em escolhas visíveis, para que um revisor possa discordar antes de o código existir, e não depois.

Simplicidade em Primeiro Lugar

A regra é o mínimo de código que resolve o problema, sem nada especulativo: nenhum recurso além do que foi pedido, nenhuma abstração para código de uso único, nenhuma flexibilidade ou configurabilidade que ninguém solicitou, nenhum tratamento de erro para cenários impossíveis, e "se 200 linhas pudessem ser 50, reescreva". O teste é uma única pergunta — um engenheiro sênior diria que isso está complicado demais? — e trata-se de uma avaliação subjetiva, e assumidamente assim.

Alterações cirúrgicas

Aqui o ficheiro divide a instrução em duas, o que é a coisa mais útil nele. Ao editar código existente: não melhore código, comentários ou formatação adjacentes; não refatore o que não está avariado; siga o estilo existente mesmo que o fizesse de forma diferente; mencione código morto não relacionado em vez de o eliminar. Quando as suas próprias alterações criam órfãos: remova as importações, variáveis e funções que as suas alterações deixaram sem uso, mas deixe o código morto pré-existente em paz, a menos que lhe seja pedido. O teste é que cada linha alterada remete diretamente para o pedido.

Execução Orientada a Objetivos

Defina critérios de sucesso e repita até verificar. O README mostra a transformação como pares. Em vez de "adicionar validação", escreva testes para entradas inválidas e depois faça-os passar. Em vez de "corrigir o bug", escreva um teste que o reproduza e depois faça-o passar. Em vez de "refatorar X", garanta que os testes passem antes e depois. Para trabalho em várias etapas, ele pede um plano curto no qual cada etapa nomeia sua própria verificação. O README cita Karpathy novamente aqui: "LLMs são excepcionalmente bons em repetir até atingirem objetivos específicos… Não diga a ele o que fazer, dê critérios de sucesso e observe-o seguir."

Um arquivo, uma habilidade e um plugin são três coisas diferentes.

Vale a pena ser preciso sobre a mecânica, porque o comportamento prático difere. CLAUDE.md é um arquivo de instruções de projeto: texto que o Claude Code lê como contexto permanente de um repositório, presente quer alguém o tenha solicitado neste turno ou não. Uma skill é uma pasta com um SKILL.md que descreve quando a capacidade deve ser usada, carregada quando uma tarefa exige e não antes. Um plugin é um pacote de distribuição, instalado por meio de um marketplace, que pode conter skills, comandos e outros componentes. As distinções dizem respeito a quando as instruções entram no contexto e a quem decide, não à qualidade.

Nesse sentido, um CLAUDE.md é o mais direto dos três. Ele está sempre ativo naquele projeto, aplica-se a todas as tarefas nele e ocupa contexto em cada turno, seja o trabalho uma correção de erro de digitação de uma linha ou uma migração. O próprio README do arquivo reconhece o custo em uma seção chamada Tradeoff Note: as diretrizes favorecem a cautela em vez da velocidade e, para tarefas triviais — correções simples de erros de digitação, soluções óbvias de uma linha —, você deve usar o bom senso. Ele diz que o objetivo é reduzir erros custosos em trabalhos não triviais, não desacelerar os simples.

Essa é uma descrição justa do que um arquivo de instruções permanentes pode fazer. Ele não pode adicionar uma capacidade que o modelo não tem. Só pode tornar o comportamento existente do modelo mais ou menos provável. É por isso que o arquivo é escrito como restrições — não faça isto, pergunte antes daquilo — em vez de como um incentivo para ser melhor.

O que 222.612 estrelas medem

Eles medem a atenção. Isso não é um desdém e não é pouca coisa: um repositório criado em janeiro de 2026 e com o último push em abril chegou a 222.612 estrelas e 22.321 forks em 23 de outubro de 2026, no GitHub, consultado naquele dia, o que significa que foi amplamente compartilhado e forkado por pessoas que queriam uma cópia própria. A contagem de estrelas é um proxy razoável para quantas pessoas acharam algo que valia a pena guardar nos favoritos.

Não é um proxy do efeito, e o repositório não finge o contrário. O que não está publicado em nenhum lugar do repositório: qualquer benchmark que compare resultados com e sem o ficheiro, qualquer metodologia para medir se funciona e qualquer comparação com um controlo. Não há antes e depois numa base de código real, nem estudo com revisores, nem taxa de incidentes. Um ficheiro como este é uma hipótese sobre o comportamento do modelo, elegantemente enunciada, e ninguém executou o ensaio.

O que o README oferece, em vez disso, é uma seção chamada How to Know It's Working, que lista quatro coisas que você pode observar: menos alterações desnecessárias nos diffs, menos reescritas por excesso de complicação, perguntas de esclarecimento chegando antes da implementação em vez de depois de erros, e pull requests limpos e mínimos. Esses são sinais sensatos. Também são exatamente o que você escreveria se não tivesse medido nada, e são autorrelatados por quem estiver aplicando o arquivo. Leia-os como uma lista de verificação para usar como critério para o arquivo no seu próprio repositório, não como evidência de que ele já passou.

O que você realmente digita para instalá-lo

O README oferece dois caminhos. O recomendado é executado dentro do Claude Code: adicione o marketplace e depois instale o plugin, após o que as diretrizes ficam presentes em todos os projetos, e não por repositório. O segundo é por projeto: baixe o CLAUDE.md bruto para um novo repositório ou anexe-o a um já existente. Há também uma regra de projeto do Cursor versionada, de modo que as mesmas diretrizes se aplicam quando a pasta é aberta no Cursor — um detalhe que indica que o arquivo foi escrito para ser portátil entre ferramentas que leem um arquivo de instruções no nível do projeto, não vinculado ao loader de um único fornecedor.

Um ponto problemático, que vale a pena sinalizar porque você vai esbarrar nele se seguir o README exatamente. O nome do comando do marketplace é forrestchang/andrej-karpathy-skills, enquanto a URL do repositório no topo da página é multica-ai/andrej-karpathy-skills. Ambas as strings aparecem no mesmo README, consultado em 23 de outubro de 2026. Consigo ver a divergência e não sei dizer por que ela existe, então o conselho honesto é tentar o outro caminho se um falhar, e tratar uma das duas strings como desatualizada.

A outra coisa a observar na página inicial: o repositório é mantido pela multica-ai, e a citação em bloco de abertura do README anuncia o Multica, “uma plataforma de código aberto para executar e gerenciar agentes de programação com habilidades reutilizáveis”. Isso é uma divulgação legítima e também é uma pista de por que o empacotamento tem a aparência que tem. Um projeto interessado em habilidades reutilizáveis provavelmente distribuirá suas próprias orientações como algo instalável, que é o que o plugin é.

Usando-o sem herdar suas pressuposições

A seção de Personalização é a parte que a maioria dos leitores pula. O arquivo foi projetado para ser mesclado com instruções específicas do projeto, em vez de substituí-las, e os exemplos que ele fornece são concretos: use o modo estrito do TypeScript, todos os endpoints de API devem ter testes, siga os padrões de tratamento de erros existentes em um arquivo específico. Isso não é decoração. É a diferença entre um manual genérico e um conjunto de instruções que sabe onde seu código vive.

Há uma razão prática para mesclar em vez de empilhar. Se você colar o arquivo como está e seu projeto tiver suas próprias convenções, os dois conjuntos de instruções podem entrar em conflito, e um modelo reconciliando um conflito é exatamente a confusão que o primeiro princípio tenta eliminar. Escrever suas convenções no mesmo arquivo, com a mesma voz, mantém a superfície de instruções pequena o suficiente para ser auditada.

E você deve auditá-lo, sim. Este é um breve documento de instruções comportamentais que se aplicará a todas as solicitações no repositório. A pergunta certa não é se 222,612 pessoas podem estar erradas — esse enquadramento não resolve nada —, mas se cada regra corresponde a uma falha que você realmente viu. Se seus diffs nunca contiveram reescritas incidentais de comentários, a seção “Surgical Changes” só consome contexto sem motivo. Exclua-a. O arquivo tem licença MIT e foi feito para ser editado.

Um nível abaixo, nada disso muda qual modelo responde. Um arquivo CLAUDE.md molda como uma solicitação é tratada depois que chega a um modelo; ele não diz nada sobre o modelo que a recebe. Essa segunda decisão pertence ao que estiver à frente do modelo. Uma forma de organizar isso é um único endpoint compatível com OpenAI que disponibiliza mais de 200 modelos sob uma única chave, com failover automático entre provedores e preços de lista dos provedores repassados com 0% de margem. Nós hospedamos modelos; não criamos o Claude Code, e nada no seu repositório é visível para nós.

A busca continuará dizendo skills, porque essa é a palavra que as pessoas têm para uma coisa que você instala para fazer um agente se comportar de forma diferente, e o empacotamento em torno deste repositório também a usa. O artefato é um arquivo: um documento de instruções permanentes, escrito em resposta a três reclamações específicas, com quatro princípios e um conjunto de testes que você pode aplicar manualmente. Julgue-o por se essas reclamações soam como o seu repositório. Essa é uma pergunta melhor do que a contagem de estrelas, que sempre mediu apenas quantas pessoas tiveram a mesma reação que você acabou de ter.