Um único arquivo CLAUDE.md para melhorar o comportamento de agentes de código e reduzir armadilhas comuns de LLMs ao programar.
Versão em português brasileiro.
LLMs costumam falhar de formas previsíveis:
"Os modelos fazem premissas erradas em seu nome e seguem com elas sem checar. Eles não gerenciam a própria confusão, não pedem esclarecimentos, não expõem inconsistências, não apresentam tradeoffs, não contestam quando deveriam."
"Eles realmente gostam de complicar demais código e APIs, inflar abstrações, não limpam código morto... implementam uma construção inchada com mais de 1000 linhas quando 100 bastariam."
"Ainda às vezes alteram/removem comentários e código que não entendem suficientemente bem como efeito colateral, mesmo que sejam ortogonais à tarefa."
Cinco princípios em um arquivo que atacam esses problemas diretamente:
| Princípio | Ataca |
|---|---|
| Pense Antes de Codar | Premissas erradas, confusão escondida, tradeoffs ausentes |
| Simplicidade em Primeiro Lugar | Excessos de complexidade, abstrações inchadas |
| Mudanças Cirúrgicas | Edições ortogonais, tocar código que não deveria |
| Execução Orientada a Objetivo | Alavancagem via testes primeiro e critérios de sucesso verificáveis |
| Sinalize Incerteza | Palpites como fatos, tom confiante sem conhecimento confiante |
Não assuma. Não esconda confusão. Exponha tradeoffs.
LLMs frequentemente escolhem uma interpretação em silêncio e seguem com ela. Este princípio força raciocínio explícito:
- Declare premissas explicitamente — Se estiver em dúvida, pergunte em vez de adivinhar
- Apresente múltiplas interpretações — Não escolha em silêncio quando houver ambiguidade
- Conteste quando fizer sentido — Se existir uma abordagem mais simples, diga
- Pare quando estiver confuso — Nomeie o que não está claro e peça esclarecimento
O mínimo de código que resolve o problema. Nada especulativo.
Combata a tendência ao overengineering:
- Sem funcionalidades além do que foi pedido
- Sem abstrações para código de uso único
- Sem "flexibilidade" ou "configurabilidade" que não foram solicitadas
- Sem tratamento de erro para cenários impossíveis
- Se 200 linhas poderiam ser 50, reescreva
O teste: Um engenheiro sênior diria que isso está complicado demais? Se sim, simplifique.
Altere apenas o necessário. Limpe só a bagunça que você criou.
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 diferente
- Se notar código morto não relacionado, mencione — não delete
Quando suas mudanças criarem órfãos:
- Remova imports/variáveis/funções que AS SUAS mudanças tornaram não utilizados
- Não remova código morto pré-existente a menos que peçam
O teste: cada linha alterada deve rastrear diretamente ao pedido do usuário.
Defina critérios de sucesso. Itere até verificar.
Transforme tarefas imperativas em objetivos verificáveis:
| Em vez de... | Transforme em... |
|---|---|
| "Adicionar validação" | "Escrever testes para entradas inválidas e fazê-los passar" |
| "Corrigir o bug" | "Escrever um teste que reproduza o bug e fazê-lo passar" |
| "Refatorar X" | "Garantir que os testes passem antes e depois" |
Para tarefas com vários passos, declare um plano breve:
1. [Passo] → verificar: [checagem]
2. [Passo] → verificar: [checagem]
3. [Passo] → verificar: [checagem]
Critérios de sucesso fortes permitem ao LLM iterar de forma independente. Critérios fracos ("faz funcionar") exigem esclarecimentos constantes.
Não apresente palpites como fatos. Quando a confiança for baixa, diga isso.
Quando o conhecimento estiver incompleto, houver alucinação inferida ou algo não verificado:
- Prefacie com "possivelmente", "provavelmente", "não tenho certeza" ou "você deveria verificar isso"
- Distinga o que sabe do que está inferindo
- Se a afirmação exigir verificação externa antes de agir, sinalize explicitamente
- Nunca deixe o tom confiante substituir conhecimento confiante
Quando estiver preenchendo uma lacuna com uma premissa:
- Nomeie a lacuna: "Não tenho visibilidade sobre X, então estou assumindo Y."
- Ofereça parar em vez de adivinhar
- Não esconda a incerteza no final de uma resposta longa e confiante
O teste: um desenvolvedor poderia agir com base nesta resposta e só descobrir o erro depois do dano? Se sim, a incerteza não foi sinalizada com clareza suficiente.
Opção A: Plugin do Claude Code
A partir do Claude Code, adicione o marketplace e instale o plugin:
/plugin marketplace add dgtallab/coding-guidelines
/plugin install coding-guidelines@coding-guidelines
Isso instala as diretrizes como plugin do Claude Code, tornando a skill disponível em todos os seus projetos.
Opção B: CLAUDE.md (por projeto)
Projeto novo:
curl -o CLAUDE.md https://raw.githubusercontent.com/dgtallab/coding-guidelines/main/CLAUDE.mdProjeto existente (anexe):
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/dgtallab/coding-guidelines/main/CLAUDE.md >> CLAUDE.mdEste repositório inclui uma rule de projeto do Cursor (.cursor/rules/coding-guidelines.mdc) para que as mesmas diretrizes se apliquem ao abrir o projeto no Cursor. Veja CURSOR.md para setup, uso da rule em outros projetos e a relação com o Claude Code.
"LLMs são excepcionalmente bons em iterar até atingir objetivos específicos... Não diga o que fazer; dê critérios de sucesso e observe."
O princípio "Execução Orientada a Objetivo" captura isso: transforme instruções imperativas em objetivos declarativos com loops de verificação.
Estas diretrizes estão funcionando se você observar:
- Menos mudanças desnecessárias nos diffs — Só aparecem as mudanças pedidas
- Menos reescritas por excesso de complexidade — O código já nasce simples
- Perguntas de esclarecimento antes da implementação — Não depois dos erros
- PRs limpos e mínimos — Sem refatoração drive-by ou "melhorias"
- Incerteza sinalizada a tempo — Informação duvidosa é marcada antes de causar dano
Estas diretrizes foram pensadas para serem mescladas com instruções específicas do projeto. Adicione-as ao seu CLAUDE.md existente ou crie um novo.
Para regras específicas do projeto, acrescente seções como:
## Diretrizes específicas do projeto
- Use TypeScript em modo strict
- Todos os endpoints de API devem ter testes
- Siga os padrões de tratamento de erro em `src/utils/errors.ts`Estas diretrizes priorizam cautela em vez de velocidade. Em tarefas triviais (typo simples, one-liners óbvios), use o bom senso — nem toda mudança precisa do rigor completo.
O objetivo é reduzir erros caros em trabalho não trivial, não atrasar tarefas simples.
Veja EXAMPLES.md para exemplos concretos do certo e do errado em cada princípio.
MIT