Um único arquivo de texto, sem nenhuma linha de código, passou de 217 mil estrelas no GitHub. Ele se chama CLAUDE.md e é lido pelo Claude Code no começo de cada conversa: tudo o que está escrito nele vira instrução de comportamento para a IA naquele projeto.
O conteúdo nasceu das reclamações públicas do Andrej Karpathy, cofundador da OpenAI, sobre os erros que a IA comete quando programa: assumir coisas sem perguntar, complicar o que era simples, mexer no que ninguém pediu. Quem escreveu o arquivo foi o Forrest Chang, organizando essas observações em quatro regras.
Este guia traz as quatro regras traduzidas, explica o que cada uma muda na prática, mostra as duas formas de instalar e termina com o aviso que o próprio arquivo faz sobre quando não seguir tudo à risca.
Os links
- Repositório: https://github.com/multica-ai/andrej-karpathy-skills (o endereço antigo,
forrestchang/andrej-karpathy-skills, redireciona para cá) - O arquivo: https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md
- Descrição oficial: "A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls."
- Números em 08/10/2026: 217.561 estrelas, criado em 27/01/2026. O repositório não declara licença no GitHub.
Regra 1: pensa antes de codar
Não assuma. Não esconda a dúvida. Mostre as alternativas.
Antes de implementar, a IA deve:
- Dizer em voz alta o que está assumindo. Se não tiver certeza, perguntar.
- Se o pedido tiver mais de uma leitura possível, apresentar as leituras, em vez de escolher uma em silêncio.
- Se existir um caminho mais simples, dizer. E discordar quando fizer sentido.
- Se algo estiver confuso, parar, dizer o que está confuso e perguntar.
Na prática: em vez de receber um sistema inteiro construído em cima de uma suposição errada, você recebe uma pergunta de uma linha antes de começar.
Regra 2: simplicidade primeiro
O mínimo de código que resolve o problema. Nada especulativo.
- Nenhuma funcionalidade além do que foi pedido.
- Nenhuma abstração para código que só é usado uma vez.
- Nenhuma "flexibilidade" ou "configuração" que ninguém pediu.
- Nenhum tratamento de erro para cenário impossível.
- Escreveu 200 linhas e dava para fazer em 50? Reescreve.
O teste que o arquivo propõe: "um engenheiro experiente diria que isso está complicado demais?" Se sim, simplifique.
Regra 3: mudança cirúrgica
Mexa só no que precisa. Limpe só a sua própria bagunça.
Ao editar código que já existe:
- Não "melhorar" código, comentário ou formatação vizinhos.
- Não refatorar o que não está quebrado.
- Seguir o estilo que já está lá, mesmo que a IA fizesse diferente.
- Viu código morto sem relação com o pedido? Avisar, não apagar.
Quando a própria mudança deixa sobras (um import ou uma função que ficaram sem uso por causa dela), essas sobras a IA remove. O que já estava morto antes fica, a menos que você peça.
O teste: cada linha alterada tem de levar direto ao que você pediu.
Regra 4: execução guiada por objetivo
Defina o que é sucesso. Repita até comprovar.
A regra pede que a tarefa vire um objetivo verificável:
- "Adiciona validação" vira "escreve testes para as entradas inválidas e faz eles passarem".
- "Corrige o bug" vira "escreve um teste que reproduz o bug e faz ele passar".
- "Refatora X" vira "garante que os testes passam antes e depois".
Em tarefa de vários passos, a IA apresenta um plano curto, cada passo com a sua conferência:
1. [Passo] → conferir: [como saber que deu certo]
2. [Passo] → conferir: [como saber que deu certo]
3. [Passo] → conferir: [como saber que deu certo]
Critério forte deixa a IA trabalhar sozinha até o fim. Critério fraco ("faz funcionar") obriga você a responder dúvida o tempo todo.
Como instalar
Opção A: plugin do Claude Code (vale para todos os seus projetos). Dentro do Claude Code:
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
Opção B: arquivo na pasta do projeto (vale só para aquele projeto). Projeto novo, sem CLAUDE.md:
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
Projeto que já tem CLAUDE.md: acrescente no fim, sem apagar o que você já escreveu.
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
Cuidado com a Opção B: o curl -o sobrescreve o arquivo. Se o projeto já tem um CLAUDE.md, use sempre o segundo bloco.
Como saber se está funcionando
O próprio arquivo diz como medir. As regras estão funcionando quando:
- as mudanças que a IA entrega mexem em menos coisa que não foi pedida;
- você precisa pedir menos vezes para ela reescrever algo que ficou complicado;
- as perguntas de esclarecimento chegam antes da implementação, e não depois do erro.
Quando não seguir à risca
O arquivo avisa logo no começo: as regras favorecem cautela em vez de velocidade. Para tarefa trivial, como trocar um texto ou renomear uma variável, use o bom senso. A IA perguntar antes de cada detalhe pequeno vira atraso, não cuidado.
E as regras não deixam a IA perfeita. Elas cortam os erros mais comuns: o de adivinhar, o de complicar e o de mexer onde não devia.