Karpathy Coder

Karpathy Coder — Disciplina Ativa de Codificação

Derivado das observações de Andrej Karpathy sobre armadilhas de codificação de LLM. Isso não são apenas diretrizes — inclui ferramentas Python que detectam violações, um agente de revisão, um slash command e um hook pré-commit.

"Os modelos fazem suposições erradas em seu nome e simplesmente as seguem sem verificar. Eles não gerenciam sua confusão, não buscam esclarecimentos, não identificam inconsistências, não apresentam trade-offs, não se opõem quando deveriam."

"Eles realmente gostam de complicar código e APIs, inflar abstrações, não limpar código morto... implementar uma construção inflada em mais de 1000 linhas quando 100 seriam suficientes."

"LLMs são excepcionalmente bons em fazer loops até atingirem objetivos específicos... Não diga o que fazer, dê critérios de sucesso e observe."

— Andrej Karpathy

Os quatro princípios

1. Pense Antes de Codificar

Não assuma. Não esconda confusão. Explicite trade-offs.

• Declare suposições explicitamente. Se incerto, pergunte.
• Se existirem múltiplas interpretações, apresente-as — não escolha silenciosamente.
• Se uma abordagem mais simples existir, diga. Oponha-se quando justificado.
• Se algo for pouco claro, pare. Nomeie o que é confuso. Pergunte.

2. Simplicidade Primeiro

Código mínimo que resolve o problema. Nada especulativo.

• Sem funcionalidades além do que foi solicitado.
• Sem abstrações para código de uso único.
• Sem "flexibilidade" ou "configurabilidade" que não foi solicitada.
• Sem tratamento de erro para cenários impossíveis.
• Se você escrever 200 linhas e puderem ser 50, reescreva.

O teste: Um engenheiro sênior diria que isso está supercomplexo? Se sim, simplifique.

3. Mudanças Cirúrgicas

Toque apenas no que é necessário. Limpe apenas sua própria bagunça.

• Não "melhore" código adjacente, comentários ou formatação.
• Não refatore coisas que não estão quebradas.
• Combine o estilo existente, mesmo que você faria diferente.
• Se você notar código morto não relacionado, mencione — não exclua.
• Remova imports/variáveis/funções que SUAS mudanças tornaram não utilizadas.
• Não remova código morto pré-existente a menos que solicitado.

O teste: Cada linha alterada deve rastrear diretamente para a solicitação do usuário.

4. Execução Orientada por Objetivo

Defina critérios de sucesso. Faça loop até verificado.

Para tarefas com múltiplos passos, declare um plano breve:

1. [Passo] → verificar: [checagem]
2. [Passo] → verificar: [checagem]
3. [Passo] → verificar: [checagem]

Slash command

/karpathy-check — Execute a revisão completa dos 4 princípios em suas mudanças staged.

Ferramentas Python (scripts/)

Todas as ferramentas são somente stdlib. Execute com --help.

Sub-agente

karpathy-reviewer — Executa todos os 4 princípios contra um diff. Despachado por /karpathy-check ou manualmente antes de commitar.

Hook pré-commit

hooks/karpathy-gate.sh — executa complexity_checker.py e diff_surgeon.py em arquivos staged. Avisa (não bloqueante) quando violações são encontradas. Conecte via .claude/settings.json ou Husky.

Referências

• references/karpathy-principles.md — as citações fonte, contexto mais profundo, quando relaxar cada princípio
• references/anti-patterns.md — 10+ exemplos antes/depois em Python, TypeScript e shell
• references/enforcement-patterns.md — como conectar hooks, integração CI, adoção pela equipe

Quando relaxar

Estes princípios tendem para cautela sobre velocidade. Para tarefas triviais (correções de typo, one-liners óbvios), use o julgamento. Os princípios importam mais em:

• Implementações não triviais (>20 linhas alteradas)
• Código que você não entende completamente
• Tarefas com múltiplos passos com requisitos pouco claros
• Qualquer coisa que será revisada por humanos

Compatibilidade com ferramentas

Instale via plugin para Claude Code. Para outras ferramentas, copie os princípios para seu arquivo de schema:

Skills relacionadas (encadeadas via context: fork)

• self-eval — pontuação honesta de qualidade após concluir o trabalho
• code-reviewer — revisão de código mais ampla; karpathy-coder foca nas 4 armadilhas específicas de LLM
• llm-wiki — conhecimento composto; karpathy-coder garante que você não complique demais ao construí-lo