Guia de entrada para karpathy-guidelines: as convenções de programação com grandes modelos recomendadas por Andrej Karpathy

Dificuldade: Iniciante | Duração: ~15 minutos | Objetivo: dominar 4 princípios + conseguir usar o karpathy-guidelines para orientar o comportamento de programação com IA

Público-alvo

• Desenvolvedores usando assistentes de código com IA como Claude Code, Cursor e Copilot
• Com 1–5 anos de experiência em desenvolvimento, querendo que o código gerado pela IA seja mais preciso, com menos enrolação e sem alterações aleatórias
• Com alguma prática em programação com IA e buscando normas de colaboração de forma sistemática

Dependências essenciais e ambiente

Estrutura completa do projeto (árvore)

andrej-karpathy-skills/
├── CLAUDE.md                # Arquivo guia principal (versão concisa dos 4 princípios; usado tanto por plugin quanto por arquivo)
├── README.md                # Instruções de instalação e uso
├── EXAMPLES.md              # Muitos exemplos práticos (acertos e erros)
└── skills/
    └── karpathy-guidelines/  # Formato de plugin do Claude Code (forma recomendada de instalação)

---

1. Primeiro, entenda o problema: por que o LLM "se mete" na própria lógica

No fim de 2025, Andrej Karpathy publicou um tweet apontando diretamente o problema central da programação com grandes modelos atualmente:

"The models make wrong assumptions on their own behalf and just run along with them without checking. They don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should."

Traduzindo: os LLMs fazem suposições por conta própria, sem checar; quando algo fica ambíguo, não perguntam e simplesmente continuam; o código vai ficando cada vez mais inchado; e ainda por cima alteram partes que eles não entendem.

Quase todo desenvolvedor que usa programação com IA de forma mais profunda já passou por isso: você pede para a IA consertar um bug pequeno e ela reescreve metade de um módulo; você pede para adicionar uma função simples e ela introduz três camadas de abstração.

O karpathy-guidelines foi criado justamente para combater esses quatro problemas:

---

2. Instalar karpathy-guidelines

Há duas formas de instalar; a primeira é recomendada.

Forma 1: via plugin (recomendada)

# Passo 1: adicionar o marketplace de plugins
/plugin marketplace add forrestchang/andrej-karpathy-skills

# Passo 2: instalar o plugin
/plugin install andrej-karpathy-skills@karpathy-skills

Após instalar, o Claude Code carrega automaticamente esses 4 princípios em qualquer projeto.

Forma 2: baixar diretamente o CLAUDE.md (para qualquer projeto)

Novo projeto:

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

Projeto já existente (adicionar ao CLAUDE.md atual):

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

---

3. Análise dos 4 princípios, um a um

Princípio 1: Think Before Coding

Essência: não assuma, não esconda a confusão — exponha ativamente as escolhas e trade-offs.

Este é o princípio que mais contraria o instinto natural das IAs. O objetivo do treinamento de uma IA é "entregar uma resposta"; quando o comando do usuário é ambíguo, ela tende a apostar na interpretação mais razoável e continuar — em vez de parar para perguntar: "o que você quer dizer exatamente?".

A forma correta de abrir é assim:

# O usuário diz: "deixe a busca mais rápida"

# ❌ O que a IA costuma fazer: adicionar cache, índices e processamento assíncrono em silêncio, e escrever 200 linhas de uma vez
@lru_cache(maxsize=1000)
async def search(query: str) -> List[Result]:
    # ... um monte de código de otimização
    pass

# ✅ O que o karpathy-guidelines exige:
"""
"Deixar a busca mais rápida" pode ser entendido de algumas formas:
1. Resposta mais rápida (< 100ms): adicionar índice no banco + cache; estimativa de 2 horas
2. Maior capacidade de throughput: adaptar para assíncrono + pool de conexões; estimativa de 4 horas
3. Sensação de velocidade maior (UX): carregamento progressivo; estimativa de 3 horas

Qual delas você quer?
"""

Quando o comando é ambíguo, parar e esclarecer antes costuma ser muito mais eficiente do que fazer tudo primeiro e ter que voltar depois.

No nível do código, esse princípio exige de você:

• Declarar claramente suas suposições; se houver algo incerto, perguntar
• Quando existirem várias interpretações razoáveis, listar todas para o usuário escolher
• Ao encontrar uma solução mais simples, trazê-la proativamente
• Quando algo não ficar claro, parar imediatamente e perguntar

---

Princípio 2: Simplicity First

Essência: escrever apenas o mínimo de código necessário para resolver o problema atual, sem design preditivo.

A IA tem uma tendência: enfiar "boas práticas" de uma vez só, mesmo quando elas não são necessárias no momento. Você pede para a IA escrever um cálculo de desconto e ela pode te entregar um ecossistema completo com Strategy, Factory e uma classe de configuração.

Veja uma comparação real:

Pedido do usuário: "adicione uma função de cálculo de desconto"

# ❌ O que a IA faz com frequência: introduzir abstrações desnecessárias
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Protocol, Union

class DiscountStrategy(ABC):
    @abstractmethod
    def calculate(self, amount: float) -> float:
        pass

class PercentageDiscount(DiscountStrategy):
    def __init__(self, percentage: float):
        self.percentage = percentage
    def calculate(self, amount: float) -> float:
        return amount * (self.percentage / 100)

@dataclass
class DiscountConfig:
    strategy: DiscountStrategy
    min_purchase: float = 0.0
    max_discount: float = float('inf')

class DiscountCalculator:
    def __init__(self, config: DiscountConfig):
        self.config = config
    def apply_discount(self, amount: float) -> float:
        # ... um monte de código

# Para usar, precisa de 30+ linhas de preparação

# ✅ O jeito do Simplicity First: 
def calculate_discount(amount: float, percent: float) -> float:
    """Calcula o valor do desconto. percent é uma porcentagem (ex.: 10 = 10%)."""
    return amount * (percent / 100)

# Uso
discount = calculate_discount(100.0, 10.0)  # 10% de desconto

Critérios para julgar esse princípio:

• Não adicionar funcionalidades que ninguém pediu
• Não abstratizar código que será usado apenas uma vez
• Se não é necessário "flexibilidade", não reservar espaço para configuração
• Não escrever tratamento de erros para cenários impossíveis
• Depois de escrever o código, se perguntar: "um engenheiro sênior chamaria isso de overengineering?" Se sim, reescreva

---

Princípio 3: Surgical Changes

Essência: alterar somente o que precisa ser alterado, limpar a sujeira que você mesmo causou, mas sem mexer no que já existia.

Ao consertar bugs, a IA tem uma tendência especial a "otimizar por conveniência": altera 3 linhas do bug e, de quebra, muda nomes de variáveis, ajusta formatação, troca comentários. O karpathy-guidelines exige precisão no nível de "cirurgia".

Um cenário típico: o usuário diz "corrija o problema do validador que quebra quando o email está vazio"

  def validate_user(user_data):
-     # Check email format
-     if not user_data.get('email'):
+     email = user_data.get('email', '')
+     if not email or not email.strip():
          raise ValueError("Email required")
-     # Basic email validation
-     if '@' not in user_data['email']:
+     if '@' not in email:
          raise ValueError("Invalid email")
-     # Check username
-     if not user_data.get('username'):
+     # Check username  ← manter como era
+     if not user_data.get('username'):
          raise ValueError("Username required")
      return True

❌ O que a IA costuma fazer (além do que o usuário pediu):

# E ainda adicionou:
# - validação mais rigorosa do formato do email (regex)
# - validação do tamanho do nome de usuário
# - validação de caracteres do nome de usuário
# - docstring
# - mudou o estilo das aspas ('' → "")

✅ O que o Surgical Changes exige (apenas mudar as duas linhas relacionadas a email vazio):

-     if not user_data.get('email'):
+     email = user_data.get('email', '')
+     if not email or not email.strip():
          raise ValueError("Email required")
-     if '@' not in user_data['email']:
+     if '@' not in email:
          raise ValueError("Invalid email")

Critério: toda linha alterada deve poder ser rastreada diretamente até o pedido específico do usuário.

---

Princípio 4: Goal-Driven Execution

Essência: traduzir "o que fazer" para "como verificar que deu certo". Substitua comandos vagos por critérios de sucesso.

Este é um ponto que Andrej Karpathy enfatiza muito: "LLMs são muito bons em executar em loop até atingirem um objetivo específico. Em vez de dizer o que fazer, dê os critérios de sucesso e deixe que eles rodem sozinhos."

Compare as duas formas de dar instruções:

❌ Instrução vaga (a IA fica sem direção):

Corrigir o problema do sistema de login

✅ Instrução Goal-Driven (com direção clara para a IA):

Problema específico no sistema de login: quando o usuário troca a senha, a sessão antiga não expira.

Plano:
1. Escrever testes: trocar senha → verificar que a sessão antiga é rejeitada
   Verificação: teste falha (reproduz o bug)

2. Implementação: ao trocar a senha, limpar a sessão correspondente do usuário
   Verificação: teste passa

3. Casos de borda: login em múltiplos dispositivos, e troca de senha em concorrência
   Verificação: novos testes passam

4. Checagem de regressão: todos os testes relacionados ao login passam
   Verificação: pnpm test

Cobertura atual de testes do módulo de login: [dados]
Diga exatamente qual problema de login você encontrou?

Formato padrão para tarefas em múltiplas etapas:

1. [descrição da etapa] → Verificação: [como verificar]
2. [descrição da etapa] → Verificação: [como verificar]
3. [descrição da etapa] → Verificação: [como verificar]

O benefício disso é: após cada etapa, a IA tem uma checklist clara para conferir; não precisa ficar confirmando repetidamente "está certo assim?".

---

4. Como verificar se as diretrizes estão funcionando

Depois de instalar o karpathy-guidelines, você pode avaliar se ele está fazendo efeito por algumas dimensões:

Ver a qualidade do diff:

• As mudanças são todas o que o usuário pediu?
• Há alguma "otimização por conveniência" a mais?
• Estilo de aspas, comentários e docstring foram alterados sem autorização?

Ver o momento de fazer perguntas:

• Quando a IA encontra um comando ambíguo, ela para e pergunta ativamente?
• Ou simplesmente adivinha e começa a escrever?

Ver a complexidade do código:

• O código novo é exatamente o suficiente?
• Há overengineering ou overabstractions?

Se essas três dimensões estiverem melhorando, então as diretrizes estão funcionando.

---

5. Mesclar com o CLAUDE.md já existente do projeto

A maioria dos projetos já tem seu próprio CLAUDE.md; cobrir diretamente pode fazer você perder configurações existentes. O correto é adicionar em vez de substituir:

# Primeiro, confirme o conteúdo atual do CLAUDE.md
cat CLAUDE.md

# Depois, mescle manualmente usando um editor, ou:
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Estrutura recomendada após a mesclagem:

# Explicação do projeto (conteúdo original mantido)

---

# karpathy-guidelines (conteúdo adicionado; PS: recomendado por Andrej Karpathy)

[Cole aqui o conteúdo do CLAUDE.md]

---

## Diretrizes específicas do projeto

- Usar modo strict do TypeScript
- Todos os endpoints da camada de API devem ter testes
- Seguir o padrão de tratamento de erros em src/utils/errors.ts

---

Solução de problemas (FAQ)

Q1: O plugin não está surtindo efeito após instalar?

# Confirmar que o plugin foi carregado
/plugin list

# Se não estiver, reinicie o Claude Code
# No Claude Code, digite /exit para sair e entre novamente

Q2: E se o CLAUDE.md do projeto entrar em conflito com o plugin?

Vale o CLAUDE.md do projeto. O plugin fornece comportamento global de fallback; o arquivo do projeto sobrepõe as configurações do plugin.

Q3: Tarefas simples também ficam travadas pedindo confirmação. O que fazer?

Isso é esperado — o karpathy-guidelines exige esclarecimento de comandos ambíguos de forma igual para todas as tarefas. Para tarefas claramente simples (por exemplo, "trocar a variável a por b"), você pode deixar explícito no comando: "é uma substituição simples, pode fazer direto". Assim, a IA pula o passo de confirmação.

Q4: A IA não segue Surgical Changes e continua mudando formato. E agora?

Imponha limites claros ao escopo das mudanças na sua instrução:

Alterar a validação de valores vazios na função validateEmail; mudar apenas isso, sem mexer no resto do código nem na formatação.

Q5: Depois de mesclar CLAUDE.md aparecem conflitos. Como resolver?

Edite manualmente o CLAUDE.md, mantendo o conteúdo original e os princípios adicionados, evitando duplicar trechos. Se dois lugares definirem o mesmo princípio, vale a definição mais específica do projeto.

Q6: Preciso aplicar esses princípios retroativamente em projetos já existentes?

Não. O karpathy-guidelines restringe o comportamento das mudanças futuras, não pede que você refatore o código existente. Use-o para orientar interações de programação novas.

---

Leitura complementar e caminhos de evolução

• Tweet original de Andrej Karpathy — observações sobre a origem das armadilhas da programação com LLMs
• forrestchang/andrej-karpathy-skills — repositório do projeto no GitHub, com o EXAMPLES.md completo (muitos exemplos bons e ruins, vale a pena ler com atenção)
• Documentação oficial do Claude Code — entender as capacidades completas do CLI e as opções de configuração
• Tutorial de integração do OpenClaw — se você quiser explorar mais a prática de agentes de IA localizados, o OpenClaw oferece capacidades mais profundas de chamadas de ferramentas

---

Próximos passos (direções avançadas)

Depois de dominar os quatro princípios, você pode continuar explorando:

Extensões personalizadas: adicionar no CLAUDE.md normas de codificação específicas do projeto, para que a IA tenha tanto as restrições gerais do karpathy-guidelines quanto o estilo próprio do projeto.

Compartilhamento em equipe: incorporar o karpathy-guidelines nas diretrizes de codificação do time. Assim, ao clonar o projeto, novos membros já recebem automaticamente as regras de comportamento para programação com IA.

Quantificar o efeito: registrar quantas vezes houve retrabalho no código da IA antes e depois de introduzir as diretrizes, o escopo das mudanças e quantas alterações não relacionadas apareceram em PRs, validando com dados o valor real dessa metodologia.