affaan-m--everything-claude-code/docs/pt-BR/rules/coding-style.md

# Estilo de Código

## Imutabilidade (CRÍTICO)

SEMPRE crie novos objetos, NUNCA modifique os existentes:

```
// Pseudocódigo
ERRADO:  modificar(original, campo, valor) → altera o original in-place
CORRETO: atualizar(original, campo, valor) → retorna nova cópia com a alteração
```

Justificativa: Dados imutáveis previnem efeitos colaterais ocultos, facilita a depuração e permite concorrência segura.

## Organização de Arquivos

MUITOS ARQUIVOS PEQUENOS > POUCOS ARQUIVOS GRANDES:
- Alta coesão, baixo acoplamento
- 200-400 linhas típico, 800 máximo
- Extrair utilitários de módulos grandes
- Organizar por recurso/domínio, não por tipo

## Tratamento de Erros

SEMPRE trate erros de forma abrangente:
- Trate erros explicitamente em cada nível
- Forneça mensagens de erro amigáveis no código voltado para UI
- Registre contexto detalhado de erro no lado do servidor
- Nunca engula erros silenciosamente

## Validação de Entrada

SEMPRE valide nas fronteiras do sistema:
- Valide toda entrada do usuário antes de processar
- Use validação baseada em schema onde disponível
- Falhe rapidamente com mensagens de erro claras
- Nunca confie em dados externos (respostas de API, entrada do usuário, conteúdo de arquivo)

## Checklist de Qualidade de Código

Antes de marcar o trabalho como concluído:
- [ ] O código é legível e bem nomeado
- [ ] Funções são pequenas (< 50 linhas)
- [ ] Arquivos são focados (< 800 linhas)
- [ ] Sem aninhamento profundo (> 4 níveis)
- [ ] Tratamento adequado de erros
- [ ] Sem valores hardcoded (use constantes ou config)
- [ ] Sem mutação (padrões imutáveis usados)