O CLAUDE.md inspirado em Karpathy ultrapassa as 15K estrelas: como um ficheiro Markdown pode domar os maus hábitos da IA ao escrever código

Um projecto GitHub chamado andrej-karpathy-skills, com apenas um único ficheiro Markdown, ultrapassa as 15.000 estrelas e torna-se um dos projectos open source mais populares no ecossistema do Claude Code. Este ficheiro CLAUDE.md baseia-se nas observações de Andrej Karpathy, antigo director-geral de IA da Tesla, sobre erros comuns ao escrever código com LLM, transformando-as em directrizes comportamentais que o Claude Code pode utilizar directamente.

Os vícios mais comuns de programação com LLM, observados por Karpathy

Karpathy aponta que, ao escrever código, os LLM cometem alguns erros previsíveis: excesso de engenharia (over-engineering), ignorar padrões existentes no código e adicionar dependências onde elas não são necessárias. Estes não são erros aleatórios, mas sim desvios sistemáticos resultantes da forma como o modelo é treinado — o modelo tende a apresentar soluções “inteligentes”, e não opções mais simples que se enquadrem no contexto do projecto.

A ideia-chave é a seguinte: uma vez que estes erros são previsíveis, podem ser evitados com instruções correctas. Esta é a aplicação prática do “feedforward” no Harness Engineering — definir regras antes de a IA agir, em vez de corrigir depois.

Como um ficheiro Markdown muda o comportamento da IA

O CLAUDE.md é um ficheiro de configuração a nível de projecto para o Claude Code. Quando o colocas na pasta raiz do projecto, o Claude Code lê-o e segue automaticamente as instruções nele contidas sempre que é iniciado. Este ficheiro transforma as observações de Karpathy em quatro princípios centrais:

Execução orientada por objectivos — transformar directivas imperativas em objectivos declarativos, em conjunto com um ciclo de validação

Não assumir — quando surgem situações incertas, é necessário confirmar primeiro, e não adivinhar

Não esconder a confusão — se não se compreender o requisito, é obrigatório expressá-lo com clareza

Expor ativamente os trade-offs — quando existem várias opções, apresentar as respectivas vantagens e desvantagens

Estes princípios parecem conselhos para engenheiros humanos, mas no contexto da IA o seu significado é diferente. O comportamento por defeito dos LLM é “produzir respostas o mais completas possível”, mesmo que isso implique adivinhar a intenção do utilizador ou fazer over-design. O CLAUDE.md direciona estes comportamentos predefinidos para uma postura mais prudente.

A tendência por detrás de 15K estrelas: uma nova forma de Prompt Engineering

O sucesso explosivo deste projecto reflecte uma mudança na comunidade de programadores: evoluir de “usar IA para escrever código” para “a engenharia do comportamento da IA faz com que a qualidade do código melhore”. No passado, o prompt engineering focava-se no desenho de prompts para uma única conversa; agora, o foco está nas directrizes comportamentais persistentes — definir uma vez e produzir efeito a longo prazo.

Isto também está alinhado com uma dimensão do Vibe Coding que ainda não foi suficientemente discutida: quando 92% dos programadores nos EUA já estão a utilizar ferramentas de programação com IA, a qualidade do código deixa de depender apenas das capacidades do modelo e passa a depender de como “geres” o comportamento deste parceiro de IA. Um bom CLAUDE.md pode ser mais eficaz do que escolher um modelo mais forte.

O projecto foi criado pelo programador forrestchang, é 100% open source e, além do ficheiro principal CLAUDE.md, também disponibiliza versões que podem ser instaladas como Skills do Claude Code.

Este artigo “CLAUDE.md inspirado por Karpathy ultrapassa 15K estrelas: como um ficheiro Markdown pode domar os maus hábitos de escrever código com IA” apareceu pela primeira vez em 链新闻 ABMedia.