Skip to content

artubss/SKILLS-CLAUDE-CODE / skills/skills/development/clean-code

clean-code

Unverified

Padrões pragmáticos de codificação - conciso, direto, sem over-engineering, sem comentários desnecessários

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ípioRegra
SRPResponsabilidade Única - cada função/classe faz UMA coisa
DRYDon't Repeat Yourself - extraia duplicatas, reutilize
KISSKeep It Simple - a solução mais simples que funciona
YAGNIYou Aren't Gonna Need It - não construa recursos não usados
Boy ScoutDeixe o código mais limpo do que encontrou

Regras de Nomenclatura

ElementoConvenção
VariáveisRevele intenção: userCount não n
FunçõesVerbo + substantivo: getUserById() não user()
BooleanosForma de pergunta: isActive, hasPermission, canEdit
ConstantesSCREAMING_SNAKE: MAX_RETRY_COUNT

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


Regras de Função

RegraDescrição
PequenaMáx 20 linhas, idealmente 5-10
Uma CoisaFaz uma coisa, faz bem
Um NívelUm nível de abstração por função
Poucos ArgsMáx 3 argumentos, prefira 0-2
Sem Efeitos ColateraisNão mute inputs inesperadamente

Estrutura de Código

PadrãoAplique
Guard ClausesEarly returns para casos extremos
Flat > NestedEvite aninhamento profundo (máx 2 níveis)
ComposiçãoFunções pequenas compostas juntas
ColocalizaçãoMantenha código relacionado perto

Estilo de Codificação com IA

SituaçãoAção
Usuário pede featureEscreva diretamente
Usuário relata bugCorrija, não explique
Requisito não claroPergunte, não assuma

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

❌ Padrão✅ Solução
Comente cada linhaDelete comentários óbvios
Helper para one-linerInline do código
Factory para 2 objetosInstanciação direta
utils.ts com 1 funçãoColoque código onde é usado
"Primeiro importamos..."Apenas escreva código
Aninhamento profundoGuard clauses
Números mágicosConstantes nomeadas
God functionsDivida por responsabilidade

🔴 Antes de Editar QUALQUER Arquivo (PENSE PRIMEIRO!)

Antes de alterar um arquivo, pergunte-se:

PerguntaPor 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çaNão Faça
Escreva código diretamenteEscreva tutoriais
Deixe o código se auto-documentarAdicione comentários óbvios
Corrija bugs imediatamenteExplique a correção primeiro
Inline coisas pequenasCrie arquivos desnecessários
Nomeie as coisas claramenteUse abreviações
Mantenha funções pequenasEscreva 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çãoPergunta
✅ 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

AgenteScriptComando
frontend-specialistUX Auditpython ~/.claude/skills/frontend-design/scripts/ux_audit.py .
frontend-specialistA11y Checkpython ~/.claude/skills/frontend-design/scripts/accessibility_checker.py .
backend-specialistAPI Validatorpython ~/.claude/skills/api-patterns/scripts/api_validator.py .
mobile-developerMobile Auditpython ~/.claude/skills/mobile-design/scripts/mobile_audit.py .
database-architectSchema Validatepython ~/.claude/skills/database-design/scripts/schema_validator.py .
security-auditorSecurity Scanpython ~/.claude/skills/vulnerability-scanner/scripts/security_scan.py .
seo-specialistSEO Checkpython ~/.claude/skills/seo-fundamentals/scripts/seo_checker.py .
seo-specialistGEO Checkpython ~/.claude/skills/geo-fundamentals/scripts/geo_checker.py .
performance-optimizerLighthousepython ~/.claude/skills/performance-profiling/scripts/lighthouse_audit.py <url>
test-engineerTest Runnerpython ~/.claude/skills/testing-patterns/scripts/test_runner.py .
test-engineerPlaywrightpython ~/.claude/skills/webapp-testing/scripts/playwright_runner.py <url>
Any agentLint Checkpython ~/.claude/skills/lint-and-validate/scripts/lint_runner.py .
Any agentType Coveragepython ~/.claude/skills/lint-and-validate/scripts/type_coverage.py .
Any agenti18n Checkpython ~/.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?**
  1. Aguarde confirmação do usuário antes de corrigir
  2. 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.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall