---
type: workflow
name: codigo-limpo
description: Workflow oficial de Código Limpo e Refatoração baseado nas 12 Regras Canônicas (Dispatch Tables, SRP, DRY, Escoteiro)
scope: global
updatedAt: "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

1. **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.

2. **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.

3. **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:**
     ```ts
     const acoesStatus: Record<StatusLicenca, (licenca: Licenca) => void> = {
       [StatusLicenca.APROVADA]: emitirCertificado,
       [StatusLicenca.PENDENTE]: solicitarDocumentos,
       [StatusLicenca.CANCELADA]: arquivarProcesso,
     }
     acoesStatus[status]?.(licenca)
     ```
   - **Retornar dados e configurações:**
     ```ts
     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):**
     ```vue
     <component :is="mapaComponentes[tipoAtual]" :dados="dadosItem" />
     ```

### II. Funções e Métodos

4. **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.

5. **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 { ... }`).

6. **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

7. **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.

8. **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`.

9. **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

10. **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.

11. **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.

12. **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)
```

1. **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).
2. **Planejar:** Defina a estrutura de arquivos e despacho. Não quebre contratos de API, props de componentes ou regras de negócio.
3. **Executar:** Refatore passo a passo, substituindo condicionais por Dispatch Tables e extraindo composables/helpers conforme necessário.
4. **Validar:**
   - Execute `biome check --write <arquivos>` para formatar.
   - Valide limite de linhas: `sh .agent/verificar-linhas.sh`.
   - Assegure tipagem estrita (zero `any`).
5. **Entregar:** Apresente os problemas encontrados, as regras aplicadas e o código final refatorado pronto para uso.