Clean Code - Padrões Pragmáticos de Codificação com IA

HABILIDADE CRÍTICA - Seja conciso, direto e focado em solução.

---

Princípios Essenciais

Princípio	Regra
SRP	Responsabilidade Única - cada função/classe faz UMA coisa
DRY	Don't Repeat Yourself - extraia duplicatas, reutilize
KISS	Keep It Simple - a solução mais simples que funciona
YAGNI	You Aren't Gonna Need It - não construa recursos não usados
Boy Scout	Deixe o código mais limpo do que encontrou

---

Regras de Nomenclatura

Elemento	Convenção
Variáveis	Revele intenção: userCount não n
Funções	Verbo + substantivo: getUserById() não user()
Booleanos	Forma de pergunta: isActive, hasPermission, canEdit
Constantes	SCREAMING_SNAKE: MAX_RETRY_COUNT

Regra: Se você precisa de um comentário para explicar um nome, renomeie.

---

Regras de Função

Regra	Descrição
Pequena	Máx 20 linhas, idealmente 5-10
Uma Coisa	Faz uma coisa, faz bem
Um Nível	Um nível de abstração por função
Poucos Args	Máx 3 argumentos, prefira 0-2
Sem Efeitos Colaterais	Não mute inputs inesperadamente

---

Estrutura de Código

Padrão	Aplique
Guard Clauses	Early returns para casos extremos
Flat > Nested	Evite aninhamento profundo (máx 2 níveis)
Composição	Funções pequenas compostas juntas
Colocalização	Mantenha código relacionado perto

---

Estilo de Codificação com IA

Situação	Ação
Usuário pede feature	Escreva diretamente
Usuário relata bug	Corrija, não explique
Requisito não claro	Pergunte, não assuma

---

Anti-Padrões (NÃO FAÇA)

❌ Padrão	✅ Solução
Comente cada linha	Delete comentários óbvios
Helper para one-liner	Inline do código
Factory para 2 objetos	Instanciação direta
utils.ts com 1 função	Coloque código onde é usado
"Primeiro importamos..."	Apenas escreva código
Aninhamento profundo	Guard clauses
Números mágicos	Constantes nomeadas
God functions	Divida por responsabilidade

---

🔴 Antes de Editar QUALQUER Arquivo (PENSE PRIMEIRO!)

Antes de alterar um arquivo, pergunte-se:

Pergunta	Por Quê
O que importa este arquivo?	Pode quebrar
O que este arquivo importa?	Mudanças de interface
Quais testes cobrem isto?	Testes podem falhar
É um componente compartilhado?	Múltiplos lugares afetados

Verificação Rápida:

Arquivo a editar: UserService.ts
└── Quem importa isto? → UserController.ts, AuthController.ts
└── Precisam de mudanças também? → Verifique assinaturas de função

🔴 Regra: Edite o arquivo + todos os arquivos dependentes na MESMA tarefa. 🔴 Nunca deixe imports quebrados ou atualizações faltando.

---

Resumo

Faça	Não Faça
Escreva código diretamente	Escreva tutoriais
Deixe o código se auto-documentar	Adicione comentários óbvios
Corrija bugs imediatamente	Explique a correção primeiro
Inline coisas pequenas	Crie arquivos desnecessários
Nomeie as coisas claramente	Use abreviações
Mantenha funções pequenas	Escreva funções com 100+ linhas

Lembre-se: O usuário quer código funcionando, não uma aula de programação.

---

🔴 Auto-verificação Antes de Completar (OBRIGATÓRIO)

Antes de dizer "tarefa concluída", verifique:

Verificação	Pergunta
✅ Meta atingida?	Fiz exatamente o que o usuário pediu?
✅ Arquivos editados?	Modifiquei todos os arquivos necessários?
✅ Código funciona?	Testei/verifiquei a mudança?
✅ Sem erros?	Lint e TypeScript passam?
✅ Nada esquecido?	Casos extremos faltando?

🔴 Regra: Se QUALQUER verificação falhar, corrija antes de completar.

---

Scripts de Verificação (OBRIGATÓRIO)

🔴 CRÍTICO: Cada agente executa APENAS os scripts de sua própria habilidade após concluir o trabalho.

Mapeamento Agente → Script

Agente	Script	Comando
frontend-specialist	UX Audit	python ~/.claude/skills/frontend-design/scripts/ux_audit.py .
frontend-specialist	A11y Check	python ~/.claude/skills/frontend-design/scripts/accessibility_checker.py .
backend-specialist	API Validator	python ~/.claude/skills/api-patterns/scripts/api_validator.py .
mobile-developer	Mobile Audit	python ~/.claude/skills/mobile-design/scripts/mobile_audit.py .
database-architect	Schema Validate	python ~/.claude/skills/database-design/scripts/schema_validator.py .
security-auditor	Security Scan	python ~/.claude/skills/vulnerability-scanner/scripts/security_scan.py .
seo-specialist	SEO Check	python ~/.claude/skills/seo-fundamentals/scripts/seo_checker.py .
seo-specialist	GEO Check	python ~/.claude/skills/geo-fundamentals/scripts/geo_checker.py .
performance-optimizer	Lighthouse	python ~/.claude/skills/performance-profiling/scripts/lighthouse_audit.py <url>
test-engineer	Test Runner	python ~/.claude/skills/testing-patterns/scripts/test_runner.py .
test-engineer	Playwright	python ~/.claude/skills/webapp-testing/scripts/playwright_runner.py <url>
Any agent	Lint Check	python ~/.claude/skills/lint-and-validate/scripts/lint_runner.py .
Any agent	Type Coverage	python ~/.claude/skills/lint-and-validate/scripts/type_coverage.py .
Any agent	i18n Check	python ~/.claude/skills/i18n-localization/scripts/i18n_checker.py .

❌ ERRADO: test-engineer executando ux_audit.py ✅ CORRETO: frontend-specialist executando ux_audit.py

---

🔴 Manipulação de Output de Script (LER → RESUMIR → PERGUNTAR)

Quando executar um script de validação, você DEVE:

1. Executar o script e capturar TODO o output
2. Analisar o output - identificar erros, avisos e aprovações
3. Resumir para o usuário neste formato:

## Resultados do Script: [script_name.py]

### ❌ Erros Encontrados (X itens)
- [Arquivo:Linha] Descrição do erro 1
- [Arquivo:Linha] Descrição do erro 2

### ⚠️ Avisos (Y itens)
- [Arquivo:Linha] Descrição do aviso

### ✅ Aprovado (Z itens)
- Verificação 1 aprovada
- Verificação 2 aprovada

**Devo corrigir os X erros?**

4. Aguarde confirmação do usuário antes de corrigir
5. Após corrigir → Re-execute o script para confirmar

🔴 VIOLAÇÃO: Executar script e ignorar output = TAREFA FALHA. 🔴 VIOLAÇÃO: Auto-corrigir sem perguntar = Não permitido. 🔴 Regra: Sempre LER output → RESUMIR → PERGUNTAR → depois corrigir.