225 mil estrelas para um Markdown: Karpathy em quatro regras

Um repositório que contém um único arquivo Markdown tem 225,000 estrelas. Ganhou cerca de 4,000 só nesta semana. Não há código, nem etapa de build, nem release, nem tabela de benchmark: apenas quatro princípios e um conjunto de instruções sobre como um modelo de linguagem deve se comportar quando recebe a tarefa de alterar uma base de código.

O arquivo se chama CLAUDE.md, fica num repositório chamado andrej-karpathy-skills, mantido por forrestchang. Ele comprime uma série de críticas que Andrej Karpathy fez ao comportamento dos LLMs ao programar em algo que um agente realmente lê no começo de cada sessão. O dado interessante é o número de estrelas, não o conteúdo, porque ele sugere algo sobre como o comportamento dos agentes vem sendo remendado hoje: de forma não oficial, em prosa, por indivíduos.

As críticas, nas palavras de Karpathy

Três citações do texto original em que o repositório se baseia:

"Os modelos fazem suposições erradas no seu lugar e simplesmente seguem com elas, sem checar. Não administram a própria confusão, não pedem esclarecimento, não expõem incoerências, não apresentam trade-offs, não discordam quando deveriam."

"Eles adoram complicar código e APIs, inflar abstrações, não limpar código morto... implementam uma construção inflada de mais de 1,000 linhas quando 100 bastariam."

"Eles ainda às vezes mudam ou removem, como efeito colateral, comentários e código que não entendem o suficiente, mesmo quando é ortogonal à tarefa."

Quem já entregou código escrito por agente reconhece as três. A segunda é a mais comum: você pede uma função de validação e recebe uma classe base abstrata, um padrão strategy, um objeto de configuração e quarenta linhas de tratamento de erro para estados que não podem acontecer.

O que os quatro princípios realmente dizem

Pensar antes de codar. Declarar as suposições em voz alta, apresentar várias interpretações em vez de escolher uma em silêncio, discordar quando existe um caminho mais simples, parar quando estiver confuso e nomear o que não está claro.

Simplicidade primeiro. O mínimo de código que resolve o problema. Nenhum recurso além do pedido, nenhuma abstração para código de uso único, nenhuma configurabilidade que ninguém pediu, nenhum tratamento de erro para cenários impossíveis. O teste: um engenheiro sênior chamaria isso de complicado demais?

Mudanças cirúrgicas. Mexer só no que precisa. Não melhorar o código ao lado nem reformatar o que você apenas atravessa. Seguir o estilo existente mesmo que você fizesse diferente. Se notar código morto sem relação, mencione — não apague. Se suas mudanças criarem órfãos, limpe só esses. O teste: cada linha alterada remete ao pedido.

Execução guiada por objetivo. Converter instruções imperativas em critérios de sucesso verificáveis. Não "adicione validação", mas "escreva testes para entradas inválidas e faça-os passar". Não "corrija o bug", mas "escreva um teste que o reproduza e faça-o passar".

O último é o único princípio que não é contenção. É alavancagem, e vem com a melhor frase do material original: LLMs são excepcionalmente bons em repetir até atingir objetivos específicos. Não diga o que fazer; dê critérios de sucesso e observe.

A instalação, e o fato de serem duas linhas

Dois caminhos, ambos triviais.

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

Ou, por projeto:

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

Há também uma regra do Cursor versionada em .cursor/rules/karpathy-guidelines.mdc, então as mesmas orientações valem quando o projeto abre no Cursor. Licença MIT.

A história da distribuição é o ponto. Dois anos atrás, corrigir "os modelos fazem overengineering" significaria um fine-tuning, um system prompt distribuído por um fornecedor ou um framework. Hoje é um arquivo que o usuário joga num repositório, mais uma entrada de marketplace que o coloca em todos os projetos daquela máquina. O ciclo de feedback entre a reclamação e a correção é muito mais curto, e é por isso que o contador está onde está: o arquivo é a menor unidade possível de mudança de comportamento.

Por que continuo cético em relação a esse enquadramento

Três ressalvas, no espírito do próprio arquivo.

Princípios não são testes. "Simplicidade primeiro" é uma preferência, não um critério. Um agente que lê isso ainda vai produzir uma solução de 300 linhas onde 80 bastariam, porque o modelo não tem como medir complexidade. O único princípio do arquivo que funciona de verdade — execução guiada por objetivo — funciona justamente porque troca uma preferência por uma checagem: um teste que passa ou não passa.

"Mudanças cirúrgicas" briga com aquilo em que agentes são bons. Se você pede uma alteração pequena e recebe uma alteração pequena, usou uma ferramenta cara para economizar digitação. O valor de um agente é poder reestruturar algo que você não queria tocar. A resposta do arquivo é que reestruturação deve ser pedida, não oferecida — razoável, mas significa que as orientações otimizam para um tipo específico de usuário: alguém com uma base de código existente e opinião forte sobre diffs.

Ninguém mede se funciona. O repositório lista sinais: menos mudanças desnecessárias nos diffs, menos reescritas, perguntas de esclarecimento antes da implementação em vez de depois. São reais e observáveis. Mas não há condição de controle. Você instala um arquivo que diz "pergunte antes de supor", e agora o agente pergunta antes de supor. Foi o arquivo, ou o ato de escrever aquilo fez você notar um comportamento que já existia?

O autor é honesto sobre o trade-off, o que é mérito dele: as orientações puxam para a cautela em vez da velocidade, e em tarefas triviais você deve usar o próprio julgamento. É a ressalva correta e também é a tensão. Um agente que para para perguntar sobre a correção de um typo de uma linha é pior do que um que corrige.

A versão que eu escreveria

Se a fraqueza do arquivo é que três dos quatro princípios são preferências, o remédio é convertê-los em checagens. Concretamente, quatro linhas que sobrevivem ao contato com um repositório de verdade:

Antes de editar, liste os arquivos que pretende tocar e pare se a lista for maior do que o pedido implica. Isso transforma "mudanças cirúrgicas" em portão, não em humor.

Antes de terminar, rode os testes e cole a saída. Isso torna a "execução guiada por objetivo" não negociável, e é a instrução de maior alavancagem que você pode colocar na frente de um agente.

Se uma tarefa tem mais de uma interpretação plausível, escreva as duas e pergunte qual. Isso converte "pensar antes de codar" de aspiração em uma rodada da conversa.

E um orçamento de diff: se a mudança adiciona mais de aproximadamente 150 linhas para corrigir um bug, pare e justifique cada abstração. Grosseiro, mas pega o modo de falha que Karpathy descreveu, o que realmente custa tempo.

Nada disso está no arquivo, e não precisa estar. O trabalho do arquivo é definir uma postura. As checagens são trabalho de quem é dono do repositório.

O que o número de estrelas está realmente dizendo

A maior parte do ferramental de agentes lançado neste ano é sobre capacidade: contexto mais longo, mais ferramentas, execução em paralelo. Este arquivo é sobre contenção, e recebeu mais atenção do que a maioria dos lançamentos de capacidade.

Essa diferença é informativa. Quem paga por essas ferramentas concluiu que o gargalo não é mais o que o modelo consegue fazer, e sim fazê-lo parar de fazer coisas que ninguém pediu. Um arquivo Markdown com 225,000 estrelas é um sinal incomumente claro de onde está a frustração de verdade.

Também é um sinal um pouco constrangedor para os laboratórios. O repositório com mais estrelas da categoria é uma lista de quatro coisas que os modelos já deveriam estar fazendo.