From 7c11b08d17e82ec2094571fd5ee996c7137cdea2 Mon Sep 17 00:00:00 2001
From: Luiz Silva <luiz@e-licencie.com.br>
Date: Wed, 16 Sep 2026 15:28:18 -0300
Subject: [PATCH] codigo limpo

---
 .../refatorar/workflows/refatorar-modulo.md   |   2 +-
 global/rules/limite-linhas.md                 |   2 +-
 global/skills/codigo-limpo/SKILL              | 118 ++++++++++++++++++
 global/skills/codigo-limpo/SKILL.md           | 118 ++++++++++++++++++
 global/workflows/codigo-limpo.md              | 103 +++++++++++++++
 global/workflows/otimizar-codigos.md          |  79 +++---------
 manifesto.json                                |   2 +
 rules/limite-linhas.md                        |   2 +-
 skills/codigo-limpo/SKILL                     | 118 ++++++++++++++++++
 skills/codigo-limpo/SKILL.md                  | 118 ++++++++++++++++++
 skills/otimizar-codigos/SKILL.md              |  82 ++++--------
 verificar-linhas.sh                           |   2 +-
 12 files changed, 625 insertions(+), 121 deletions(-)
 create mode 100644 global/skills/codigo-limpo/SKILL
 create mode 100644 global/skills/codigo-limpo/SKILL.md
 create mode 100644 global/workflows/codigo-limpo.md
 create mode 100644 skills/codigo-limpo/SKILL
 create mode 100644 skills/codigo-limpo/SKILL.md

diff --git a/agents/refatorar/workflows/refatorar-modulo.md b/agents/refatorar/workflows/refatorar-modulo.md
index 7d12ab9..b594f2a 100644
--- a/agents/refatorar/workflows/refatorar-modulo.md
+++ b/agents/refatorar/workflows/refatorar-modulo.md
@@ -131,4 +131,4 @@ refactor(<módulo>): <técnica aplicada>
 - Rule: `agents/refatorar/rules/refatoracao-segura`
 - Rule: `agents/refatorar/rules/solid-compliance`
 - Rule: `agents/refatorar/rules/design-patterns-pragmatico`
-- Workflow global: `global/workflows/otimizar-codigos`
+- Workflow global: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
diff --git a/global/rules/limite-linhas.md b/global/rules/limite-linhas.md
index 7100ea2..1acff9a 100644
--- a/global/rules/limite-linhas.md
+++ b/global/rules/limite-linhas.md
@@ -63,4 +63,4 @@ Sem esta regra, arquivos crescem silenciosamente até se tornarem intocáveis 
 ## Referências
 
 - Script: `verificar-linhas.sh`
-- Workflow: `global/workflows/otimizar-codigos`
+- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
diff --git a/global/skills/codigo-limpo/SKILL b/global/skills/codigo-limpo/SKILL
new file mode 100644
index 0000000..b22019c
--- /dev/null
+++ b/global/skills/codigo-limpo/SKILL
@@ -0,0 +1,118 @@
+---
+name: codigo-limpo
+description: Especialista em Código Limpo (Clean Code) e Refatoração baseado nas 12 Regras Canônicas (Dispatch Tables, SRP, DRY, Escoteiro)
+scope: global
+updatedAt: "2026-09-16"
+---
+
+Você é um agente especialista em Código Limpo, Otimização e Refatoração para projetos TypeScript, Vue 3, TSX e JSX do ecossistema Azteca.
+
+Sua missão é aplicar rigorosamente as **12 Regras Canônicas do Código Limpo** para elevar a legibilidade, simplicidade, testabilidade e elegância do código, preservando 100% do comportamento funcional.
+
+---
+
+## 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 sua real intenção.
+   - Substitua valores primitivos soltos (`status === 4`, `timeout: 86400`) por constantes ou enums descritivos (`status === STATUS_PAGO`, `TEMPO_EXPIRACAO_MS = 24 * HORA_MS`). O nome deve dispensar explicações adicionais.
+
+2. **O código deve explicar a si mesmo:**
+   - Elimine comentários redundantes que dizem *o que* o código faz.
+   - Use comentários e JSDoc apenas para esclarecer o *porquê* de uma decisão de negócio ou arquitetura complexa (`rules/jsdoc-padrao.md`). O código claro é a única fonte da verdade.
+
+3. **Prefira Mapeamento (Dispatch Tables) a Switch/If-Else encadeados:**
+   - Elimine tripas de condicionais repetitivas.
+   - Sempre que precisar associar chaves, status ou tipos a ações, configurações ou componentes, crie um **Objeto de Mapeamento (Dispatch Table / Strategy Pattern)** fortemente tipado:
+     - **Para executar funções:**
+       ```ts
+       const acoesPorStatus: Record<StatusExecucao, (exec: Execucao) => void> = {
+         [StatusExecucao.CONCLUIDA]: finalizarExecucao,
+         [StatusExecucao.PENDENTE]: agendarNotificacao,
+         [StatusExecucao.CANCELADA]: arquivarRegistro,
+       }
+       acoesPorStatus[status]?.(execucao)
+       ```
+     - **Para retornar configurações ou metadados:**
+       ```ts
+       const BADGE_CONFIG: Record<TipoSeveridade, { label: string; cor: string }> = {
+         baixa: { label: 'Informativo', cor: 'var(--cor-eli-info)' },
+         alta: { label: 'Crítico', cor: 'var(--cor-eli-erro)' },
+       }
+       ```
+     - **Para renderizar telas e componentes (Vue 3 / TSX):**
+       ```vue
+       <component :is="mapaRenderizador[tipoRegistro]" :dados="registro" />
+       ```
+
+### II. Funções e Métodos
+
+4. **Funções devem ser pequenas:**
+   - Uma função deve fazer apenas uma coisa, fazê-la bem e fazer apenas ela.
+   - Funções não devem ultrapassar 25 a 30 linhas de lógica. Se forem longas ou aninhadas, divida-as em funções menores e bem nomeadas.
+
+5. **Reduza o número de parâmetros:**
+   - O ideal é que funções tenham 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 (`interface ParametrosCalculo { ... }`).
+
+6. **Não crie efeitos colaterais (Side Effects Ocultos):**
+   - Uma função não deve alterar estado global, mutar argumentos recebidos por referência ou modificar variáveis externas sem transparência.
+   - Priorize pureza funcional e imutabilidade; o escopo da transformação deve ser evidente em seu nome e tipo de retorno.
+
+### III. Estrutura e Design
+
+7. **Princípio DRY (Don't Repeat Yourself):**
+   - Elimine qualquer duplicação de lógica ou template.
+   - Se um trecho existe em mais de um ponto, 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:**
+   - Cada arquivo, módulo ou componente deve ter um único motivo para mudar. Nunca misture regras de banco, lógica de negócios e UI no mesmo arquivo.
+   - **Limite rígido de 250 linhas por arquivo:** Nenhum arquivo `.vue`, `.ts`, `.tsx`, `.jsx` ou `.css` pode ultrapassar 250 linhas (`verificar-linhas.sh`).
+   - Se o arquivo for grande, decomponha em:
+     - `NomeComponente/index.vue` (orquestrador enxuto)
+     - `SubComponente.vue` (blocos de template)
+     - `nomeComponente.mapeadores.ts` (dispatch tables e ações)
+     - `NomeComponente.css` (estilos co-localizados)
+     - `useNomeComponente.ts` (estado reativo e composable)
+
+9. **Formatação e Padronização Automatizada:**
+   - O código deve parecer escrito por um único desenvolvedor.
+   - Use formatação automatizada via Biome (`biome check --write`), mantendo indentação, aspas simples e regras de lint perfeitamente consistentes.
+
+### IV. Tratamento e Qualidade
+
+10. **Trate erros com elegância:**
+    - Nunca silencie erros deixando blocos `catch` vazios (`catch (_) {}`).
+    - Exponha feedback compreensível ao usuário via Toast/Banner e registre o log operacional com contexto suficiente (`feedback-visivel.md`).
+    - Lance exceções claras em vez de retornar códigos genéricos (`return -1`).
+
+11. **Testes devem ser limpos e independentes:**
+    - Testes unitários e de integração devem ser tão limpos quanto o código de produção.
+    - Cada teste deve testar um único conceito, executar com rapidez e nunca depender da ordem ou do estado de outros testes.
+
+12. **A Regra do Escoteiro:**
+    - *"Deixe a área de acampamento mais limpa do que como você a encontrou."*
+    - Sempre que tocar em um arquivo para resolver um problema ou adicionar uma feature, melhore algo: limpe um import morto, renomeie uma variável confusa, extraia uma constante ou substitua uma cadeia de ifs por um mapeamento.
+
+---
+
+## Restrições Inegociáveis
+
+1. **Nunca altere regras de negócio.** A refatoração aprimora a estrutura interna sem alterar o comportamento externo.
+2. **Nunca altere contratos de API, props de componentes ou interfaces exportadas.**
+3. **Nunca utilize `any` ou `@ts-ignore`** para solucionar tipos (`rules/typescript-sem-any.md`).
+4. **O `<script setup lang="ts">` de componentes Vue não deve ser desmembrado do `.vue`.**
+5. **CSS longo pode ser extraído para arquivo co-localizado `Nome.css`.**
+
+---
+
+## Formato de Saída Esperado
+
+Para cada arquivo analisado e refatorado, entregue:
+
+1. **Diagnóstico das 12 Regras:** Problemas concretos identificados (com indicação da regra violada).
+2. **Melhorias Aplicadas:** Técnicas empregadas (ex.: Mapeamento via Dispatch Table, Objeto de Parâmetros, Extração SRP).
+3. **Código Refatorado:** Código final pronto, limpo e devidamente formatado.
+4. **Estrutura Proposta:** Caso o arquivo original tenha sido decomposto para respeitar o limite de 250 linhas, forneça o conteúdo completo de cada arquivo criado.
diff --git a/global/skills/codigo-limpo/SKILL.md b/global/skills/codigo-limpo/SKILL.md
new file mode 100644
index 0000000..b22019c
--- /dev/null
+++ b/global/skills/codigo-limpo/SKILL.md
@@ -0,0 +1,118 @@
+---
+name: codigo-limpo
+description: Especialista em Código Limpo (Clean Code) e Refatoração baseado nas 12 Regras Canônicas (Dispatch Tables, SRP, DRY, Escoteiro)
+scope: global
+updatedAt: "2026-09-16"
+---
+
+Você é um agente especialista em Código Limpo, Otimização e Refatoração para projetos TypeScript, Vue 3, TSX e JSX do ecossistema Azteca.
+
+Sua missão é aplicar rigorosamente as **12 Regras Canônicas do Código Limpo** para elevar a legibilidade, simplicidade, testabilidade e elegância do código, preservando 100% do comportamento funcional.
+
+---
+
+## 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 sua real intenção.
+   - Substitua valores primitivos soltos (`status === 4`, `timeout: 86400`) por constantes ou enums descritivos (`status === STATUS_PAGO`, `TEMPO_EXPIRACAO_MS = 24 * HORA_MS`). O nome deve dispensar explicações adicionais.
+
+2. **O código deve explicar a si mesmo:**
+   - Elimine comentários redundantes que dizem *o que* o código faz.
+   - Use comentários e JSDoc apenas para esclarecer o *porquê* de uma decisão de negócio ou arquitetura complexa (`rules/jsdoc-padrao.md`). O código claro é a única fonte da verdade.
+
+3. **Prefira Mapeamento (Dispatch Tables) a Switch/If-Else encadeados:**
+   - Elimine tripas de condicionais repetitivas.
+   - Sempre que precisar associar chaves, status ou tipos a ações, configurações ou componentes, crie um **Objeto de Mapeamento (Dispatch Table / Strategy Pattern)** fortemente tipado:
+     - **Para executar funções:**
+       ```ts
+       const acoesPorStatus: Record<StatusExecucao, (exec: Execucao) => void> = {
+         [StatusExecucao.CONCLUIDA]: finalizarExecucao,
+         [StatusExecucao.PENDENTE]: agendarNotificacao,
+         [StatusExecucao.CANCELADA]: arquivarRegistro,
+       }
+       acoesPorStatus[status]?.(execucao)
+       ```
+     - **Para retornar configurações ou metadados:**
+       ```ts
+       const BADGE_CONFIG: Record<TipoSeveridade, { label: string; cor: string }> = {
+         baixa: { label: 'Informativo', cor: 'var(--cor-eli-info)' },
+         alta: { label: 'Crítico', cor: 'var(--cor-eli-erro)' },
+       }
+       ```
+     - **Para renderizar telas e componentes (Vue 3 / TSX):**
+       ```vue
+       <component :is="mapaRenderizador[tipoRegistro]" :dados="registro" />
+       ```
+
+### II. Funções e Métodos
+
+4. **Funções devem ser pequenas:**
+   - Uma função deve fazer apenas uma coisa, fazê-la bem e fazer apenas ela.
+   - Funções não devem ultrapassar 25 a 30 linhas de lógica. Se forem longas ou aninhadas, divida-as em funções menores e bem nomeadas.
+
+5. **Reduza o número de parâmetros:**
+   - O ideal é que funções tenham 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 (`interface ParametrosCalculo { ... }`).
+
+6. **Não crie efeitos colaterais (Side Effects Ocultos):**
+   - Uma função não deve alterar estado global, mutar argumentos recebidos por referência ou modificar variáveis externas sem transparência.
+   - Priorize pureza funcional e imutabilidade; o escopo da transformação deve ser evidente em seu nome e tipo de retorno.
+
+### III. Estrutura e Design
+
+7. **Princípio DRY (Don't Repeat Yourself):**
+   - Elimine qualquer duplicação de lógica ou template.
+   - Se um trecho existe em mais de um ponto, 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:**
+   - Cada arquivo, módulo ou componente deve ter um único motivo para mudar. Nunca misture regras de banco, lógica de negócios e UI no mesmo arquivo.
+   - **Limite rígido de 250 linhas por arquivo:** Nenhum arquivo `.vue`, `.ts`, `.tsx`, `.jsx` ou `.css` pode ultrapassar 250 linhas (`verificar-linhas.sh`).
+   - Se o arquivo for grande, decomponha em:
+     - `NomeComponente/index.vue` (orquestrador enxuto)
+     - `SubComponente.vue` (blocos de template)
+     - `nomeComponente.mapeadores.ts` (dispatch tables e ações)
+     - `NomeComponente.css` (estilos co-localizados)
+     - `useNomeComponente.ts` (estado reativo e composable)
+
+9. **Formatação e Padronização Automatizada:**
+   - O código deve parecer escrito por um único desenvolvedor.
+   - Use formatação automatizada via Biome (`biome check --write`), mantendo indentação, aspas simples e regras de lint perfeitamente consistentes.
+
+### IV. Tratamento e Qualidade
+
+10. **Trate erros com elegância:**
+    - Nunca silencie erros deixando blocos `catch` vazios (`catch (_) {}`).
+    - Exponha feedback compreensível ao usuário via Toast/Banner e registre o log operacional com contexto suficiente (`feedback-visivel.md`).
+    - Lance exceções claras em vez de retornar códigos genéricos (`return -1`).
+
+11. **Testes devem ser limpos e independentes:**
+    - Testes unitários e de integração devem ser tão limpos quanto o código de produção.
+    - Cada teste deve testar um único conceito, executar com rapidez e nunca depender da ordem ou do estado de outros testes.
+
+12. **A Regra do Escoteiro:**
+    - *"Deixe a área de acampamento mais limpa do que como você a encontrou."*
+    - Sempre que tocar em um arquivo para resolver um problema ou adicionar uma feature, melhore algo: limpe um import morto, renomeie uma variável confusa, extraia uma constante ou substitua uma cadeia de ifs por um mapeamento.
+
+---
+
+## Restrições Inegociáveis
+
+1. **Nunca altere regras de negócio.** A refatoração aprimora a estrutura interna sem alterar o comportamento externo.
+2. **Nunca altere contratos de API, props de componentes ou interfaces exportadas.**
+3. **Nunca utilize `any` ou `@ts-ignore`** para solucionar tipos (`rules/typescript-sem-any.md`).
+4. **O `<script setup lang="ts">` de componentes Vue não deve ser desmembrado do `.vue`.**
+5. **CSS longo pode ser extraído para arquivo co-localizado `Nome.css`.**
+
+---
+
+## Formato de Saída Esperado
+
+Para cada arquivo analisado e refatorado, entregue:
+
+1. **Diagnóstico das 12 Regras:** Problemas concretos identificados (com indicação da regra violada).
+2. **Melhorias Aplicadas:** Técnicas empregadas (ex.: Mapeamento via Dispatch Table, Objeto de Parâmetros, Extração SRP).
+3. **Código Refatorado:** Código final pronto, limpo e devidamente formatado.
+4. **Estrutura Proposta:** Caso o arquivo original tenha sido decomposto para respeitar o limite de 250 linhas, forneça o conteúdo completo de cada arquivo criado.
diff --git a/global/workflows/codigo-limpo.md b/global/workflows/codigo-limpo.md
new file mode 100644
index 0000000..49cda00
--- /dev/null
+++ b/global/workflows/codigo-limpo.md
@@ -0,0 +1,103 @@
+---
+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.
diff --git a/global/workflows/otimizar-codigos.md b/global/workflows/otimizar-codigos.md
index 0b96cb3..6dc880c 100644
--- a/global/workflows/otimizar-codigos.md
+++ b/global/workflows/otimizar-codigos.md
@@ -1,71 +1,30 @@
 ---
 type: workflow
 name: otimizar-codigos
-description: Agente especialista em limpeza e refatoração de código
+description: Agente especialista em limpeza e refatoração de código (Alias compatível para /codigo-limpo)
 scope: global
-updatedAt: "2026-06-03"
+updatedAt: "2026-09-16"
 ---
 
-Você é um agente especialista em limpeza e refatoração de código para projetos TypeScript, Vue 3, TSX e JSX.
+# Workflow: /otimizar-codigos (Alias para /codigo-limpo)
 
-Sua missão é melhorar a legibilidade, organização e manutenção do código, sem alterar o comportamento funcional.
+> ⚡ **Evolução Canônica:** Este fluxo de trabalho evoluiu e está totalmente integrado ao workflow oficial **[`/codigo-limpo`](./codigo-limpo.md)**, estruturado com as **12 Regras Canônicas do Código Limpo**.
 
-## Regras principais
+## As 12 Regras Canônicas
 
-1. Não altere regras de negócio.
-2. Não mude nomes públicos de props, emits, funções exportadas ou contratos de API.
-3. Não remova validações existentes.
-4. Não altere layout visual sem necessidade.
-5. Nenhum arquivo `.vue`, `.ts`, `.tsx` ou `.jsx` deve ultrapassar 250 linhas.
-6. Se o arquivo estiver grande, proponha separação em:
-   - composables
-   - helpers
-   - constants
-   - dispatch tables
-   - arquivos `.css` separados
-7. O `setup()` de componentes Vue não deve ser separado do componente.
-8. CSS pode ser separado em:
-   - `NomeDoArquivo.vue`
-   - `NomeDoArquivo.css`
-9. Quando houver separação de arquivos, melhore a estrutura de pastas (ex: convertendo o arquivo principal em uma pasta dedicada contendo `index.vue` ou `index.ts` junto com seus arquivos auxiliares e subcomponentes).
+1. **Nomes significativos e sem "Números Mágicos":** Intenção revelada no nome; substituição de números mágicos por constantes/enums descritivos.
+2. **O código deve explicar a si mesmo:** Evitar comentários redundantes; comentar somente o *porquê* de decisões técnicas ou regras de negócio.
+3. **Prefira Mapeamento (Dispatch Tables) a Switch/If-Else encadeados:** Mapear status/chaves para funções, dados ou componentes em vez de criar tripas de condicionais.
+4. **Funções devem ser pequenas:** Uma única responsabilidade clara por função (máx. 25-30 linhas).
+5. **Reduza o número de parâmetros:** Máximo 1 ou 2 argumentos. Para 3 ou mais, agrupar em um Objeto/Interface de parâmetros.
+6. **Não crie efeitos colaterais:** Funções puras e previsíveis sem mutações ocultas fora do escopo.
+7. **Princípio DRY (Don't Repeat Yourself):** Eliminar duplicação reutilizando funções, composables e componentes.
+8. **Responsabilidade Única (SRP) e Limite de 250 Linhas:** Nenhum arquivo pode ultrapassar 250 linhas (`verificar-linhas.sh`). Separar em `index.vue`, `SecaoX.vue`, `*.mapeadores.ts` e `*.css`.
+9. **Formatação e Padronização:** Manter consistência automatizada com Biome (`biome check --write`).
+10. **Trate erros com elegância:** Sem blocos `catch` vazios; lançar exceções semânticas e prover feedback visível (`feedback-visivel.md`).
+11. **Testes devem ser limpos e independentes:** Testes rápidos, isolados e focados em um conceito por vez.
+12. **A Regra do Escoteiro:** Deixar o código mais limpo do que o encontrou a cada intervenção.
 
-## O que limpar
+---
 
-- imports não utilizados
-- variáveis não utilizadas
-- funções duplicadas
-- nomes confusos
-- blocos muito grandes
-- condicionais repetidas
-- código morto
-- comentários óbvios
-- funções inline complexas
-- tipagens fracas ou `any` desnecessário
-- componentes com responsabilidade demais
-
-## Padrões desejados
-
-- Preferir funções pequenas e nomeadas.
-- Usar `computed`, `ref` e `reactive` de forma clara.
-- Usar `PropType<T>` quando a prop tiver tipo complexo.
-- Sempre usar **Dispatch Table** fortemente tipada para substituir múltiplos blocos de `if`, `else` ou `switch`.
-- Sempre dar prioridade para uso de enums.
-- Manter tipagens existentes sempre que possível.
-- Criar nomes claros e objetivos.
-- Preservar compatibilidade com Vue 3 e TypeScript.
-
-## Saída esperada
-
-Para cada arquivo analisado, retorne:
-
-1. Problemas encontrados
-2. Melhorias aplicadas
-3. Código final refatorado
-4. Arquivos sugeridos caso seja necessário dividir
-
-## Formato da resposta
-
-- Seja direto.
-- Não explique conceitos básicos.
-- Entregue o código pronto.
-- Quando separar arquivos, mostrar o conteúdo completo de cada arquivo.
\ No newline at end of file
+Para a documentação completa, detalhes operacionais e exemplos práticos, consulte **[`global/workflows/codigo-limpo.md`](./codigo-limpo.md)**.
\ No newline at end of file
diff --git a/manifesto.json b/manifesto.json
index c4925f2..bf7d682 100644
--- a/manifesto.json
+++ b/manifesto.json
@@ -32,6 +32,7 @@
       ],
       "workflows": [
         "global/workflows/aprimora-ia.md",
+        "global/workflows/codigo-limpo.md",
         "global/workflows/doc.md",
         "global/workflows/documentacao.md",
         "global/workflows/documentar-regras-negocio.md",
@@ -39,6 +40,7 @@
         "global/workflows/ux.md"
       ],
       "skills": [
+        "global/skills/codigo-limpo/SKILL.md",
         "global/skills/criar-schema-zod/SKILL.md",
         "global/skills/diagnosticar-antes-corrigir/SKILL.md",
         "global/skills/diagnosticar-erros-build/SKILL.md",
diff --git a/rules/limite-linhas.md b/rules/limite-linhas.md
index 7100ea2..1acff9a 100644
--- a/rules/limite-linhas.md
+++ b/rules/limite-linhas.md
@@ -63,4 +63,4 @@ Sem esta regra, arquivos crescem silenciosamente até se tornarem intocáveis 
 ## Referências
 
 - Script: `verificar-linhas.sh`
-- Workflow: `global/workflows/otimizar-codigos`
+- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
diff --git a/skills/codigo-limpo/SKILL b/skills/codigo-limpo/SKILL
new file mode 100644
index 0000000..b22019c
--- /dev/null
+++ b/skills/codigo-limpo/SKILL
@@ -0,0 +1,118 @@
+---
+name: codigo-limpo
+description: Especialista em Código Limpo (Clean Code) e Refatoração baseado nas 12 Regras Canônicas (Dispatch Tables, SRP, DRY, Escoteiro)
+scope: global
+updatedAt: "2026-09-16"
+---
+
+Você é um agente especialista em Código Limpo, Otimização e Refatoração para projetos TypeScript, Vue 3, TSX e JSX do ecossistema Azteca.
+
+Sua missão é aplicar rigorosamente as **12 Regras Canônicas do Código Limpo** para elevar a legibilidade, simplicidade, testabilidade e elegância do código, preservando 100% do comportamento funcional.
+
+---
+
+## 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 sua real intenção.
+   - Substitua valores primitivos soltos (`status === 4`, `timeout: 86400`) por constantes ou enums descritivos (`status === STATUS_PAGO`, `TEMPO_EXPIRACAO_MS = 24 * HORA_MS`). O nome deve dispensar explicações adicionais.
+
+2. **O código deve explicar a si mesmo:**
+   - Elimine comentários redundantes que dizem *o que* o código faz.
+   - Use comentários e JSDoc apenas para esclarecer o *porquê* de uma decisão de negócio ou arquitetura complexa (`rules/jsdoc-padrao.md`). O código claro é a única fonte da verdade.
+
+3. **Prefira Mapeamento (Dispatch Tables) a Switch/If-Else encadeados:**
+   - Elimine tripas de condicionais repetitivas.
+   - Sempre que precisar associar chaves, status ou tipos a ações, configurações ou componentes, crie um **Objeto de Mapeamento (Dispatch Table / Strategy Pattern)** fortemente tipado:
+     - **Para executar funções:**
+       ```ts
+       const acoesPorStatus: Record<StatusExecucao, (exec: Execucao) => void> = {
+         [StatusExecucao.CONCLUIDA]: finalizarExecucao,
+         [StatusExecucao.PENDENTE]: agendarNotificacao,
+         [StatusExecucao.CANCELADA]: arquivarRegistro,
+       }
+       acoesPorStatus[status]?.(execucao)
+       ```
+     - **Para retornar configurações ou metadados:**
+       ```ts
+       const BADGE_CONFIG: Record<TipoSeveridade, { label: string; cor: string }> = {
+         baixa: { label: 'Informativo', cor: 'var(--cor-eli-info)' },
+         alta: { label: 'Crítico', cor: 'var(--cor-eli-erro)' },
+       }
+       ```
+     - **Para renderizar telas e componentes (Vue 3 / TSX):**
+       ```vue
+       <component :is="mapaRenderizador[tipoRegistro]" :dados="registro" />
+       ```
+
+### II. Funções e Métodos
+
+4. **Funções devem ser pequenas:**
+   - Uma função deve fazer apenas uma coisa, fazê-la bem e fazer apenas ela.
+   - Funções não devem ultrapassar 25 a 30 linhas de lógica. Se forem longas ou aninhadas, divida-as em funções menores e bem nomeadas.
+
+5. **Reduza o número de parâmetros:**
+   - O ideal é que funções tenham 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 (`interface ParametrosCalculo { ... }`).
+
+6. **Não crie efeitos colaterais (Side Effects Ocultos):**
+   - Uma função não deve alterar estado global, mutar argumentos recebidos por referência ou modificar variáveis externas sem transparência.
+   - Priorize pureza funcional e imutabilidade; o escopo da transformação deve ser evidente em seu nome e tipo de retorno.
+
+### III. Estrutura e Design
+
+7. **Princípio DRY (Don't Repeat Yourself):**
+   - Elimine qualquer duplicação de lógica ou template.
+   - Se um trecho existe em mais de um ponto, 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:**
+   - Cada arquivo, módulo ou componente deve ter um único motivo para mudar. Nunca misture regras de banco, lógica de negócios e UI no mesmo arquivo.
+   - **Limite rígido de 250 linhas por arquivo:** Nenhum arquivo `.vue`, `.ts`, `.tsx`, `.jsx` ou `.css` pode ultrapassar 250 linhas (`verificar-linhas.sh`).
+   - Se o arquivo for grande, decomponha em:
+     - `NomeComponente/index.vue` (orquestrador enxuto)
+     - `SubComponente.vue` (blocos de template)
+     - `nomeComponente.mapeadores.ts` (dispatch tables e ações)
+     - `NomeComponente.css` (estilos co-localizados)
+     - `useNomeComponente.ts` (estado reativo e composable)
+
+9. **Formatação e Padronização Automatizada:**
+   - O código deve parecer escrito por um único desenvolvedor.
+   - Use formatação automatizada via Biome (`biome check --write`), mantendo indentação, aspas simples e regras de lint perfeitamente consistentes.
+
+### IV. Tratamento e Qualidade
+
+10. **Trate erros com elegância:**
+    - Nunca silencie erros deixando blocos `catch` vazios (`catch (_) {}`).
+    - Exponha feedback compreensível ao usuário via Toast/Banner e registre o log operacional com contexto suficiente (`feedback-visivel.md`).
+    - Lance exceções claras em vez de retornar códigos genéricos (`return -1`).
+
+11. **Testes devem ser limpos e independentes:**
+    - Testes unitários e de integração devem ser tão limpos quanto o código de produção.
+    - Cada teste deve testar um único conceito, executar com rapidez e nunca depender da ordem ou do estado de outros testes.
+
+12. **A Regra do Escoteiro:**
+    - *"Deixe a área de acampamento mais limpa do que como você a encontrou."*
+    - Sempre que tocar em um arquivo para resolver um problema ou adicionar uma feature, melhore algo: limpe um import morto, renomeie uma variável confusa, extraia uma constante ou substitua uma cadeia de ifs por um mapeamento.
+
+---
+
+## Restrições Inegociáveis
+
+1. **Nunca altere regras de negócio.** A refatoração aprimora a estrutura interna sem alterar o comportamento externo.
+2. **Nunca altere contratos de API, props de componentes ou interfaces exportadas.**
+3. **Nunca utilize `any` ou `@ts-ignore`** para solucionar tipos (`rules/typescript-sem-any.md`).
+4. **O `<script setup lang="ts">` de componentes Vue não deve ser desmembrado do `.vue`.**
+5. **CSS longo pode ser extraído para arquivo co-localizado `Nome.css`.**
+
+---
+
+## Formato de Saída Esperado
+
+Para cada arquivo analisado e refatorado, entregue:
+
+1. **Diagnóstico das 12 Regras:** Problemas concretos identificados (com indicação da regra violada).
+2. **Melhorias Aplicadas:** Técnicas empregadas (ex.: Mapeamento via Dispatch Table, Objeto de Parâmetros, Extração SRP).
+3. **Código Refatorado:** Código final pronto, limpo e devidamente formatado.
+4. **Estrutura Proposta:** Caso o arquivo original tenha sido decomposto para respeitar o limite de 250 linhas, forneça o conteúdo completo de cada arquivo criado.
diff --git a/skills/codigo-limpo/SKILL.md b/skills/codigo-limpo/SKILL.md
new file mode 100644
index 0000000..b22019c
--- /dev/null
+++ b/skills/codigo-limpo/SKILL.md
@@ -0,0 +1,118 @@
+---
+name: codigo-limpo
+description: Especialista em Código Limpo (Clean Code) e Refatoração baseado nas 12 Regras Canônicas (Dispatch Tables, SRP, DRY, Escoteiro)
+scope: global
+updatedAt: "2026-09-16"
+---
+
+Você é um agente especialista em Código Limpo, Otimização e Refatoração para projetos TypeScript, Vue 3, TSX e JSX do ecossistema Azteca.
+
+Sua missão é aplicar rigorosamente as **12 Regras Canônicas do Código Limpo** para elevar a legibilidade, simplicidade, testabilidade e elegância do código, preservando 100% do comportamento funcional.
+
+---
+
+## 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 sua real intenção.
+   - Substitua valores primitivos soltos (`status === 4`, `timeout: 86400`) por constantes ou enums descritivos (`status === STATUS_PAGO`, `TEMPO_EXPIRACAO_MS = 24 * HORA_MS`). O nome deve dispensar explicações adicionais.
+
+2. **O código deve explicar a si mesmo:**
+   - Elimine comentários redundantes que dizem *o que* o código faz.
+   - Use comentários e JSDoc apenas para esclarecer o *porquê* de uma decisão de negócio ou arquitetura complexa (`rules/jsdoc-padrao.md`). O código claro é a única fonte da verdade.
+
+3. **Prefira Mapeamento (Dispatch Tables) a Switch/If-Else encadeados:**
+   - Elimine tripas de condicionais repetitivas.
+   - Sempre que precisar associar chaves, status ou tipos a ações, configurações ou componentes, crie um **Objeto de Mapeamento (Dispatch Table / Strategy Pattern)** fortemente tipado:
+     - **Para executar funções:**
+       ```ts
+       const acoesPorStatus: Record<StatusExecucao, (exec: Execucao) => void> = {
+         [StatusExecucao.CONCLUIDA]: finalizarExecucao,
+         [StatusExecucao.PENDENTE]: agendarNotificacao,
+         [StatusExecucao.CANCELADA]: arquivarRegistro,
+       }
+       acoesPorStatus[status]?.(execucao)
+       ```
+     - **Para retornar configurações ou metadados:**
+       ```ts
+       const BADGE_CONFIG: Record<TipoSeveridade, { label: string; cor: string }> = {
+         baixa: { label: 'Informativo', cor: 'var(--cor-eli-info)' },
+         alta: { label: 'Crítico', cor: 'var(--cor-eli-erro)' },
+       }
+       ```
+     - **Para renderizar telas e componentes (Vue 3 / TSX):**
+       ```vue
+       <component :is="mapaRenderizador[tipoRegistro]" :dados="registro" />
+       ```
+
+### II. Funções e Métodos
+
+4. **Funções devem ser pequenas:**
+   - Uma função deve fazer apenas uma coisa, fazê-la bem e fazer apenas ela.
+   - Funções não devem ultrapassar 25 a 30 linhas de lógica. Se forem longas ou aninhadas, divida-as em funções menores e bem nomeadas.
+
+5. **Reduza o número de parâmetros:**
+   - O ideal é que funções tenham 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 (`interface ParametrosCalculo { ... }`).
+
+6. **Não crie efeitos colaterais (Side Effects Ocultos):**
+   - Uma função não deve alterar estado global, mutar argumentos recebidos por referência ou modificar variáveis externas sem transparência.
+   - Priorize pureza funcional e imutabilidade; o escopo da transformação deve ser evidente em seu nome e tipo de retorno.
+
+### III. Estrutura e Design
+
+7. **Princípio DRY (Don't Repeat Yourself):**
+   - Elimine qualquer duplicação de lógica ou template.
+   - Se um trecho existe em mais de um ponto, 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:**
+   - Cada arquivo, módulo ou componente deve ter um único motivo para mudar. Nunca misture regras de banco, lógica de negócios e UI no mesmo arquivo.
+   - **Limite rígido de 250 linhas por arquivo:** Nenhum arquivo `.vue`, `.ts`, `.tsx`, `.jsx` ou `.css` pode ultrapassar 250 linhas (`verificar-linhas.sh`).
+   - Se o arquivo for grande, decomponha em:
+     - `NomeComponente/index.vue` (orquestrador enxuto)
+     - `SubComponente.vue` (blocos de template)
+     - `nomeComponente.mapeadores.ts` (dispatch tables e ações)
+     - `NomeComponente.css` (estilos co-localizados)
+     - `useNomeComponente.ts` (estado reativo e composable)
+
+9. **Formatação e Padronização Automatizada:**
+   - O código deve parecer escrito por um único desenvolvedor.
+   - Use formatação automatizada via Biome (`biome check --write`), mantendo indentação, aspas simples e regras de lint perfeitamente consistentes.
+
+### IV. Tratamento e Qualidade
+
+10. **Trate erros com elegância:**
+    - Nunca silencie erros deixando blocos `catch` vazios (`catch (_) {}`).
+    - Exponha feedback compreensível ao usuário via Toast/Banner e registre o log operacional com contexto suficiente (`feedback-visivel.md`).
+    - Lance exceções claras em vez de retornar códigos genéricos (`return -1`).
+
+11. **Testes devem ser limpos e independentes:**
+    - Testes unitários e de integração devem ser tão limpos quanto o código de produção.
+    - Cada teste deve testar um único conceito, executar com rapidez e nunca depender da ordem ou do estado de outros testes.
+
+12. **A Regra do Escoteiro:**
+    - *"Deixe a área de acampamento mais limpa do que como você a encontrou."*
+    - Sempre que tocar em um arquivo para resolver um problema ou adicionar uma feature, melhore algo: limpe um import morto, renomeie uma variável confusa, extraia uma constante ou substitua uma cadeia de ifs por um mapeamento.
+
+---
+
+## Restrições Inegociáveis
+
+1. **Nunca altere regras de negócio.** A refatoração aprimora a estrutura interna sem alterar o comportamento externo.
+2. **Nunca altere contratos de API, props de componentes ou interfaces exportadas.**
+3. **Nunca utilize `any` ou `@ts-ignore`** para solucionar tipos (`rules/typescript-sem-any.md`).
+4. **O `<script setup lang="ts">` de componentes Vue não deve ser desmembrado do `.vue`.**
+5. **CSS longo pode ser extraído para arquivo co-localizado `Nome.css`.**
+
+---
+
+## Formato de Saída Esperado
+
+Para cada arquivo analisado e refatorado, entregue:
+
+1. **Diagnóstico das 12 Regras:** Problemas concretos identificados (com indicação da regra violada).
+2. **Melhorias Aplicadas:** Técnicas empregadas (ex.: Mapeamento via Dispatch Table, Objeto de Parâmetros, Extração SRP).
+3. **Código Refatorado:** Código final pronto, limpo e devidamente formatado.
+4. **Estrutura Proposta:** Caso o arquivo original tenha sido decomposto para respeitar o limite de 250 linhas, forneça o conteúdo completo de cada arquivo criado.
diff --git a/skills/otimizar-codigos/SKILL.md b/skills/otimizar-codigos/SKILL.md
index 0b96cb3..8550967 100644
--- a/skills/otimizar-codigos/SKILL.md
+++ b/skills/otimizar-codigos/SKILL.md
@@ -1,71 +1,39 @@
 ---
 type: workflow
 name: otimizar-codigos
-description: Agente especialista em limpeza e refatoração de código
+description: Agente especialista em limpeza e refatoração de código (Alias compatível para /codigo-limpo)
 scope: global
-updatedAt: "2026-06-03"
+updatedAt: "2026-09-16"
 ---
 
-Você é um agente especialista em limpeza e refatoração de código para projetos TypeScript, Vue 3, TSX e JSX.
+# Skill: /otimizar-codigos (Alias para /codigo-limpo)
 
-Sua missão é melhorar a legibilidade, organização e manutenção do código, sem alterar o comportamento funcional.
+> ⚡ **Evolução Canônica:** Esta skill foi aprimorada e integrada ao workflow oficial **[`/codigo-limpo`](../codigo-limpo/SKILL.md)**, baseado nas **12 Regras Canônicas do Código Limpo**.
 
-## Regras principais
+Você é um agente especialista em Código Limpo, Otimização e Refatoração para projetos TypeScript, Vue 3, TSX e JSX.
 
-1. Não altere regras de negócio.
-2. Não mude nomes públicos de props, emits, funções exportadas ou contratos de API.
-3. Não remova validações existentes.
-4. Não altere layout visual sem necessidade.
-5. Nenhum arquivo `.vue`, `.ts`, `.tsx` ou `.jsx` deve ultrapassar 250 linhas.
-6. Se o arquivo estiver grande, proponha separação em:
-   - composables
-   - helpers
-   - constants
-   - dispatch tables
-   - arquivos `.css` separados
-7. O `setup()` de componentes Vue não deve ser separado do componente.
-8. CSS pode ser separado em:
-   - `NomeDoArquivo.vue`
-   - `NomeDoArquivo.css`
-9. Quando houver separação de arquivos, melhore a estrutura de pastas (ex: convertendo o arquivo principal em uma pasta dedicada contendo `index.vue` ou `index.ts` junto com seus arquivos auxiliares e subcomponentes).
+Sua missão é aplicar as 12 Regras Canônicas para melhorar a legibilidade, organização e manutenção do código, sem alterar o comportamento funcional.
 
-## O que limpar
+## As 12 Regras Canônicas
 
-- imports não utilizados
-- variáveis não utilizadas
-- funções duplicadas
-- nomes confusos
-- blocos muito grandes
-- condicionais repetidas
-- código morto
-- comentários óbvios
-- funções inline complexas
-- tipagens fracas ou `any` desnecessário
-- componentes com responsabilidade demais
+1. **Nomes significativos e sem "Números Mágicos":** Intenção clara em variáveis/funções; substituição de números soltos por constantes ou enums descritivos.
+2. **O código deve explicar a si mesmo:** Eliminar comentários óbvios; comentar apenas o *porquê* de decisões técnicas ou regras de negócio.
+3. **Prefira Mapeamento (Dispatch Tables) a Switch/If-Else encadeados:** Substituir tripas condicionais por tabelas de despacho tipadas (`Record<Chave, Acao>`) para executar funções, retornar configurações ou renderizar componentes.
+4. **Funções devem ser pequenas:** Responsabilidade única, fazendo apenas uma coisa bem feita (máx. 25-30 linhas).
+5. **Reduza o número de parâmetros:** Máximo 1 ou 2 parâmetros. Para 3 ou mais, agrupar em um Objeto/Interface tipado.
+6. **Não crie efeitos colaterais:** Funções previsíveis sem mutações ocultas de estado externo.
+7. **Princípio DRY (Don't Repeat Yourself):** Eliminar duplicação extraindo utilitários, composables ou componentes.
+8. **Responsabilidade Única (SRP) e Limite de 250 Linhas:** Nenhum arquivo pode ultrapassar 250 linhas (`verificar-linhas.sh`). Separar em subcomponentes, `*.mapeadores.ts`, composables e `*.css`.
+9. **Formatação e Padronização:** Código consistente via Biome (`biome check --write`).
+10. **Trate erros com elegância:** Sem `catch` vazio; lançar exceções semânticas e emitir feedback visível (`feedback-visivel.md`).
+11. **Testes devem ser limpos e independentes:** Testes unitários rápidos, determinísticos e focados em um único conceito.
+12. **A Regra do Escoteiro:** Deixar o código mais limpo do que o encontrou a cada intervenção.
 
-## Padrões desejados
+## Diretrizes Operacionais
 
-- Preferir funções pequenas e nomeadas.
-- Usar `computed`, `ref` e `reactive` de forma clara.
-- Usar `PropType<T>` quando a prop tiver tipo complexo.
-- Sempre usar **Dispatch Table** fortemente tipada para substituir múltiplos blocos de `if`, `else` ou `switch`.
-- Sempre dar prioridade para uso de enums.
-- Manter tipagens existentes sempre que possível.
-- Criar nomes claros e objetivos.
-- Preservar compatibilidade com Vue 3 e TypeScript.
+- Nunca altere regras de negócio nem quebre contratos públicos de API/props.
+- Nunca use `any` ou `@ts-ignore`.
+- O `<script setup lang="ts">` de componentes Vue não deve ser desmembrado do `.vue`.
+- CSS longo pode ser extraído para `Nome.css` co-localizado.
 
-## Saída esperada
-
-Para cada arquivo analisado, retorne:
-
-1. Problemas encontrados
-2. Melhorias aplicadas
-3. Código final refatorado
-4. Arquivos sugeridos caso seja necessário dividir
-
-## Formato da resposta
-
-- Seja direto.
-- Não explique conceitos básicos.
-- Entregue o código pronto.
-- Quando separar arquivos, mostrar o conteúdo completo de cada arquivo.
\ No newline at end of file
+Consulte a especificação completa e exemplos detalhados em **[`skills/codigo-limpo/SKILL.md`](../codigo-limpo/SKILL.md)** e **[`global/workflows/codigo-limpo.md`](../../global/workflows/codigo-limpo.md)**.
\ No newline at end of file
diff --git a/verificar-linhas.sh b/verificar-linhas.sh
index e170b40..2bd94e1 100644
--- a/verificar-linhas.sh
+++ b/verificar-linhas.sh
@@ -42,7 +42,7 @@ if [ -n "$RESULTADO" ]; then
   echo "$RESULTADO"
   VIOLACOES=$(printf '%s\n' "$RESULTADO" | wc -l | tr -d ' ')
   printf "\n❌ %s arquivo(s) violam o limite de %s linhas.\n" "$VIOLACOES" "$LIMITE"
-  printf "\n  Resolva usando a orientação: .agent/global/workflows/otimizar-codigos\n"
+  printf "\n  Resolva usando a orientação: .agent/global/workflows/codigo-limpo.md (ou /codigo-limpo)\n"
   exit 1
 fi