MÓDULO 1.3

🔪 Mudanças Cirúrgicas

Toque só no necessário. Cada linha alterada deve rastrear diretamente ao pedido do usuário. Fim do refactor drive-by, da "melhoria" não solicitada, da limpeza alheia.

6
Tópicos
30
Minutos
Básico
Nível
Prática
Tipo
1

🚷 Não mexer no que não pediu

A regra de ouro. Mesmo que o LLM "ache que pode melhorar" código adjacente — não toca. Foco é o pedido. Tudo o mais fica como está.

🎯 Karpathy disse

"Eles às vezes alteram/removem comentários e código que não entendem suficientemente como efeito colateral, mesmo que ortogonal à tarefa."

✓ Diff ideal

// Pedido: adicionar log no fim function pay(amount) { charge(amount); + log('paid', amount); }

3 linhas mexidas, 1 mudança real.

✗ Drive-by refactor

// Mesmo pedido - function pay(amount) { + const pay = (amount) => { - charge(amount); + const result = charge(amount); + log('paid', amount); + return result; - } + };

10 linhas, mudou estilo, retorno, escopo. Review impossível.

💡 Regra simples

Quer melhorar algo fora do escopo? Avise o usuário no final: "Notei que X poderia ser refatorado, quer que eu abra um PR separado?" Nunca no mesmo diff.

2

🎨 Respeitar o estilo existente

Seguir convenções do projeto — nomes, padrões, estilo — mesmo discordando. Inconsistência custa mais do que opinião pessoal.

📋 O que olhar antes de codar

  • Nomes: arquivos vizinhos usam kebab-case ou camelCase?
  • Indentação: 2 ou 4 espaços? Tabs?
  • Comentários: JSDoc? `//`? Português ou inglês?
  • Padrões: usa hooks, classes, factory? Mantém o mesmo.
  • Imports: ordem, agrupamento, aliases.

✓ Mimética estilística

  • ✓Ler 2-3 arquivos próximos antes de escrever
  • ✓Copiar padrões existentes mesmo se "old-school"
  • ✓Mencionar discordância só uma vez, fora do diff

✗ Imposição estilística

  • ✗Trocar `var` por `let` em arquivo que só usa `var`
  • ✗Converter callbacks pra Promises sem pedido
  • ✗Adicionar TypeScript em projeto JS puro
3

☠️ Código morto não relacionado

Se o LLM encontra código aparentemente não usado fora do escopo da tarefa, deve apenas mencionar. Nunca apagar sem permissão. "Não usado" pode ser usado.

⚠️ Por que "código morto aparente" é traiçoeiro

  • • Pode ser chamado por reflexão / strings dinâmicas.
  • • Pode ser usado por outro repo (lib pública).
  • • Pode estar atrás de feature flag, build flag ou env.
  • • Pode ser ponto de extensão documentado externamente.
  • • Pode ter sido feito para um caso futuro real.

🔧 Como reportar (em vez de deletar)

"Durante a tarefa notei: - A função foo() em utils.ts parece sem callers - O componente Banner em /old está com 0 imports - O método legacy() em UserService está marcado @deprecated Posso remover? (Confirme se algum deles ainda é usado externamente.)"

💡 Blast radius

Sempre pergunte: "Se isso aqui sumir, quem chora?" Se a resposta envolve "talvez X", "não tenho certeza Y" — não apaga.

4

🧹 Limpar só os seus órfãos

Quando uma mudança deixa imports, variáveis ou funções sem uso, o LLM remove. Se o órfão é pré-existente, deixa. Bagunça gerada pela mudança é responsabilidade dela.

✓

Removeu uma função → remove imports dela

Se você apagou `helper()`, apaga o `import { helper }` que sobrou.

✓

Renomeou variável → atualize callers no escopo

Não deixe metade do código com nome antigo.

✗

Não toca em imports não usados que já existiam

Eles são problema de outra tarefa. Não inflacione o diff.

Sua bagunça

Você criou → você limpa

Bagunça herdada

Pré-existente → menciona, não mexe

Critério

"Esse órfão existe por causa da minha mudança?"

5

📝 Comentários e formatação adjacentes

Não "melhorar" comentários, espaçamento ou ordem de imports fora da área da mudança. Mudanças cosméticas ofuscam a real no diff.

📊 Signal-to-noise no diff

Reviewer olha um PR com 50 linhas mexidas. Quantas são a mudança real?

  • • 5 linhas: a mudança real.
  • • 20 linhas: reformatação automática.
  • • 15 linhas: ordem de imports "limpa".
  • • 10 linhas: comentários "melhorados".

Resultado: review demora 10x e o reviewer ainda pode passar batido na mudança real.

✓ Permitido

  • ✓Adicionar comentário na linha que você mexeu
  • ✓Corrigir typo num comentário que já estava sendo editado
  • ✓Adicionar import na seção de imports, sem reorganizar tudo

✗ Proibido

  • ✗Reformatar arquivo inteiro automaticamente
  • ✗"Limpar" comentários de outras funções
  • ✗Reordenar imports só por estética
  • ✗Mudar quebra de linha em código não tocado

💡 Respeito ao git blame

Cada linha tem um autor histórico. Reformatar tudo apaga essa história. Daqui 6 meses, ninguém vai conseguir saber por que aquela linha existe — porque o blame vai apontar pra você, e você não escreveu ela.

6

🔍 Rastreabilidade de cada linha

O teste final. Antes de entregar o diff, conferir: cada linha alterada justifica-se pelo pedido?

🎯 Auditoria pré-PR

Para cada linha + ou - no diff: - Por que essa linha foi mexida? - Rastreia ao pedido? - Se não, descarta a mudança. Se sobrar linha sem justificativa → reverte e re-faz só com o necessário.

🔧 Instrução no CLAUDE.md

Antes de finalizar um diff, faça auditoria linha por linha. Cada alteração deve ter uma justificativa direta no pedido original. Linhas sem justificativa → reverter. Se você modificou algo "de passagem", explique explicitamente no resumo do diff, ou desfaça.
Critério

Rastreabilidade 1:1 com pedido

Ferramenta

`git diff` antes de commit

Resultado

PRs enxutos, reviews rápidos, regressões raras

📝Resumo do Módulo

✓
Regra de ouro — não mexer no que não pediu. Refactor adjacente vira PR separado.
✓
Estilo existente — copie convenções vizinhas, mesmo discordando.
✓
Código morto aparente — mencione, nunca delete sem permissão.
✓
Seus órfãos — você criou, você limpa. Herdado, não toca.
✓
Cosmética = ruído — reformatação fora do escopo destrói o diff.
✓
Auditoria pré-PR — cada linha rastreia ao pedido ou some.

Próximo Módulo:

1.4 — 🎯 Execução Orientada a Meta

← Módulo Anterior Próximo Módulo →