2026-09-16 15:28:18 -03:00

6.4 KiB

Raw Blame History

type	name	description	scope	updatedAt
workflow	codigo-limpo	Workflow oficial de Código Limpo e Refatoração baseado nas 12 Regras Canônicas (Dispatch Tables, SRP, DRY, Escoteiro)	global	2026-09-16

Workflow: /codigo-limpo (Guia das 12 Regras de Código Limpo)

Workflow oficial de limpeza, refatoração e otimização de código para projetos TypeScript, Vue 3, TSX e JSX no ecossistema Azteca.

💡 Comando rápido: Execute /codigo-limpo <arquivo_ou_modulo> para inspecionar, diagnosticar e refatorar o código sob as 12 regras canônicas. (Alias retrocompatível: /otimizar-codigos).

As 12 Regras Canônicas do Código Limpo

I. Nomenclatura e Clareza

Nomes significativos e sem "Números Mágicos": Variáveis, funções e classes devem revelar explicitamente sua intenção. Substitua valores soltos (ex.: status === 4 ou timeout 86400000) por constantes ou enums tipados e legíveis (ex.: status === STATUS_PAGO, TEMPO_EXPIRACAO_MS = 24 * HORA_MS). O nome deve dispensar explicações secundárias.
O código deve explicar a si mesmo: Evite comentários redundantes que apenas parafraseiam o que o código faz. Use comentários e JSDoc exclusivamente para explicar o porquê de uma decisão técnica complexa, regras de negócio ou referenciar a Wiki Dev (wiki/dev/<modulo>/). O código limpo é a única fonte real da verdade.

Prefira Mapeamento (Dispatch Tables) a Switch/If-Else encadeados: Evite tripas de condicionais (if/else if/else ou switch volumosos). Sempre que associar chaves/status a ações, configurações ou componentes, crie um Objeto de Mapeamento (Dispatch Table) fortemente tipado:

Executar funções/ações:

const acoesStatus: Record<StatusLicenca, (licenca: Licenca) => void> = {
  [StatusLicenca.APROVADA]: emitirCertificado,
  [StatusLicenca.PENDENTE]: solicitarDocumentos,
  [StatusLicenca.CANCELADA]: arquivarProcesso,
}
acoesStatus[status]?.(licenca)

Retornar dados e configurações:

const CONFIG_VARIANTE: Record<TipoAlerta, { cor: string; icone: Component }> = {
  erro: { cor: 'var(--cor-eli-erro)', icone: AlertTriangle },
  sucesso: { cor: 'var(--cor-eli-sucesso)', icone: CheckCircle2 },
}

Renderizar componentes (Vue/TSX):

<component :is="mapaComponentes[tipoAtual]" :dados="dadosItem" />

II. Funções e Métodos

Funções devem ser pequenas: Uma função deve ter responsabilidade única: fazer apenas uma coisa, fazê-la bem, e fazer apenas ela. Se ultrapassar 25 a 30 linhas ou contiver múltiplos níveis de indentação, extraia blocos em funções auxiliares ou composables.
Reduza o número de parâmetros: O ideal é que uma função receba zero, um ou no máximo dois argumentos. Caso precise de três ou mais parâmetros, agrupe-os em um Objeto de Parâmetros tipado via interface, type ou schema Zod (interface FiltroParams { ... }).
Não crie efeitos colaterais (Side Effects Ocultos): Uma função não deve modificar estado global, mutar parâmetros recebidos ou alterar variáveis fora do seu escopo de forma oculta. Prefira funções puras e imutabilidade; o escopo da ação deve estar transparente em seu nome e tipo de retorno.

III. Estrutura e Design

Princípio DRY (Don't Repeat Yourself): Elimine duplicação lógica e estrutural. Se o mesmo trecho, cálculo ou padrão de interface existe em 2 ou mais lugares, transforme-o em uma função utilitária, composable (use*.ts), constante compartilhada ou componente reutilizável.
Responsabilidade Única (SRP) e Limite de 250 Linhas: Uma classe, módulo ou componente deve ter apenas um motivo para mudar. Nunca misture acesso a banco de dados, regras de negócio e renderização de UI no mesmo arquivo.
- Limite rígido: Nenhum arquivo pode ultrapassar 250 linhas (verificar-linhas.sh).
- Se um componente crescer, desmembre em pasta com index.vue + SecaoX.vue + *.mapeadores.ts + *.css.
Formatação e Padronização Automatizada: O código do projeto deve parecer ter sido escrito por uma única pessoa. Sempre valide a formatação com o Biome (biome check --write), respeitando aspas simples, sem ponto e vírgula supérfluo, indentação de 2 espaços e regras de lint estritas.

IV. Tratamento e Qualidade

Trate erros com elegância e visibilidade: Nunca silencie erros com blocos catch vazios (catch (_) {}). Sempre registre contexto técnico suficiente (console.error) e exiba feedback compreensível ao usuário via Toast/Banner (ver feedback-visivel.md). Lance exceções semânticas ou retorne tipos Result discriminados em vez de -1 ou null arbitrário.
Testes devem ser limpos e independentes: Código de teste é cidadão de primeira classe. Cada teste deve focar em um único cenário, rodar rápido, ser determinístico e nunca depender do resultado ou ordem de execução de outro teste.
A Regra do Escoteiro: "Deixe a área de acampamento mais limpa do que como a encontrou." Toda vez que abrir um arquivo para corrigir um bug ou criar uma funcionalidade, faça ao menos uma melhoria estrutural: remova um import inútil, renomeie uma variável críptica, extraia uma constante ou desfaça uma condicional encadeada.

Protocolo de Execução do /codigo-limpo

Quando o workflow for acionado, siga as etapas:

1. DIAGNOSTICAR ──▶ 2. PLANEJAR ──▶ 3. EXECUTAR ──▶ 4. VALIDAR ──▶ 5. ENTREGAR
(12 Regras)       (Decomposição)   (Cirúrgico)      (Biome/Tests)   (Relatório)

Diagnosticar: Inspecione o código-alvo mapeando cada violação entre as 12 regras (ex.: status == 2 sem constante, if/switch encadeado, funções > 30 linhas, arquivo > 250 linhas).
Planejar: Defina a estrutura de arquivos e despacho. Não quebre contratos de API, props de componentes ou regras de negócio.
Executar: Refatore passo a passo, substituindo condicionais por Dispatch Tables e extraindo composables/helpers conforme necessário.
Validar:
- Execute biome check --write <arquivos> para formatar.
- Valide limite de linhas: sh .agent/verificar-linhas.sh.
- Assegure tipagem estrita (zero any).
Entregar: Apresente os problemas encontrados, as regras aplicadas e o código final refatorado pronto para uso.

6.4 KiB Raw Blame History