No mundo em rápida evolução da codificação assistida por AI, um repo do GitHub surgiu como o conjunto mais popular de diretrizes comportamentais para agentes de codificação de AI: forrestchang/andrej-karpathy-skills. Criado pelo desenvolvedor Forrest Chang, ele sintetiza as observações virais de Andrej Karpathy sobre as armadilhas de codificação com LLM em um único e prático CLAUDE.md arquivo. Nós o pesquisamos no GitHub, Twitter/X, Reddit, artigos da web e no próprio código-fonte — aqui está o guia definitivo.
Get the latest on AI, LLMs & developer tools
New MCP servers, model updates, and guides like this one — delivered weekly.
🎬 Assista à análise em vídeo
Prefere ler? Continue rolando para o guia escrito completo com exemplos de código.
1. Por que viralizou
Vamos começar pelo motivo deste repositório ser importante. Ele se tornou um dos repositórios de crescimento mais rápido no GitHub — dezenas de milhares de estrelas em suas primeiras semanas — para um repositório que contém essencialmente um único arquivo.
Não é um framework. Nem uma biblioteca. Nem um app. Um único conjunto de diretrizes comportamentais para agentes de codificação de IA. Criado em 27 de janeiro de 2026, lançado sob a licença MIT, e continua crescendo. Isso diz algo importante sobre para onde a indústria está caminhando.
Por que isso importa
Muitas ferramentas open-source populares com milhares de contribuidores e anos de desenvolvimento possuem menos estrelas. Este repo viralizou com um punhado de commits e zero dependências de runtime. O valor não está no código — está nas ideias.
2. A História de Origem
O repo remete diretamente a um tweet viral de Andrej Karpathy — cofundador da OpenAI, ex-líder de IA na Tesla e a pessoa que cunhou o termo “vibe coding.” Em seu post, Karpathy não compartilhou uma ferramenta ou um repo. Ele compartilhou observações — uma lista de frustrações sobre como os LLMs se comportam ao escrever código.
Algumas notas aleatórias do Claude programando bastante nas últimas semanas.
— Andrej Karpathy (@karpathy) 26 de janeiro de 2026
Workflow de programação. Dado o recente salto na capacidade de programação de LLMs, como muitos outros, passei rapidamente de cerca de 80% de programação manual+autocomplete e 20% de agentes em novembro para 80% de programação com agentes e 20% de edições+ajustes em…
O desenvolvedor Forrest Chang leu essas observações e fez algo prático: ele as converteu em um arquivo estruturado e legível por máquina CLAUDE.md arquivo. Não um post vago em um blog. Não uma thread no Twitter. Um arquivo de configuração que agentes de IA realmente leem e seguem.
O insight principal foi este: Karpathy identificou problemas. Forrest Chang codificou soluções. A comunidade validou ambos — tornando-o um dos repositórios de workflow de IA com mais estrelas no GitHub.
3. Os Problemas que Karpathy Identificou
As observações de Karpathy não foram reclamações vagas. Foram padrões específicos e reproduzíveis que todo desenvolvedor que utiliza agentes de codificação de IA já experimentou. Aqui estão suas palavras exatas:
Problema 1: Suposições Ocultas
“Os modelos fazem suposições erradas em seu nome e simplesmente seguem em frente sem verificar. Eles não gerenciam sua confusão, não buscam esclarecimentos, não expõem inconsistências, não apresentam tradeoffs, não questionam quando deveriam.”
Problema 2: Over-Engineering
“Eles realmente gostam de complicar demais o código e as APIs, inflar abstrações, não limpam código morto... implementam uma construção inchada de mais de 1000 linhas quando 100 seriam suficientes.”
Problema 3: Efeitos Colaterais Indesejados
“Eles ainda às vezes alteram/removem comentários e códigos que não entendem suficientemente como efeitos colaterais, mesmo que sejam ortogonais à tarefa.”
Se você já usou Claude Code, Copilot, Cursor ou qualquer agente de codificação de IA, você já sentiu isso. Você pede ao agente para corrigir um bug e ele reescreve metade do arquivo. Você pede para adicionar uma funcionalidade e ele constrói uma camada de abstração inteira. Você pede ajuda e ele avança confiantemente com suposições erradas.
A comunidade do Reddit (especialmente r/ClaudeAI e r/ClaudeCode) tem um termo amplamente utilizado para esse comportamento: “o dev júnior confiante.” A IA é rápida, experiente e propensa a cometer erros ingênuos se não for supervisionada. É brilhante, mas pouco confiável — exatamente o tipo de engenheiro que precisa de proteções claras.
4. Os Quatro Princípios
Forrest Chang destilou as observações de Karpathy em quatro princípios. Cada um aborda diretamente uma classe específica de falha de LLM:
| Princípio | Aborda |
|---|---|
| Pense Antes de Codar | Suposições erradas, confusão oculta, falta de tradeoffs |
| Simplicidade em Primeiro Lugar | Supercomplicação, abstrações inchadas, funcionalidades especulativas |
| Mudanças Cirúrgicas | Edições ortogonais, mexer em código que não deveria, desvio de estilo |
| Execução Focada em Objetivos | Implementação vaga, falta de verificação, critérios de sucesso fracos |
Vamos detalhar cada um deles.
Princípio 1: Pense Antes de Codar
“Não presuma. Não esconda confusão. Exponha os tradeoffs.”
Este é o princípio mais fundamental. LLMs têm a tendência de escolher uma interpretação silenciosamente e seguir com ela. Este princípio força o raciocínio explícito:
- Declare as suposições explicitamente — Se estiver incerto, pergunte em vez de adivinhar
- Apresente múltiplas interpretações — Não escolha silenciosamente quando houver ambiguidade
- Questione quando for justificável — Se existir uma abordagem mais simples, diga
- Pare quando estiver confuso — Nomeie o que não está claro e peça esclarecimentos
Exemplo: A Armadilha das Suposições Ocultas
Solicitação do usuário: “Add a feature to export user data”
def export_users(format='json'):
users = User.query.all()
# Supôs TODOS os usuários, localização do arquivo, campos,
# nomes de campos CSV — sem perguntar nada
Antes de implementar, preciso esclarecer:
1. Escopo: Exportar todos os usuários ou um subconjunto filtrado?
(implicações de privacidade)
2. Formato: Download de arquivo? Job em segundo plano?
Endpoint de API?
3. Campos: Quais campos de usuário?
(alguns podem ser sensíveis)
4. Volume: Quantos usuários normalmente?
Abordagem mais simples: Adicionar um endpoint de API que
retorna JSON paginado. Qual é a sua preferência?
Princípio 2: Simplicidade Primeiro
“Código mínimo que resolve o problema. Nada especulativo.”
Isso combate a tendência do LLM para over-engineering. As regras são rígidas:
- Sem funcionalidades além do que foi solicitado
- Sem abstrações para código de uso único
- Sem “flexibilidade” ou “configurabilidade” que não tenha sido solicitada
- Sem tratamento de erros para cenários impossíveis
- Se 200 linhas pudessem ser 50, reescreva-as
O teste: Um engenheiro sênior diria que isso está excessivamente complicado? Se sim, simplifique.
Exemplo: A Armadilha da Sobre-abstração
Solicitação do usuário: “Adicione uma função para calcular desconto”
class DiscountStrategy(ABC):
@abstractmethod
def calculate(self, amount): ...
class PercentageDiscount(DiscountStrategy): ...
class FixedDiscount(DiscountStrategy): ...
class DiscountConfig: ...
class DiscountCalculator: ...
# mais de 50 linhas para um único cálculo
# O uso requer mais de 30 linhas de configuração
def calculate_discount(amount, percent):
"""Calcula o desconto. percent é de 0 a 100."""
return amount * (percent / 100)
# Uso
discount = calculate_discount(100.0, 10.0) # $10 de desconto
Insight Principal do Repo
“Os exemplos ‘complicados demais’ não estão obviamente errados — eles seguem padrões de design e boas práticas. O problema é timing: eles adicionam complexidade antes que seja necessário.” Um bom código resolve o problema de hoje de forma simples, não o problema de amanhã prematuramente.
Princípio 3: Mudanças Cirúrgicas
“Toque apenas no que for necessário. Limpe apenas a sua própria bagunça.”
Este é o princípio que aborda mais diretamente a frustração de Karpathy com LLMs fazendo mudanças ortogonais. Ao editar código existente:
- Não “melhore” código adjacente, comentários ou formatação
- Não refatore o que não está quebrado
- Siga o estilo existente, mesmo que você fizesse de forma diferente
- Se você notar código morto não relacionado, mencione-o — não o exclua
Quando suas mudanças criarem órfãos:
- Remova imports/variáveis/funções que as SUAS mudanças tornaram sem uso
- Não remova código morto pré-existente, a menos que solicitado
O teste: Cada linha alterada deve estar diretamente ligada à solicitação do usuário.
Exemplo: A Armadilha da Refatoração Drive-By
Solicitação do usuário: “Corrija o bug onde e-mails vazios quebram o validador”
Alterou 15 linhas:
- Adicionou docstring (não solicitado)
- Adicionou validação de username (não solicitado)
- Alterou comentários (não solicitado)
- Lógica de validação de e-mail “melhorada” (não solicitado)
- Adicionou chamadas .strip() em todo lugar (não solicitado)
Alterou 3 linhas:
- Adicionou proteção contra string vazia no e-mail
- Alterou a referência da variável para evitar crash
- Nada mais foi alterado.
Exemplo: A Armadilha do Desvio de Estilo
Solicitação do usuário: “Adicione logging à função de upload”
The LLM adds logging — but also changes single quotes to double quotes, adds type hints nobody asked for, adds a docstring, reformats whitespace, and restructures the boolean return logic. The correct approach: add apenas as linhas de logging, usando o estilo existente (single quotes, no type hints, same spacing).
Princípio 4: Execução Orientada a Objetivos
“Defina critérios de sucesso. Entre em loop até verificar.”
Este princípio resume o que Karpathy considera o insight de maior impacto ao trabalhar com LLMs:
O Insight Principal de Karpathy
“LLMs são excepcionalmente bons em iterar até atingirem objetivos específicos... Não diga a ele o que fazer, dê critérios de sucesso e observe-o agir.”
O princípio transforma tarefas imperativas em objetivos declarativos:
| Em vez de... | Transforme em... |
|---|---|
| “Adicione validação” | “Escreva testes para entradas inválidas e, em seguida, faça-os passar” |
| “Corrija o bug” | “Escreva um teste que o reproduza e, em seguida, faça-o passar” |
| “Refatore X” | “Garanta que os testes passem antes e depois” |
Para tarefas de várias etapas, o modelo deve apresentar um plano breve:
1. [Etapa] → verificar: [check]
2. [Etapa] → verificar: [check]
3. [Etapa] → verificar: [check]
Strong success criteria let the LLM loop
de forma independente. Critérios fracos (“faça funcionar”)
exigem esclarecimentos constantes.
5. O Arquivo CLAUDE.md Real
Aqui está o arquivo completo e integral CLAUDE.md do repositório. Ele é intencionalmente curto — menos de 70 linhas. Essa brevidade é uma funcionalidade, não uma limitação:
Diretrizes comportamentais para reduzir erros comuns de codificação de LLM
Mescle com instruções específicas do projeto
conforme necessário.
Tradeoff: Estas diretrizes priorizam a cautela
em detrimento da velocidade. Para tarefas triviais, use o bom senso.
## 1. Pense Antes de Codificar
Não presuma. Não esconda confusão. Exponha os tradeoffs.
Antes de implementar:
- Declare suas suposições explicitamente. Se estiver incerto, pergunte.
- Se existirem múltiplas interpretações, apresente-as.
- Se existir uma abordagem mais simples, diga.
- Se algo não estiver claro, pare. Nomeie o que é confuso.
## 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” que não tenha sido solicitada.
- Sem tratamento de erros para cenários impossíveis.
- Se 200 linhas puderem ser 50, reescreva.
## 3. Mudanças Cirúrgicas
Toque apenas no que for necessário. Limpe apenas a sua própria bagunça.
- Não “melhore” o código adjacente ou a formatação.
- Não refatore o que não está quebrado.
- Siga o estilo existente, mesmo que você faria de forma diferente.
- Se notar código morto, mencione-o — não o delete.
## 4. Execução Focada em Objetivos
Defina critérios de sucesso. Repita até verificar.
Transforme tarefas em objetivos verificáveis:
- “Adicionar validação” → “Escrever testes, depois fazê-los passar”
- “Corrigir o bug” → “Reproduzi-lo em um teste, depois corrigir”
- “Refatorar X” → “Garantir que os testes passem antes e depois”
É isso. O arquivo inteiro. Seu poder está na concisão — curto o suficiente para caber na janela de contexto do agente sem poluir as instruções específicas do projeto, longo o suficiente para codificar as diretrizes comportamentais críticas.
6. Exemplos do Mundo Real
O repositório inclui um EXAMPLES.md arquivo com comparações detalhadas de antes/depois. Aqui está o principal “resumo de anti-padrões” do arquivo:
| Princípio | Anti-padrão | Correção |
|---|---|---|
| Pense Antes de Programar | Assume silenciosamente o formato do arquivo, campos e escopo | Liste as suposições explicitamente, peça esclarecimentos |
| Simplicidade Primeiro | Padrão Strategy para um único cálculo de desconto | Uma única função até que a complexidade seja realmente necessária |
| Mudanças Cirúrgicas | Reformats quotes, adds type hints while fixing a bug | Altere apenas as linhas que corrigem o problema relatado |
| Orientado a Objetivos | “Vou revisar e melhorar o código” | “Escrever teste para o bug X → fazê-lo passar → verificar se não há regressões” |
7. Como Instalar
O repositório oferece dois métodos de instalação:
Opção A: Plugin do Claude Code (Recomendado)
Isso instala as diretrizes como um plugin do Claude Code, tornando a habilidade disponível em todos os seus projetos:
/plugin marketplace add forrestchang/andrej-karpathy-skills
# Depois, instale o plugin
/plugin install andrej-karpathy-skills@karpathy-skills
Opção B: CLAUDE.md (Por Projeto)
Para um único projeto:
curl -o CLAUDE.md https://raw.githubusercontent.com/
forrestchang/andrej-karpathy-skills/main/CLAUDE.md
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/
andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
Customização
Estas diretrizes foram projetadas para serem mescladas com instruções específicas do projeto. Adicione suas próprias seções para configurações de TypeScript, padrões de API, convenções de teste ou o que quer que seu projeto precise. Os quatro princípios fornecem a base comportamental; as regras do seu projeto são construídas sobre eles.
8. O que é o CLAUDE.md?
Para quem não está familiarizado com o conceito: CLAUDE.md é um Memory Card do Projeto para agentes de codificação de IA. Ele é lido automaticamente pelo Claude Code no início de cada sessão, fornecendo contexto persistente que se mantém entre as conversas.
Pense nisso como o equivalente em IA da documentação de onboarding para um novo desenvolvedor — exceto que a IA a lê todas as vezes que começa a trabalhar no seu projeto.
Melhores Práticas para o CLAUDE.md (2026)
| Seção | Conteúdo |
|---|---|
| Visão Geral do Projeto | Resumo de 2 a 3 frases sobre o que o projeto faz |
| Tech Stack | Linguagens, frameworks, bibliotecas principais |
| Arquitetura | Mapa da codebase (source, components, config) |
| Comandos | comandos de dev, build, test, lint |
| Padrões de Codificação | Convenções de nomenclatura, padrões, regras de estilo |
| Regras de Segurança | “Nunca faça hardcode de chaves de API,” “Não edite /config” |
A Hierarquia
CLAUDE.md(raiz do projeto) — Contexto compartilhado, commitado no GitCLAUDE.local.md(raiz do projeto) — Notas privadas específicas do desenvolvedor (adicione ao .gitignore)~/.claude/CLAUDE.md— Preferências globais em todos os projetos- Subdiretório
CLAUDE.mdarquivos — Contexto carregado apenas ao trabalhar naquele diretório
A regra de ouro: Se você precisar repetir uma instrução no chat mais de duas vezes, promova-a para o seu CLAUDE.md.
9. Reações da Comunidade
Pesquisamos discussões no Reddit (r/ClaudeAI, r/ClaudeCode), Twitter/X e blogs técnicos. Aqui está o que a comunidade pensa:
O Consenso do “Dev Júnior Confiante”
A comunidade do Reddit frequentemente descreve o Claude Code como um brilhante, mas às vezes pouco confiável “desenvolvedor júnior.” Ele é rápido e experiente, mas propenso a tomar atalhos perigosos, alucinar ou cometer erros ingênuos se não for supervisionado. O arquivo de skills do Karpathy aborda isso diretamente, adicionando as guardrails que um dev júnior precisa.
O argumento do “Problema de Habilidade”
Um sentimento predominante no Reddit: a qualidade do código gerado por IA é diretamente proporcional ao próprio julgamento de engenharia do usuário e às habilidades de “context engineering”. Usuários avançados que dominam a estrutura de prompts, o gerenciamento de contexto e loops de verificação relatam taxas de sucesso drasticamente maiores. O arquivo de skills do Karpathy é uma das ferramentas de “context engineering” mais populares.
O debate sobre a “Psicose de IA”
A descrição de Karpathy sobre a “psicose perpétua de IA” — um estado constante de direcionamento de agentes hiperprodutivo, porém exaustivo — ressoou profundamente. Alguns veem os agentes de IA como uma vantagem competitiva que você não pode se dar ao luxo de ignorar. Outros chamam isso de “teatro de produtividade” — sentir-se rápido enquanto produz código de difícil manutenção. O arquivo de skills fica no meio-termo: ele reconhece que os agentes de IA são poderosos, mas argumenta que eles precisam de restrições disciplinadas.
A mudança no gargalo humano
O consenso da comunidade: a IA baixou a barreira para escrever código. Mas o real gargalo mudou da implementação para arquitetura e avaliação. O desafio não é mais “como eu escrevo isso?” mas sim “eu entendo o que o agente acabou de construir o suficiente para mantê-lo?”
10. O panorama geral
De “Vibe Coding” para “Agentic Engineering”
Quando Karpathy cunhou o termo “vibe coding” no início de 2025, ele descrevia uma forma solta e conversacional de dar prompts à IA. Em 2026, a comunidade amadureceu isso para “agentic engineering” — uma disciplina onde desenvolvedores tratam a IA como uma parceira que exige objetivos claros, limites definidos e testes rigorosos.
O andrej-karpathy-skills repo representa essa evolução. Não se trata de limitar o que a IA pode fazer. Trata-se de canalizar o que ela pode fazer através de princípios que produzem resultados melhores.
O Padrão “Idea File”
Este repo também exemplifica o que Karpathy chama de “idea file” padrão — compartilhar ideias em vez de implementações. O CLAUDE.md arquivo não é uma biblioteca que alguém importa. É um conjunto de princípios que qualquer pessoa pode adaptar. O agente do destinatário o customiza para suas necessidades específicas. Este é um novo tipo de open source: não código aberto, mas ideias abertas.
Como saber se está funcionando
Com base no README do repo, estas diretrizes estão funcionando se você notar:
- Menos alterações desnecessárias em diffs — Apenas as alterações solicitadas aparecem
- Menos reescritas devido à complexidade excessiva — O código é simples logo na primeira vez
- Perguntas de esclarecimento vêm antes da implementação — Não depois de erros
- PRs limpos e minimalistas — Sem refatorações de passagem ou “melhorias”
A Nota sobre Tradeoffs
O repo é honesto sobre seus tradeoffs: “Estas diretrizes priorizam a cautela em vez da velocidade.” Para tarefas triviais (correções simples de digitação, one-liners óbvios), use o bom senso — nem toda mudança exige rigor total. O objetivo é reduzir erros dispendiosos em trabalhos não triviais, não atrasar tarefas simples.
11. Todas as Fontes & Links
Este artigo foi pesquisado utilizando pesquisa de múltiplas fontes no GitHub, Twitter/X, Reddit, artigos da web e no próprio código-fonte. Aqui estão todas as fontes primárias:
Fontes Primárias
- GitHub: forrestchang/andrej-karpathy-skills — O próprio repo
- CLAUDE.md — O arquivo de diretrizes real
- EXAMPLES.md — Exemplos reais de antes/depois
- Tweet Original do Karpathy — O post viral identificando armadilhas de codificação com LLM
Discussões da Comunidade
- Reddit r/ClaudeAI — Discussões da comunidade sobre workflows do Claude Code e o consenso do “dev júnior confiante”
- Reddit r/ClaudeCode — Threads sobre melhores práticas do CLAUDE.md e sistemas de especificações
- Twitter/X — Reações de desenvolvedores, compartilhamento de workflows e relatórios de adoção
Fontes da Web
- Medium — Reviews técnicos e guias de implementação
- dev.to — Tutoriais da comunidade de desenvolvedores
- Forbes — Cobertura da evolução do “vibe coding” para a “engenharia agêntica”
- VentureBeat — Análise da analogia de “compilador” de Karpathy para gerenciamento de contexto
- Analytics Vidhya — Análise técnica da abordagem do arquivo de skills
Documentação
- Documentação do Claude Code — Referência oficial do CLAUDE.md
- HumanLayer.dev — Melhores práticas para configuração do CLAUDE.md
Artigos Relacionados neste Site
- Bases de Conhecimento de LLM do Karpathy: O Tweet Original, Explicado
- Wiki de LLM do Karpathy: O Guia Completo para seu Arquivo de Ideias
- Como Configurar Skills em sua IDE de IA
- O Guia Completo de Prompts de Sistema para Agentes de IA
Get the Ultimate Antigravity Cheat Sheet
Join 5,000+ developers and get our exclusive PDF guide to mastering Gemini 3 shortcuts and agent workflows.