name: ai-problems-detection description: Protocolo de autodiagnostico contra os 5 problemas mais comuns da IA ao programar. Detecta overengineering, codigo duplicado, reinvencao da roda, falta de documentacao e arquivos monoliticos. Use SEMPRE antes de implementar, ao planejar mudancas, quando criar funcoes novas, ao escrever codigo, para revisar implementacoes. Palavras-chave - simples, duplicado, repetido, existe, separar, modular, documentacao, complexo, refatorar, engenharia demais, roda, reutilizar. allowed-tools: Read, Grep, Glob, Bash, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__perplexity__perplexity_ask, mcp__perplexity__perplexity_search
AI Problems Detection - Protocolo Anti-Erros da IA
MISSAO
Executar 5 verificacoes OBRIGATORIAS antes de escrever qualquer codigo novo. Cada verificacao corresponde a um problema cronico da IA ao programar. Se qualquer verificacao falhar, PARAR e corrigir antes de prosseguir.
REGRA DE OURO
╔═══════════════════════════════════════════════════════════════════╗
║ ANTES DE ESCREVER CODIGO, PERGUNTE: ║
║ ║
║ 1. Tem um jeito mais simples? (Overengineering) ║
║ 2. Alguem ja fez isso? (Reinventando a roda) ║
║ 3. Tem documentacao pra isso? (Nao sabe fazer) ║
║ 4. Esse codigo ja existe no projeto? (Codigo duplicado) ║
║ 5. Deveria separar em mais arquivos? (Tudo no mesmo lugar) ║
║ ║
║ Se respondeu SIM a qualquer uma → PARAR e resolver primeiro ║
╚═══════════════════════════════════════════════════════════════════╝
CHECKLIST RAPIDO (Usar antes de CADA implementacao)
□ SIMPLICIDADE: A solucao mais simples que funciona foi considerada?
□ REUTILIZACAO: Busquei no codebase por codigo similar existente?
□ DOCUMENTACAO: Consultei docs oficiais da lib/API envolvida?
□ DUPLICACAO: Verifiquei se funcao/logica similar ja existe no projeto?
□ MODULARIDADE: O arquivo destino ja esta grande demais (>300 linhas)?
PROBLEMA 1: OVERENGINEERING
Sintomas
- Criar abstracoes para uso unico
- Adicionar configurabilidade desnecessaria
- Implementar patterns (Factory, Strategy, Observer) onde um
ifbastaria - Criar classes onde funcoes simples resolveriam
- Adicionar camadas de indirection sem beneficio claro
- Preparar para "requisitos futuros" que ninguem pediu
Protocolo de Deteccao
ANTES de implementar, responder:
## TESTE DE SIMPLICIDADE
1. NECESSIDADE REAL
- Quantos lugares vao usar isso? → Se 1, nao abstrair
- Existe requisito futuro CONCRETO? → Se nao, YAGNI
- O stakeholder pediu isso? → Se nao, nao fazer
2. ALTERNATIVA SIMPLES
- Consegue resolver com uma funcao simples? → Preferir
- Consegue resolver com 3 linhas inline? → Melhor ainda
- Precisa de classe/pattern? → Provavelmente nao
3. TESTE DO "E SE EU NAO FIZER?"
- O que acontece se eu NAO criar essa abstração? → Se nada, nao crie
- O codigo funciona sem essa camada extra? → Se sim, remova
Exemplos Concretos (Super Cartola)
// OVERENGINEERED: Factory pattern para criar um tipo de objeto
class ParticipanteFactory {
static create(type, data) {
switch(type) {
case 'normal': return new Participante(data);
case 'admin': return new AdminParticipante(data);
default: throw new Error('Unknown type');
}
}
}
// SIMPLES: Funcao direta que resolve
function criarParticipante(data) {
return { ...data, ativo: true, temporada: getCurrentTemporada() };
}
// OVERENGINEERED: Middleware configuravel generico
function createValidator(schema, options = {}) {
return (req, res, next) => {
const { strict = true, partial = false, transform = false } = options;
// 50 linhas de logica generica...
};
}
// SIMPLES: Validacao direta no controller
function validarAcertoFinanceiro(req, res, next) {
const { valor, tipo } = req.body;
if (!valor || !tipo) return res.status(400).json({ error: 'Campos obrigatorios' });
next();
}
Comando de Verificacao
# Detectar sinais de overengineering no codigo que estou escrevendo:
# Classes com um unico metodo (funcao bastava)
grep -rn "class.*{" [arquivo] | while read line; do
file=$(echo "$line" | cut -d: -f1)
methods=$(grep -c "async\|function\|=>" "$file" 2>/dev/null)
if [ "$methods" -le 2 ]; then
echo " Classe com poucos metodos (funcao bastava?): $file"
fi
done
# Patterns desnecessarios
grep -rn "Factory\|Strategy\|Observer\|Singleton\|Builder" --include="*.js" .
# Arquivos de config com uma unica opcao
find . -name "config*.js" -exec wc -l {} \; | awk '$1 < 10'
PROBLEMA 2: REINVENTANDO A RODA
Sintomas
- Implementar manualmente o que uma lib ja faz
- Criar funcoes utilitarias que o JS nativo ja tem
- Reescrever logica de formatacao/validacao existente
- Implementar HTTP client custom quando fetch/axios existe
- Criar sistema de cache quando ja existe no projeto
Protocolo de Deteccao
ANTES de implementar, verificar em 3 niveis:
## TESTE DE REUTILIZACAO
### NIVEL 1: JavaScript Nativo
Verificar se o JS/Node ja tem:
- Array methods: map, filter, reduce, find, some, every, flat, flatMap
- Object methods: entries, keys, values, assign, fromEntries
- String methods: includes, startsWith, padStart, replaceAll
- Date: toLocaleDateString, Intl.DateTimeFormat
- Estruturas: Map, Set, WeakMap, WeakRef
- Utils: structuredClone, crypto.randomUUID, URL, URLSearchParams
### NIVEL 2: Dependencias do Projeto
Verificar no package.json o que JA esta instalado:
```bash
cat package.json | jq '.dependencies, .devDependencies'
NIVEL 3: Documentacao Externa
Se precisa de algo que nao tem no projeto:
// Buscar docs oficiais
mcp__context7__resolve_library_id({ query: "[funcionalidade]", libraryName: "[lib]" })
mcp__context7__query_docs({ libraryId: "[id]", query: "[funcionalidade especifica]" })
// Buscar alternativas existentes
mcp__perplexity__perplexity_ask({
messages: [{ role: "user", content: "Node.js: melhor forma de fazer [X] sem reinventar a roda" }]
})
### Exemplos Concretos
```javascript
// REINVENTANDO: Funcao custom de deep clone
function deepClone(obj) {
if (typeof obj !== 'object') return obj;
const clone = Array.isArray(obj) ? [] : {};
for (const key in obj) {
clone[key] = deepClone(obj[key]);
}
return clone;
}
// JA EXISTE: JS nativo
const clone = structuredClone(obj);
// REINVENTANDO: Formatar moeda manualmente
function formatarMoeda(valor) {
return 'R$ ' + valor.toFixed(2).replace('.', ',').replace(/\B(?=(\d{3})+(?!\d))/g, '.');
}
// JA EXISTE: Intl nativo
const formatarMoeda = (valor) =>
new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' }).format(valor);
// REINVENTANDO: Rate limiter custom
const requests = {};
function checkRateLimit(ip) {
if (!requests[ip]) requests[ip] = { count: 0, lastReset: Date.now() };
// 30 linhas de logica...
}
// JA EXISTE NO PROJETO: express-rate-limit (package.json)
const rateLimit = require('express-rate-limit');
const limiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 100 });
Comandos de Verificacao
# Verificar se funcao que vou criar ja existe como metodo nativo
# Buscar no MDN/Node.js docs via Context7
# Verificar dependencias instaladas
cat package.json | jq -r '.dependencies | keys[]' 2>/dev/null
# Buscar funcoes utilitarias ja existentes no projeto
grep -rn "function format\|function parse\|function valid\|function calc" \
--include="*.js" utils/ helpers/ services/ lib/ 2>/dev/null
# Verificar se padrao ja implementado
grep -rn "module.exports" utils/ helpers/ lib/ 2>/dev/null | head -20
PROBLEMA 3: NAO SABE FAZER (E INVENTA)
Sintomas
- Usar API/metodo com parametros errados
- Implementar com base em "memoria" ao inves de docs
- Confundir versoes de frameworks
- Assumir comportamento sem verificar
- Gerar codigo que parece certo mas nao funciona
Protocolo de Deteccao
ANTES de usar qualquer API/lib/metodo desconhecido:
## TESTE DE CONHECIMENTO
1. SEI EXATAMENTE como isso funciona?
- SIM com certeza → Prosseguir
- ACHO que sei → PARAR, consultar docs
- NAO sei → PARAR, pesquisar antes
2. QUAL a versao da lib no projeto?
```bash
cat package.json | jq '.dependencies["[lib]"]'
-
CONSULTAR documentacao oficial:
// Docs de frameworks (Context7) mcp__context7__resolve_library_id({ query: "[funcionalidade]", libraryName: "[lib]" }) mcp__context7__query_docs({ libraryId: "[id]", query: "[uso especifico]" }) -
CONSULTAR informacoes nao-documentadas:
// API Cartola, comportamentos especificos (Perplexity) mcp__perplexity__perplexity_ask({ messages: [{ role: "user", content: "[pergunta tecnica especifica]" }] })
### Exemplos Concretos
```javascript
// INVENTADO: Parametros errados do MongoDB
await collection.findOneAndUpdate(
{ _id: id },
{ $set: data },
{ returnOriginal: false } // ERRADO: opcao obsoleta
);
// VERIFICADO NA DOC: Opcao correta
await collection.findOneAndUpdate(
{ _id: id },
{ $set: data },
{ returnDocument: 'after' } // CORRETO: driver v4+
);
// INVENTADO: Assume que fetch retorna JSON direto
const data = await fetch('/api/dados');
console.log(data.nome); // undefined! fetch retorna Response, nao JSON
// VERIFICADO: Uso correto
const response = await fetch('/api/dados');
const data = await response.json();
console.log(data.nome);
Sinais de Alerta (Parar e Verificar)
PARAR IMEDIATAMENTE quando perceber:
- Usando metodo que "acho" que existe
- Passando parametros "que devem estar certos"
- Copiando pattern de outro projeto sem adaptar
- Usando sintaxe que "lembro" mas nao tenho certeza
- Escrevendo try/catch "por garantia" sem saber o erro
Comandos de Verificacao
# Verificar versao real das dependencias
node -e "console.log(require('[lib]/package.json').version)"
# Verificar como o projeto JA usa determinada lib
grep -rn "require.*[lib]\|from.*[lib]" --include="*.js" . | head -10
# Ver exemplos reais de uso no codebase
grep -rn "[metodo]" --include="*.js" controllers/ services/ | head -10
PROBLEMA 4: CODIGO DUPLICADO
Sintomas
- Copiar-colar funcoes entre arquivos
- Reescrever logica que ja existe em outro modulo
- Criar helpers identicos em diferentes partes
- Repetir validacoes em multiplos controllers
- Duplicar queries MongoDB com pequenas variacoes
Protocolo de Deteccao
ANTES de escrever qualquer funcao nova:
## TESTE DE DUPLICACAO
1. BUSCAR funcao similar no projeto:
```bash
# Por nome de funcao similar
grep -rn "function [nomeSimilar]\|[nomeSimilar]\s*=" --include="*.js" .
# Por logica similar (palavras-chave do que a funcao faz)
grep -rn "[palavraChave1].*[palavraChave2]" --include="*.js" .
# Por operacao similar no MongoDB
grep -rn "\.find\|\.aggregate\|\.updateMany" --include="*.js" . | grep "[collection]"
-
SE ENCONTRAR codigo similar:
- E identico? → REUTILIZAR (importar)
- E 80% similar? → GENERALIZAR em funcao compartilhada
- E 50% similar? → Avaliar se vale extrair parte comum
- E <50% similar? → OK criar nova funcao
-
ONDE COLOCAR codigo compartilhado:
- Logica de negocio → services/
- Utilitarios puros → utils/ ou helpers/
- Validacoes → middleware/
- Formatacao → utils/formatters.js
### Exemplos Concretos (Super Cartola)
```javascript
// DUPLICADO: Mesmo calculo em 3 controllers diferentes
// controllers/rankingController.js
function calcularPontos(rodadas) {
return rodadas.reduce((acc, r) => acc + (r.pontos || 0), 0);
}
// controllers/participanteController.js
function somarPontos(listaRodadas) {
return listaRodadas.reduce((total, rod) => total + (rod.pontos || 0), 0);
}
// SOLUCAO: Extrair para utils compartilhado
// utils/calculos.js
function calcularPontosTotal(rodadas) {
return rodadas.reduce((acc, r) => acc + (r.pontos || 0), 0);
}
module.exports = { calcularPontosTotal };
// DUPLICADO: Query MongoDB repetida com pequenas variacoes
// Em 5 controllers diferentes:
const participantes = await db.collection('times').find({
liga_id: ligaId,
temporada: temporada,
ativo: true
}).toArray();
// SOLUCAO: Funcao no service
// services/participanteService.js
async function getParticipantesAtivos(ligaId, temporada) {
return await db.collection('times').find({
liga_id: ligaId,
temporada: temporada,
ativo: true
}).toArray();
}
Comandos de Verificacao
# Buscar funcoes com nomes similares ao que vou criar
grep -rn "function.*[palavraChave]" --include="*.js" . | grep -v node_modules
# Buscar logica de calculo similar
grep -rn "reduce\|forEach\|map" --include="*.js" controllers/ services/ | grep "[operacao]"
# Buscar queries MongoDB similares
grep -rn "\.find(\|\.findOne(\|\.aggregate(" --include="*.js" . | grep "[collection]"
# Detectar duplicacao com ferramentas (se disponivel)
npx jscpd --min-lines 5 --min-tokens 50 controllers/ services/ 2>/dev/null
PROBLEMA 5: TUDO NO MESMO LUGAR
Sintomas
- Arquivo crescendo alem de 300 linhas
- Misturar UI, logica de negocio e acesso a dados
- Controller fazendo tudo (rota + validacao + query + resposta)
- Frontend com fetch + calculo + DOM manipulation no mesmo lugar
- Funcoes que nao se relacionam juntas no mesmo arquivo
Protocolo de Deteccao
ANTES de adicionar codigo a um arquivo existente:
## TESTE DE MODULARIDADE
1. TAMANHO DO ARQUIVO DESTINO:
```bash
wc -l [arquivo-destino]
- < 200 linhas → OK adicionar
- 200-300 linhas → Avaliar se pertence ali
- 300-500 linhas → Considerar separar ANTES de adicionar
-
500 linhas → OBRIGATORIO separar (usar skill Refactor-Monolith)
-
RESPONSABILIDADES NO ARQUIVO:
# Contar tipos de operacao no arquivo echo "=== ANALISE DE RESPONSABILIDADES ===" echo "Manipulacao DOM: $(grep -c 'getElementById\|querySelector\|innerHTML\|classList' [arquivo])" echo "Fetch/API: $(grep -c 'fetch\|axios\|XMLHttp' [arquivo])" echo "Calculo/Logica: $(grep -c 'function calc\|function process\|function compute\|reduce\|Math\.' [arquivo])" echo "Event handlers: $(grep -c 'addEventListener\|onclick\|onchange' [arquivo])" echo "MongoDB: $(grep -c '\.find\|\.insert\|\.update\|\.delete\|\.aggregate' [arquivo])"- Se > 2 tipos de responsabilidade → Candidato a separacao
-
A FUNCAO QUE VOU ADICIONAR:
- Pertence a MESMA responsabilidade do arquivo? → OK
- E uma responsabilidade DIFERENTE? → Criar arquivo separado
- Sera usada por OUTROS arquivos? → Colocar em local compartilhado
### Exemplos Concretos
```javascript
// MONOLITO: Controller fazendo TUDO
router.post('/acerto', async (req, res) => {
// Validacao (deveria ser middleware)
if (!req.body.valor) return res.status(400).json({ error: 'Valor obrigatorio' });
// Logica de negocio (deveria ser service)
const saldo = await calcularSaldoAtual(req.params.ligaId, req.body.timeId);
const novoSaldo = saldo + req.body.valor;
// Acesso a dados (deveria ser repository/model)
await db.collection('acertofinanceiros').insertOne({
liga_id: req.params.ligaId,
time_id: req.body.timeId,
valor: req.body.valor,
data: new Date()
});
// Formatacao de resposta (deveria ser separado)
res.json({
sucesso: true,
saldoAnterior: formatarMoeda(saldo),
saldoAtual: formatarMoeda(novoSaldo)
});
});
// SEPARADO: Cada camada com sua responsabilidade
// middleware/validators.js → validarAcerto
// services/acertoService.js → registrarAcerto
// controllers/acertoController.js → orquestrar
router.post('/acerto', validarAcerto, acertoController.registrar);
Quando Separar vs Quando Manter Junto
## DECISAO: SEPARAR OU NAO?
### SEPARAR QUANDO:
- Arquivo > 300 linhas
- > 2 responsabilidades distintas
- Funcao reutilizada em 2+ lugares
- Equipes diferentes mexem no mesmo arquivo
- Teste unitario fica dificil
### MANTER JUNTO QUANDO:
- Arquivo < 200 linhas
- Tudo fortemente acoplado
- Unico consumidor
- Separar criaria mais complexidade que simplificaria
- So 1 pessoa mexe no arquivo
### NUNCA:
- Criar arquivo com 1 funcao de 10 linhas
- Separar por "padrao" sem beneficio concreto
- Criar camada de abstração que so repassa chamadas
Comandos de Verificacao
# Listar arquivos grandes (candidatos a separacao)
find . -name "*.js" ! -path "./node_modules/*" -exec wc -l {} \; | \
sort -rn | awk '$1 > 300 {print " " $1 " linhas: " $2}' | head -15
# Analisar responsabilidades de um arquivo especifico
echo "=== RADIOGRAFIA: [arquivo] ==="
echo "Total linhas: $(wc -l < [arquivo])"
echo "Funcoes: $(grep -c 'function\|=>' [arquivo])"
echo "DOM: $(grep -c 'getElementById\|querySelector\|innerHTML' [arquivo])"
echo "API: $(grep -c 'fetch\|axios' [arquivo])"
echo "DB: $(grep -c '\.find\|\.insert\|\.update\|\.aggregate' [arquivo])"
echo "Events: $(grep -c 'addEventListener\|on[A-Z]' [arquivo])"
FLUXO COMPLETO DE VERIFICACAO
Antes de Escrever Qualquer Codigo Novo
┌─────────────────────────────────┐
│ RECEBEU TAREFA DE IMPLEMENTAR │
└──────────────┬──────────────────┘
│
▼
┌──────────────────────────────────┐
│ 1. SIMPLICIDADE │
│ Tem jeito mais simples? │
│ → Se SIM: usar o mais simples │
└──────────────┬───────────────────┘
│
▼
┌──────────────────────────────────┐
│ 2. EXISTENCIA NO PROJETO │
│ Ja existe algo similar? │
│ → Se SIM: reutilizar/adaptar │
└──────────────┬───────────────────┘
│
▼
┌──────────────────────────────────┐
│ 3. DOCUMENTACAO │
│ Sei como fazer ou preciso docs? │
│ → Se NAO SEI: consultar antes │
└──────────────┬───────────────────┘
│
▼
┌──────────────────────────────────┐
│ 4. DUPLICACAO │
│ Vou repetir codigo existente? │
│ → Se SIM: extrair pra compartilhar│
└──────────────┬───────────────────┘
│
▼
┌──────────────────────────────────┐
│ 5. MODULARIDADE │
│ Arquivo destino esta grande? │
│ → Se SIM: separar primeiro │
└──────────────┬───────────────────┘
│
▼
┌──────────────────────────────────┐
│ TODAS AS 5 VERIFICACOES OK? │
│ → AGORA pode escrever codigo │
└──────────────────────────────────┘
INTEGRACAO COM OUTRAS SKILLS
| Problema Detectado | Skill para Resolver |
|---|---|
| Arquivo > 500 linhas | /Refactor-Monolith |
| Nao sei como API funciona | /fact-checker + Context7 |
| Codigo com vulnerabilidades | /code-inspector |
| Preciso de docs da API Cartola | /cartola-api |
| Feature complexa precisa planejamento | /workflow → /pesquisa → /spec → /code |
| Frontend precisa de padrao | /frontend-crafter |
METRICAS DE QUALIDADE
Indicadores de que o protocolo esta funcionando
- Zero funcoes duplicadas criadas
- Zero libs reinventadas
- Zero APIs usadas com parametros errados
- Todos arquivos < 500 linhas
- Toda funcao nova justificada (nao e overengineering)
Indicadores de que o protocolo FALHOU
grep -rnencontrou funcao quase identica em outro arquivo- Erro em producao por API/metodo usado errado
- Arquivo cresceu 200+ linhas de uma vez
- Criou abstraction layer que ninguem usa
- Implementou algo que
npm install [lib]resolvia
STATUS: AI PROBLEMS DETECTION - SELF-DIAGNOSTIC PROTOCOL ACTIVE
Versao: 1.0
Principio: "Codigo que nao precisa existir e o melhor codigo."