Skip to content

About

Diretrizes comportamentais para reduzir erros comuns de LLMs ao codar (pt-BR)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

Diretrizes de Código

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.

Os problemas

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."

A solução

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

Os cinco princípios em detalhe

1. Pense Antes de Codar

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

2. Simplicidade em Primeiro Lugar

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.

3. Mudanças Cirúrgicas

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.

4. Execução Orientada a Objetivo

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.

5. Sinalize Incerteza

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.

Instalação

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.md

Projeto existente (anexe):

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/dgtallab/coding-guidelines/main/CLAUDE.md >> CLAUDE.md

Usando com o Cursor

Este 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.

Insight principal

"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.

Como saber que está funcionando

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

Customização

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`

Nota sobre o tradeoff

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.

Exemplos

Veja EXAMPLES.md para exemplos concretos do certo e do errado em cada princípio.

Licença

MIT

About

Diretrizes comportamentais para reduzir erros comuns de LLMs ao codar (pt-BR)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors