🪓 Exija a menor mudança possível
A IA tende a produzir soluções aparentemente completas, mesmo quando uma solução menor seria suficiente: abstrações prematuras, camadas desnecessárias, interfaces redundantes, frameworks internos, muitos arquivos, configuração excessiva, tratamento de casos hipotéticos.
A regra prática — cole no seu AGENTS.md
Implemente a menor alteração que satisfaça os critérios de aceitação. Não crie novas abstrações, dependências ou camadas sem necessidade comprovada.
Duas frases. É o controle com melhor relação custo-benefício deste curso inteiro.
Como ler: os dois lados passam nos mesmos testes. A diferença aparece daqui a seis meses, quando alguém precisar mudar algo: à esquerda mexe em dois arquivos; à direita precisa entender a fábrica, o registry e a camada de configuração antes de tocar em qualquer linha.
Menor
Que satisfaça o critério
Preservar
A estrutura existente
Justificar
Todo componente novo
Revisável
Diff pequeno é lido
🏗️ Evite abstrações prematuras
Abstração errada custa mais que duplicação: para mudar qualquer coisa, primeiro é preciso desfazer a abstração. E ela chega com aparência de qualidade — nomes bonitos, camadas simétricas, tudo "extensível".
✓ Quando abstrair
- ✓Existem dois ou três usos reais, não previstos
- ✓Os usos variam no mesmo eixo (a abstração captura a variação certa)
- ✓A duplicação já causou um bug de inconsistência
✗ Quando NÃO abstrair
- ✗"Um dia vamos precisar suportar outro provedor"
- ✗Um único uso, com interface criada "por precaução"
- ✗Semelhança superficial: duas coisas parecidas hoje que evoluem separadas
💡 Dica prática
Peça sempre as duas versões: "me mostre a solução simples e a extensível, com o custo de cada uma; recomende uma e diga o que perde". A conversa fica objetiva em trinta segundos — e a resposta costuma ser a simples.
2–3 usos reais
Antes de abstrair
Hipotético
Não é requisito
Errada > duplicada
Em custo
Duas versões
Compare sempre
📦 Controle dependências e arquivos alterados
Cada dependência é superfície de ataque, custo de atualização e risco de abandono. E cada arquivo a mais no diff reduz a chance de alguém revisar de verdade — a partir de certo tamanho, o PR não é revisado: é aceito.
🚦 Controles recomendados
- •Proibir dependência nova sem aprovação explícita.
- •Limitar o número de arquivos alterados por tarefa.
- •Evitar refatoração fora do escopo — vira outro PR.
- •Remover código não utilizado que a mudança deixou órfão.
- •Avaliar o custo de manutenção antes de aceitar a solução.
⚠️ Atenção
Dependência sugerida por IA merece uma checagem extra: ela existe mesmo? está mantida? o nome é o que você espera? Pacote inventado — ou com nome parecido com o real — é vetor conhecido de ataque à cadeia de suprimentos.
Custo permanente
Toda dependência tem
Existe mesmo?
Confira o pacote
Limite de arquivos
Denuncia escopo
Órfão
Remova o que sobrou
👯 Combata a duplicação semântica
É a forma de dívida que a IA mais gera, porque cada tarefa começa sem lembrar do que já existe. O resultado é a terceira função de formatar data, com outro nome, em outro módulo, com outro comportamento de borda.
🧪 Exercício copiável — caçada à duplicação
Objetivo: medir a dívida semântica acumulada no seu repositório. Rode uma vez por trimestre.
Analise <pasta ou repositório> e encontre DUPLICAÇÃO SEMÂNTICA: trechos que resolvem o mesmo problema com implementações diferentes (não copie-e-cola literal). Para cada grupo encontrado, informe: - o que fazem (uma frase); - onde estão (arquivo:linha de cada ocorrência); - as diferenças de comportamento entre elas (especialmente em bordas: nulo, vazio, fuso horário, arredondamento, erro); - qual é a mais completa e por quê; - risco de consolidar (baixo/médio/alto). Não altere nada. Ordene por risco de inconsistência para o usuário final.
Como verificar: escolha o grupo de maior risco e confira as diferenças de borda manualmente. Quase sempre existe pelo menos um caso em que as duas implementações discordam — e esse é um bug que ninguém tinha reportado ainda.
"Já existe?"
Pergunte antes de criar
Bordas
Onde elas discordam
Inconsistência
Vira bug de usuário
Consolidar
Trabalho recorrente
🧪 Desconfie de testes superficiais
Teste que executa o código sem afirmar comportamento relevante dá a pior combinação possível: sensação de segurança com zero proteção — e ainda trava refatorações, por testar a implementação em vez do comportamento.
O teste do "quebre de propósito"
Introduza um bug óbvio na função e rode a suíte. Se nada ficar vermelho, aquele teste não testa nada. É a checagem mais rápida que existe para avaliar testes gerados por IA.
Comportamento, não implementação
Teste que verifica quais métodos internos foram chamados quebra em toda refatoração e não pega defeito nenhum. Teste o que entra e o que sai.
Peça erro e borda, não caminho feliz
Instrua explicitamente: "priorize casos de erro, limites e concorrência; não gere testes redundantes do caminho feliz". Sem isso, você recebe vinte variações do mesmo cenário.
Quebre de propósito
O teste ficou vermelho?
Comportamento
Entrada e saída
Bordas
É onde mora o bug
Teste vazio
É dívida, não ativo
🎭 Detecte o código que viola a intenção
É o defeito mais perigoso do desenvolvimento com IA: a solução que passa nos testes e mesmo assim está errada. Ela atravessa todos os gates automáticos com sinal verde, porque otimizou exatamente para o verificador.
🚩 Sinais no diff
- • Condição que trata especificamente o valor usado no teste.
- • try/catch que engole a exceção e retorna um valor padrão.
- • Cache adicionado "para melhorar desempenho" que na verdade esconde a inconsistência.
- • Verificação removida "porque estava causando falha".
- • Teste antigo alterado no mesmo commit da correção.
Checagem rápida: o agente entregou 18 arquivos, 3 dependências novas e uma camada de abstração — e tudo passa. O que fazer?
Ler o diff
Não só o resultado
Exceção engolida
Bandeira vermelha
Teste alterado
Junto da correção
Métrica-alvo
Deixa de medir
📌 Resumo do Módulo
Próxima trilha:
Trilha 5 - Playbooks, Skills, Rules e Governança: transformar tudo isso em processo reutilizável.