CLAUDE.md: as 4 cláusulas do Karpathy e a 5ª que a comunidade adicionou

O Andrej Karpathy resolveu um problema chato com uma cara nova: o Claude Code, em vez de te perguntar quando a tarefa está ambígua, assume sozinho — e sai escrevendo. Toca código que não devia. Cria abstração que ninguém pediu. Em projeto real, isso vira retrabalho.

A resposta dele não foi um plugin nem um modelo novo. Foi um arquivo de texto: o claude.md. Quatro cláusulas curtas que o agente lê antes de você digitar a primeira palavra. O post mais votado da semana no r/ClaudeAI (1434 ups) pegou essas quatro cláusulas e adicionou uma quinta — e é a quinta que mais muda o comportamento do agente na prática.

Neste guia você vai entender o que é o claude.md, as quatro cláusulas que o Karpathy usa, a quinta que a comunidade descobriu, e vai sair com um arquivo pronto pra colar no seu projeto.

TL;DR

• O que é: claude.md é o arquivo de instruções que o Claude Code lê no início de cada sessão — um system prompt persistente do seu projeto.
• Stack: Claude Code (CLI/IDE). Funciona com qualquer linguagem.
• Custo/Acesso: o arquivo é gratuito; você já tem se usa Claude Code.
• O que muda: quatro cláusulas do Karpathy contra erros de raciocínio + uma quinta da comunidade que tira o agente do modo passivo.

O que é o claude.md (e por que ele importa)

O claude.md é um arquivo de texto na raiz do projeto que o Claude Code carrega automaticamente no começo de toda sessão. Pensa nele como um system prompt versionado junto com o código: antes de qualquer prompt seu, o agente já leu as regras da casa.

Isso resolve um problema concreto. Sem claude.md, você repete as mesmas instruções toda vez — "não mexe no que não pedi", "pergunta antes de assumir", "não inventa abstração". Com o arquivo, isso vira contexto fixo. O agente carrega na memória de trabalho a cada sessão, sem você gastar token repetindo.

O detalhe que o Karpathy acertou: as regras dele não são de formatação. Não tem "use 2 espaços de indentação" nem "comente cada função". São regras de raciocínio — atacam os jeitos que o modelo erra quando está raciocinando sobre a sua intenção. É por isso que funcionam. Segundo relatos da comunidade que reproduziram o setup, o conjunto de regras derrubou a taxa de erro do Claude Code de 41% para 11% nas tarefas testadas (AI Builder Club). Número pra pegar com pinça — varia com o projeto — mas a direção é clara: regra de raciocínio rende mais que regra de estilo.

As 4 cláusulas do Karpathy

O Karpathy postou as quatro no X depois de mapear os erros que mais batia de frente no Claude Code. Cada uma mira uma falha específica.

1. Ask, don't assume. Se algo está ambíguo, pergunte antes de escrever uma linha. Declare suas premissas. Apresente as interpretações possíveis em vez de escolher uma no escuro.

Corrige: o modelo assume a intenção errada e corre com ela em silêncio. Você só descobre depois de 80 linhas escritas.

2. Simplest solution first. Sempre a solução mais simples que resolve. Nada de feature além do que foi pedido, nada de camada configurável que ninguém solicitou, nada de abstração pra código que roda uma vez só.

Corrige: overengineering. O agente adora "deixar preparado pro futuro" e te entrega três interfaces onde uma função bastava.

3. Don't touch unrelated code. Se um arquivo ou função não faz parte da tarefa, não mexe — mesmo que dê pra melhorar. Mudança cirúrgica. Código morto você sinaliza, não deleta por conta própria.

Corrige: scope creep. O diff que devia ter 10 linhas vem com 200 e um refactor que você não pediu no meio.

4. Flag uncertainty explicitly. Se não está confiante sobre uma abordagem ou um detalhe técnico, diz isso antes de seguir. E, no lugar de microgerenciar passo a passo, dê critério de sucesso. Como o próprio Karpathy resumiu: "don't tell it what to do, give it success criteria" — LLM é excelente em iterar até bater uma meta clara.

Corrige: confiança falsa. O modelo apresenta um chute com a mesma cara de quem tem certeza, e você confia.

Repara no padrão: todas atacam o momento em que o agente decide sozinho algo que devia ter trazido pra você. Esse é o calcanhar do trabalho com agente. Não é o código — é a decisão silenciosa antes do código.

A 5ª cláusula: a que a comunidade descobriu

Aqui é onde o post do r/ClaudeAI sai do "copiei o Karpathy" e vira contribuição de verdade.

O usuário Osi32 rodou as quatro cláusulas por um tempo e bateu num efeito colateral: com todas elas ativas, o agente ficou obediente demais. Seguia as instruções à risca, mas parou de questionar abordagem ruim. Se você pedia algo de um jeito subótimo, ele fazia daquele jeito — calado. As regras 1 a 4 dizem "não assuma, não invente, não exagere". O lado ruim é que elas também ensinam o agente a não te confrontar.

A quinta cláusula reabre essa porta:

I'm always open to ideas on better ways to do things.
Please suggest a better way or one with long-lasting impact.

Em português, "estou sempre aberto a ideias melhores; sugira um jeito melhor ou um com impacto duradouro". Parece bobo. Mas muda o comportamento de um jeito que as outras quatro não conseguem: ela convida o desafio. Em vez de um executor que cumpre ordem, você ganha um par técnico que olha pro seu pedido e diz "dá pra fazer, mas tem um caminho que envelhece melhor — quer ver?".

A thread (94 comentários, 96% de aprovação) chegou num consenso interessante: as quatro cláusulas do Karpathy seguram o agente pra ele não fazer besteira; a quinta solta ele de novo, só que na direção certa. Uma freia, a outra acelera. É a combinação que faz o claude.md parecer um colega sênior em vez de um estagiário assustado.

Mão na massa: um claude.md que o Claude Code obedece

Junta tudo e cola na raiz do projeto, num arquivo chamado CLAUDE.md:

# Como trabalhar neste projeto

## Antes de codar
- Se a tarefa estiver ambígua, pergunte antes de escrever qualquer linha.
- Declare suas premissas. Se houver mais de uma interpretação, liste e espere eu escolher.

## Ao escrever
- Solução mais simples primeiro. Sem feature, abstração ou opção que eu não pedi.
- Não toque em código fora da tarefa. Mudança cirúrgica. Código morto: sinalize, não delete.

## Confiança e direção
- Se não estiver confiante, diga isso antes de seguir.
- Trabalhe por critério de sucesso, não por passo a passo microgerenciado.

## Postura
- Estou sempre aberto a ideias melhores. Sugira um caminho melhor
  ou um com impacto mais duradouro, mesmo que contrarie meu pedido.

Três coisas que valem ouro na hora de aplicar:

Escreva em português se seu time é BR. O Claude Code lê o arquivo no idioma que você escrever. As cláusulas do Karpathy circulam em inglês, mas não tem ganho em manter o inglês se o resto do projeto é em português. Mantenha consistente.

Conheça a hierarquia. O Claude Code lê um ~/.claude/CLAUDE.md global (vale pra todo projeto) e o CLAUDE.md da raiz do projeto (vale só ali). Regra de raciocínio como essas cinco cláusulas é forte candidata ao global — você quer esse comportamento em tudo. Regra específica de stack (versão de PHP, convenção do framework) fica no do projeto. Em base grande, dá pra ir além e usar CLAUDE.md em camadas por subpasta pra não estourar contexto.

Curto vence longo. A tentação é encher o arquivo de regra. Não faça. Cada linha que você adiciona compete por atenção com as outras. Cinco cláusulas afiadas valem mais que trinta diluídas. Se uma regra nunca é desrespeitada, ela está ocupando espaço à toa — tira.

Limitações e pontos de atenção

O claude.md é instrução, não trava de execução. O agente lê e tende a obedecer, mas não é garantia de hardware — em sessão longa, com o contexto cheio, o peso dessas regras dilui. Se a tarefa é crítica, reforce no prompt; não terceirize 100% pro arquivo.

Tem também o custo de contexto. Tudo que está no claude.md entra em toda sessão e consome token. Um arquivo de 50 linhas é desprezível; um de 500, com listas de convenção que ninguém lê, é desperdício que ainda por cima afoga as regras que importam.

E não confunda claude.md com documentação. Ele não é o lugar pra explicar a arquitetura do sistema inteiro — é o lugar pra dizer como o agente deve se comportar. Arquitetura vai em doc, em código, em ADR. No claude.md vai postura.

FAQ rápido

Onde fica o arquivo? Na raiz do projeto, chamado CLAUDE.md. O Claude Code também lê um global em ~/.claude/CLAUDE.md e arquivos em subpastas, que se somam ao da raiz.

Funciona com outras ferramentas além do Claude Code? As cláusulas são agnósticas — a ideia de regra de raciocínio vale pra qualquer agente de código. O nome do arquivo e o carregamento automático são específicos do Claude Code; em outras ferramentas você adapta o mecanismo (regras do Cursor, system prompt, etc.).

Preciso das cinco cláusulas? Não. Comece com as quatro do Karpathy, rode uns dias e veja se o agente está passivo demais. Se estiver, adiciona a quinta. claude.md é iterativo: você ajusta conforme apanha.

Tem exemplo pronto pra copiar? O bloco da seção "Mão na massa" acima já é um claude.md exemplo funcional. Cola, ajusta o tom pro seu projeto e segue.

Conclusão

O claude.md é a prova de que a parte mais barata de melhorar um agente nem sempre é o modelo — às vezes são cinco linhas de texto bem postas. As quatro cláusulas do Karpathy seguram o agente nos pontos onde ele decide sozinho e erra. A quinta, da comunidade, devolve a ele a liberdade de te confrontar quando seu pedido tem um caminho melhor. Juntas, transformam o Claude Code de executor obediente em par técnico.

Mas escrever as regras que um agente obedece é só o primeiro nível. O próximo é construir o harness em volta dele — a estrutura que decide quando ele pergunta, quando age, como recebe contexto e onde é avaliado. É exatamente esse salto, do prompt pro harness de produção, que a gente constrói de ponta a ponta no workshop Do Prompt ao Harness: construindo um Agent de Vendas, montando um agente de vendas real do zero. Se este post te fez olhar com outros olhos pro claude.md, esse é o passo seguinte natural.

Começa pequeno: cola as cinco cláusulas, abre o Claude Code e repara na diferença na primeira tarefa ambígua. Você vai ver o agente perguntar onde antes ele teria assumido. É aí que o trabalho com IA deixa de ser sorte e vira engenharia.