codigo limpo
This commit is contained in:
parent
f57362d30d
commit
7c11b08d17
12 changed files with 625 additions and 121 deletions
103
global/workflows/codigo-limpo.md
Normal file
103
global/workflows/codigo-limpo.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
Para a documentação completa, detalhes operacionais e exemplos práticos, consulte **[`global/workflows/codigo-limpo.md`](./codigo-limpo.md)**.
|
||||
Loading…
Add table
Add a link
Reference in a new issue