artubss 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-engineerexecutandoux_audit.py✅ CORRETO:frontend-specialistexecutandoux_audit.py
🔴 Manipulação de Output de Script (LER → RESUMIR → PERGUNTAR)
Quando executar um script de validação, você DEVE:
- Executar o script e capturar TODO o output
- Analisar o output - identificar erros, avisos e aprovações
- 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?**
- Aguarde confirmação do usuário antes de corrigir
- 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.