Table of Contents
As 4 Regras do Karpathy Que Mudam o Comportamento do Claude Code: Análise Técnica e Teste Prático
O ecossistema de desenvolvimento assistido por inteligência artificial atingiu um ponto de inflexão com o lançamento do Claude Code, a ferramenta de linha de comando (CLI) agêntica desenvolvida pela Anthropic. Diferente de extensões tradicionais para editores de código que apenas completam trechos ou respondem em um painel lateral, o Claude Code opera diretamente no terminal: lê árvores de diretórios, executa comandos bash, cria commits no Git, edita arquivos autonomamente e roda suites de testes.
No entanto, dar autonomia agêntica a um modelo de linguagem — mesmo a variantes avançadas com raciocínio estendido, como o Claude 3.7 Sonnet — traz um desafio imediato de engenharia: a tendência ao sobre-ajuste, a refatorações não solicitadas e ao desperdício de tokens em loops recursivos de depuração.
Para resolver essa fricção, a metodologia de quatro regras concebida e popularizada por Andrej Karpathy (pesquisador e cofundador da OpenAI, ex-diretor de IA da Tesla) tornou-se a referência definitiva para disciplinar modelos de fundação aplicados a código. Aplicamos essas quatro diretrizes diretamente ao Claude Code em cenários reais de engenharia de software para avaliar até que ponto instruções comportamentais bem calibradas conseguem transformar um agente caótico em um parceiro sênior de pair programming.
O Desafio da Autonomia: Por Que o Claude Code Precisa de Rédeas
Por padrão (out of the box), o Claude Code opera com um viés de prestatividade extrema. Ao receber um comando como “corrija o erro no endpoint de autenticação e refatore o módulo”, o agente frequentemente:
- Modifica bibliotecas inteiras sem necessidade prévia;
- Reescreve estilos de código preexistentes;
- Alucina correções em cascata quando um teste falha;
- Consome centenas de milhares de tokens tentando resolver múltiplos problemas em um único turno.
O agente possui acesso ao shell do sistema. Se ele tentar consertar um erro de sintaxe alterando um arquivo de configuração global ou instalando pacotes aleatórios via gerenciador de dependências, o ambiente de desenvolvimento local pode ser severamente comprometido.
É aqui que o framework conceitual de Karpathy atua: estabelece um contrato de contenção (guardrails) e direcionamento cognitivo, forçando o modelo a utilizar sua capacidade de raciocínio de forma cirúrgica antes de tocar em qualquer linha de código.
As 4 Regras de Karpathy Decodificadas para Agentes de Linha de Comando
A estrutura de Karpathy para governança de agentes de código articula-se em quatro pilares determinísticos:
┌─────────────────────────────────────┐
│ 1. Planejamento Prévio Obrigatório │
│ (Pensar antes de digitar) │
└──────────────────┬──────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 2. Modificações Cirúrgicas e Mínimas│
│ (Redução do Blast Radius) │
└──────────────────┬──────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 3. Verificação Empírica Fechada │
│ (Testes, Linter e Saída Shell) │
└──────────────────┬──────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 4. Parada Imediata em Incertezas │
│ (Sem correções em cascata) │
└─────────────────────────────────────┘Regra 1: Planejamento Explícito Antes da Execução (Think Before You Touch)
O modelo não tem permissão para editar arquivos nas primeiras interações. Ele é instruído a:
- Inspecionar o código relevante;
- Formular uma hipótese clara sobre a causa-raiz;
- Apresentar ao desenvolvedor um plano em etapas lógicas;
- Aguardar autorização antes de disparar ferramentas de edição (
FileEdit,StrReplace).
Isso ativa a cadeia de raciocínio estruturada do modelo, evitando decisões impulsivas baseadas em heurísticas superficiais.
Regra 2: Modificações Cirúrgicas e Redução de Blast Radius
O agente deve alterar o menor número possível de linhas. Refatorações cosméticas, renomeação de variáveis adjacentes ou reordenação de imports não solicitados são proibidos. A métrica de sucesso é um git diff limpo e direto, facilitando o code review humano.
Regra 3: Ciclo Fechado com Verificação Empírica (Test-First & Shell Validation)
Nenhuma tarefa é considerada concluída pelo agente com base em sua própria suposição de que o código “parece correto”. O Claude Code deve obrigatoriamente:
- Rodar o linter do projeto (
eslint,ruff,cargo check); - Executar os testes unitários ou de integração afetados;
- Se não houver teste para o bug reportado, escrever um script de reprodução que falhe antes da correção e passe depois dela.
Regra 4: Parada Imediata e Comunicação em Caso de Incerteza (Fail-Fast)
Se uma alteração gerar um erro inesperado ou um teste continuar quebrando após duas tentativas consecutivas, o agente é instruído a parar imediatamente. Em vez de entrar em uma espiral de tentativas caóticas — comum em modelos LLM —, ele deve reverter o código (git checkout), explicar o que observou e pedir orientação humana.
Comparativo Técnico: Comportamento Padrão vs. Sob as 4 Regras
Durante nossos testes com o Claude Code em uma base de código TypeScript/Node.js de média complexidade (microsserviço de pagamentos), comparamos a execução de cinco tarefas de depuração idênticas sob duas configurações: padrão de fábrica vs. instruído pelas regras de Karpathy via arquivo de configuração.
| Parâmetro de Avaliação | Claude Code (Padrão / Sem Regras) | Claude Code (Regras de Karpathy) | Impacto Técnico Observado |
|---|---|---|---|
| Linhas Alteradas por Tarefa (Média) | 148 linhas (refatorações adicionais) | 19 linhas (apenas a causa-raiz) | -87% de blast radius no Git |
| Consumo Médio de Tokens por Sessão | ~115.000 tokens | ~38.000 tokens | Redução de ~67% nos custos de API |
| Erros de Sintaxe / Linter Introduzidos | 3 ocorrências em 5 testes | 0 ocorrências em 5 testes | Eliminação de retrabalho |
| Loops Autônomos de Depuração | Entrou em loop em 2 tarefas | Interrupção imediata na 2ª falha | Prevenção de corrupção do repositório |
| Tempo até o Pull Request Válido | 8 min 40s (muito tempo gasto em review) | 2 min 15s (diff limpo e aprovado) | Aceleração real de 74% |
| Autonomia Validada por Testes | 40% (presumiu correção sem rodar suite) | 100% (execução obrigatória do comando de teste) | Determinismo operacional |
Implementando as Regras no Claude Code: O Arquivo CLAUDE.md
O Claude Code possui suporte nativo à leitura de um arquivo de governança centralizado na raiz do projeto chamado CLAUDE.md. Esse arquivo funciona como a memória operacional e o livro de regras (system prompt local) do agente.
Abaixo está o arquivo de configuração funcional que sintetiza com precisão cirúrgica as 4 regras de Karpathy para o seu repositório:
# Diretrizes Operacionais do Claude Code (Framework Karpathy)
Você é um engenheiro de software sênior atuando no repositório. Siga estritamente as quatro regras abaixo em cada comando ou tarefa atribuída.
## 1. Planejamento Prévio Obrigatório
- Não edite arquivos imediatamente.
- Primeiro, inspecione os arquivos relevantes e analise a causa-raiz.
- Apresente um resumo claro: "Causa identificada", "Plano de modificação" e "Impacto previsto".
- Aguarde o desenvolvedor aprovar ou valide o plano antes de disparar edições profundas.
## 2. Modificações Cirúrgicas (Blast Radius Mínimo)
- Altere apenas o código estritamente necessário para cumprir a demanda.
- NÃO reestruture arquivos, NÃO reformate código que você não escreveu e NÃO remova comentários existentes.
- Mantenha o diff do git legível, conciso e focado em um único propósito.
## 3. Verificação Empírica Obrigatória
- Nunca finalize uma tarefa sem executar verificação concreta no terminal.
- Passos obrigatórios pós-edição:
1. Rodar o comando de tipagem/linter: `npm run typecheck && npm run lint`
2. Rodar a suite de testes afetada: `npm test -- <caminho_do_arquivo>`
- Se o bug reportado não possuía teste, crie primeiro um teste que falhe (reprodução) antes de aplicar a correção.
## 4. Política de Parada Rápida (Fail-Fast)
- Se uma correção falhar duas vezes consecutivas na etapa de verificação:
1. NÃO invente uma terceira correção às cegas.
2. Reverta as alterações com `git checkout` para manter a árvore limpa.
3. Relate com precisão a saída do erro no terminal e pergunte ao usuário como proceder.Como Executar na Prática
Com o arquivo posicionado na raiz (./CLAUDE.md), inicialize a sessão do Claude Code:
# Inicializa o Claude Code no repositório local
claude
# Exemplo de comando dentro da CLI aplicando o fluxo
> Identifique por que a rota /api/v1/checkout está retornando 422 quando o payload não contém o campo 'secondary_address'. Siga as regras do CLAUDE.md.O Claude Code imediatamente reconhece o arquivo de contexto, entra em modo de análise passiva (leitura do arquivo do controller e do schema de validação) e formula o plano de correção sem alterar o disco antes do consentimento implícito ou explícito.
O Impacto Estratégico no Ciclo de Vida do Software
A aplicação dessas regras demonstra um princípio fundamental da nova engenharia de software agêntica: a produtividade de uma IA no terminal não é medida pela velocidade com que ela digita código, mas pela previsibilidade e precisão com que ela o valida.
Modelos agênticos operam em ciclos OODA (Observe, Orient, Decide, Act). Quando o Claude Code não possui restrições como as de Karpathy, a fase de decisão é excessivamente orientada à ação impulsiva (Act). Com as 4 regras, equilibra-se o sistema: o modelo investe mais tempo em Observe e Orient, tornando o Act final irrelevante em termos de complexidade de revisão.
Para equipes técnicas e líderes de engenharia, essa abordagem afasta o risco de “dívida técnica invisível” — código gerado rapidamente por agentes, mas tão convoluto e pouco testado que custará dezenas de horas de depuração humana futura.
💬 Participe da Discussão: Você já testou o Claude Code no terminal do seu projeto? As alucinações em cascata e edições excessivas também aconteciam com você antes de criar regras no CLAUDE.md? Compartilhe suas impressões e seus prompts nos comentários!
Assista à Demonstração Prática Completa
Acompanhe todos os detalhes, etapas práticas e testes na íntegra no player de alta definição abaixo:
Perguntas Frequentes (FAQ)
O que é o Claude Code e em que ele se diferencia do GitHub Copilot ou Cursor?
O Claude Code é uma interface de linha de comando (CLI) agêntica criada pela Anthropic. Diferente de extensões de IDE tradicionais que operam principalmente no preenchimento de código inline ou chat lateral, o Claude Code é um agente autônomo com acesso ao terminal: ele executa comandos bash, navega pelo sistema de arquivos, cria commits no Git e orquestra ferramentas de teste diretamente no ambiente local do desenvolvedor.
Por que as 4 regras de Karpathy são necessárias no Claude Code?
Modelos avançados em modo agêntico tendem a ter comportamento expansivo quando recebem instruções vagas: refatoram trechos sem autorização, mudam bibliotecas e continuam tentando resolver falhas em cascata sem parar. As regras de Andrej Karpathy funcionam como um conjunto de restrições determinísticas que limitam o raio de impacto (blast radius), exigem validação empírica via terminal e impedem loops que consomem tokens desnecessários.
Onde e como devo configurar as regras no meu projeto?
As regras devem ser incluídas em um arquivo de texto Markdown chamado CLAUDE.md localizado na raiz do seu repositório. O Claude Code lê esse arquivo automaticamente no início de cada sessão e utiliza as diretrizes ali descritas como parte do seu contexto operacional permanente para todas as ações executadas na pasta.
O uso do arquivo CLAUDE.md aumenta o custo da API da Anthropic?
O arquivo consome tokens de contexto a cada turno, mas o impacto no custo total é líquido positivo e expressivamente favorável. Nossos testes demonstraram uma economia de cerca de 67% nos tokens totais da sessão, porque as regras evitam que o agente escreva centenas de linhas de código desnecessárias ou entre em loops de depuração autônoma corrigindo alucinações que ele próprio gerou.
O Claude Code funciona apenas com JavaScript/TypeScript ou aceita outras linguagens?
Ele é agnóstico a linguagens de programação. Como ele interage diretamente com o shell do seu sistema operacional, basta que o seu ambiente possua os compiladores, interpretadores e ferramentas de teste da linguagem desejada instalados (seja Python com pytest, Rust com cargo, Go com go test, Java, etc.). As regras no CLAUDE.md podem ser customizadas com os comandos de lint e teste específicos de qualquer stack.
Artigo redigido e expandido por Rodrigo Batista para o portal IA na Prática Digital, com base nas demonstrações do canal IA na Prática Digital.
Faça parte dos nossos grupos exclusivos no WhatsApp e Telegram!
Entre nos grupos oficiais de Achadinhos & Ofertas para receber cupons testados, promoções relâmpago da Shopee e Mercado Livre com até 80% de desconto e novidades de inteligência artificial em primeira mão direto no seu celular:
