Compare commits
No commits in common. "a947483a7693b4ed28dd2a8d9f10c7042c7dc7ef" and "f57362d30db9a65f02c5bf65a8d8a51f35835289" have entirely different histories.
a947483a76
...
f57362d30d
39 changed files with 148 additions and 1380 deletions
23
TOOLS
23
TOOLS
|
|
@ -89,22 +89,9 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 6. Automação e Testes de Interface (Browser)
|
## 6. Instalação Rápida (Copia e Cola)
|
||||||
|
|
||||||
### agent-browser
|
Para instalar as ferramentas base de forma ágil e em lote, copie os blocos de comando abaixo e os rode inteiramente em seu terminal (requer `npm` e `snap` já configurados).
|
||||||
- **Descrição:** CLI de automação de navegadores baseada em Rust, projetada especificamente para Agentes de IA.
|
|
||||||
- **Por que ajuda as IAs:** Utiliza representação compacta da árvore de acessibilidade com referências determinísticas (`@e1`, `@e2`), consumindo 200–400 tokens (até 90% menos tokens que a leitura do DOM completo). Permite executar testes E2E, interagir com telas, validar fluxos e registrar evidências visuais.
|
|
||||||
- **Modo Visível Obrigatório:** Para que o operador acompanhe cada teste em tempo real na tela, execute sempre com a flag `--headed` (ex: `agent-browser open --headed <url>`) ou defina `export AGENT_BROWSER_HEADED=true`.
|
|
||||||
- **Instalação:**
|
|
||||||
- Com Bun (padrão): `bun i -g agent-browser && agent-browser install`
|
|
||||||
- Com NPM: `npm install -g agent-browser && agent-browser install`
|
|
||||||
- **Documentação:** https://agent-browser.dev/
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. Instalação Rápida (Copia e Cola)
|
|
||||||
|
|
||||||
Para instalar as ferramentas base de forma ágil e em lote, copie os blocos de comando abaixo e os rode inteiramente em seu terminal (requer `npm`, `bun` e `snap` já configurados).
|
|
||||||
|
|
||||||
### Linux (Debian / Ubuntu)
|
### Linux (Debian / Ubuntu)
|
||||||
|
|
||||||
|
|
@ -116,10 +103,7 @@ sudo apt-get install -y ripgrep fd-find jq shellcheck bat tree eza httpie gh
|
||||||
# 2. Instalar ferramentas em Node
|
# 2. Instalar ferramentas em Node
|
||||||
npm install -g @ast-grep/cli @biomejs/biome
|
npm install -g @ast-grep/cli @biomejs/biome
|
||||||
|
|
||||||
# 3. Instalar automação de navegador para IA (visível com --headed)
|
# 3. Instalar yq via snap
|
||||||
bun i -g agent-browser && agent-browser install
|
|
||||||
|
|
||||||
# 4. Instalar yq via snap
|
|
||||||
sudo snap install yq
|
sudo snap install yq
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -129,5 +113,4 @@ sudo snap install yq
|
||||||
# Instalar utilitários essenciais
|
# Instalar utilitários essenciais
|
||||||
brew install ripgrep fd ast-grep jq yq shellcheck bat tree eza httpie gh
|
brew install ripgrep fd ast-grep jq yq shellcheck bat tree eza httpie gh
|
||||||
npm install -g @biomejs/biome
|
npm install -g @biomejs/biome
|
||||||
bun i -g agent-browser && agent-browser install
|
|
||||||
```
|
```
|
||||||
|
|
|
||||||
|
|
@ -141,4 +141,4 @@ O arquivo `./COMERCIAL/<nome-do-modulo>.md` deve seguir esta estrutura:
|
||||||
- Rule: `global/rules/escrita-natural` (padrão obrigatório de redação)
|
- Rule: `global/rules/escrita-natural` (padrão obrigatório de redação)
|
||||||
- Workflow: `agents/comercial/workflows/orcamento` (texto para documentos de orçamento e proposta — apresentação + lista de funcionalidades)
|
- Workflow: `agents/comercial/workflows/orcamento` (texto para documentos de orçamento e proposta — apresentação + lista de funcionalidades)
|
||||||
- Workflow: `agents/comercial/workflows/marketing` (peças de marketing digital — LinkedIn, Instagram, WhatsApp, E-mail)
|
- Workflow: `agents/comercial/workflows/marketing` (peças de marketing digital — LinkedIn, Instagram, WhatsApp, E-mail)
|
||||||
- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`) (para documentação técnica, não comercial)
|
- Workflow: `global/workflows/otimizar-codigos` (para documentação técnica, não comercial)
|
||||||
|
|
|
||||||
|
|
@ -47,7 +47,6 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
|
||||||
8. Implementar fluxos de navegação e estados de interface
|
8. Implementar fluxos de navegação e estados de interface
|
||||||
9. Criar e manter arquivo `{componente}.ajuda.md` co-localizado (para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`) sempre que houver ajuda contextual (ver `skills/adicionar-ajuda`)
|
9. Criar e manter arquivo `{componente}.ajuda.md` co-localizado (para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`) sempre que houver ajuda contextual (ver `skills/adicionar-ajuda`)
|
||||||
10. Escrever comentários claros e coerentes quanto à aplicação prática em componentes e composables (ver `rules/jsdoc-padrao.md`)
|
10. Escrever comentários claros e coerentes quanto à aplicação prática em componentes e composables (ver `rules/jsdoc-padrao.md`)
|
||||||
11. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`)** para acompanhamento do operador (ver `rules/testes-interface-agent-browser.md`)
|
|
||||||
|
|
||||||
## Restrições
|
## Restrições
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -185,5 +185,5 @@ Caso contrário, seguir os passos acima para criar a primeira implementação.
|
||||||
|
|
||||||
## Referências
|
## Referências
|
||||||
|
|
||||||
- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|
- Workflow: `global/workflows/otimizar-codigos`
|
||||||
- Skill: `global/skills/documentar-decisao-tecnica/SKILL` (para decisões que geram fluxogramas)
|
- Skill: `global/skills/documentar-decisao-tecnica/SKILL` (para decisões que geram fluxogramas)
|
||||||
|
|
|
||||||
File diff suppressed because one or more lines are too long
|
|
@ -232,7 +232,6 @@ Artefatos em `.agent-local/` sempre têm prioridade sobre os herdados de `.agent
|
||||||
|
|
||||||
## Referências Fundamentais
|
## Referências Fundamentais
|
||||||
|
|
||||||
- As 12 Regras Canônicas do Código Limpo — Workflow `global/workflows/codigo-limpo`
|
|
||||||
- Mergulho nos Padrões de Projeto — Alexander Shvets (https://refactoring.guru/pt-br)
|
- Mergulho nos Padrões de Projeto — Alexander Shvets (https://refactoring.guru/pt-br)
|
||||||
- Refatoração — Martin Fowler
|
- Refatoração — Martin Fowler
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -131,4 +131,4 @@ refactor(<módulo>): <técnica aplicada>
|
||||||
- Rule: `agents/refatorar/rules/refatoracao-segura`
|
- Rule: `agents/refatorar/rules/refatoracao-segura`
|
||||||
- Rule: `agents/refatorar/rules/solid-compliance`
|
- Rule: `agents/refatorar/rules/solid-compliance`
|
||||||
- Rule: `agents/refatorar/rules/design-patterns-pragmatico`
|
- Rule: `agents/refatorar/rules/design-patterns-pragmatico`
|
||||||
- Workflow global: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|
- Workflow global: `global/workflows/otimizar-codigos`
|
||||||
|
|
|
||||||
|
|
@ -45,7 +45,6 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
|
||||||
6. Identificar casos extremos e cenários de falha não cobertos
|
6. Identificar casos extremos e cenários de falha não cobertos
|
||||||
7. Validar schemas Zod contra dados reais de produção
|
7. Validar schemas Zod contra dados reais de produção
|
||||||
8. Documentar bugs encontrados com passos de reprodução
|
8. Documentar bugs encontrados com passos de reprodução
|
||||||
9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`)** para que o operador acompanhe cada ação na tela (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`)
|
|
||||||
|
|
||||||
## Restrições
|
## Restrições
|
||||||
|
|
||||||
|
|
@ -113,7 +112,6 @@ Artefatos em `.agent-local/` sempre têm prioridade sobre os herdados de `.agent
|
||||||
- [ ] Casos extremos (null, vazio, limite) testados?
|
- [ ] Casos extremos (null, vazio, limite) testados?
|
||||||
- [ ] Erros de rede/banco simulados?
|
- [ ] Erros de rede/banco simulados?
|
||||||
- [ ] Performance em volume realista de dados?
|
- [ ] Performance em volume realista de dados?
|
||||||
- [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) com screenshots comprobatórios?
|
|
||||||
|
|
||||||
## Memória Persistente & Identidade do Projeto
|
## Memória Persistente & Identidade do Projeto
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -45,7 +45,6 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
|
||||||
6. Organizar a hierarquia de informação das telas
|
6. Organizar a hierarquia de informação das telas
|
||||||
7. Revisar labels, placeholders e textos de ajuda
|
7. Revisar labels, placeholders e textos de ajuda
|
||||||
8. Identificar inconsistências de UX entre módulos
|
8. Identificar inconsistências de UX entre módulos
|
||||||
9. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`)** para que o operador acompanhe a validação visual (ver `rules/testes-interface-agent-browser.md`)
|
|
||||||
|
|
||||||
## Restrições
|
## Restrições
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -63,4 +63,4 @@ Sem esta regra, arquivos crescem silenciosamente até se tornarem intocáveis
|
||||||
## Referências
|
## Referências
|
||||||
|
|
||||||
- Script: `verificar-linhas.sh`
|
- Script: `verificar-linhas.sh`
|
||||||
- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|
- Workflow: `global/workflows/otimizar-codigos`
|
||||||
|
|
|
||||||
|
|
@ -1,133 +0,0 @@
|
||||||
---
|
|
||||||
type: rule
|
|
||||||
name: testes-interface-agent-browser
|
|
||||||
description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) ao operador.
|
|
||||||
scope: global
|
|
||||||
trigger: always_on
|
|
||||||
updatedAt: "2026-09-16"
|
|
||||||
---
|
|
||||||
|
|
||||||
# Regra: Testes Automatizados de Interface e Navegação com agent-browser
|
|
||||||
|
|
||||||
## Contexto
|
|
||||||
|
|
||||||
Quando uma IA precisa testar o frontend, validar jornadas de usuário, inspecionar componentes gráficos ou simular interações na tela, é crucial utilizar uma ferramenta rápida, determinística e econômica em tokens. Além disso, o operador humano deve sempre ter visibilidade do que a IA está executando em tempo real na interface gráfica.
|
|
||||||
|
|
||||||
Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** para qualquer teste de interface ou automação de navegador conduzida por agentes de IA.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Regra
|
|
||||||
|
|
||||||
Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar realizar testes automatizados de interface (E2E), navegar no frontend ou inspecionar telas ativas, **DEVE OBRIGATORIAMENTE**:
|
|
||||||
|
|
||||||
1. **Utilizar o `agent-browser`** como ferramenta oficial de automação de navegador.
|
|
||||||
2. **Executar SEMPRE em Modo Visível (`--headed`)**:
|
|
||||||
- A janela do navegador **deve sempre aparecer na área de trabalho do operador**.
|
|
||||||
- É **terminantemente proibido** rodar testes ocultos (headless silencioso), a menos que o operador humano solicite expressamente essa exceção.
|
|
||||||
- Usar a flag `--headed` nos comandos de abertura (`agent-browser open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
|
|
||||||
3. **Utilizar o modelo de referências (`@ref`)**:
|
|
||||||
- Mapear a tela via `agent-browser snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
|
|
||||||
- Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
|
|
||||||
4. **Registrar evidências e fechar sessão**:
|
|
||||||
- Registrar comprovações visuais com `agent-browser screenshot <arquivo.png>`.
|
|
||||||
- Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Instalação e Configuração
|
|
||||||
|
|
||||||
O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Instalação global via bun (recomendado)
|
|
||||||
bun i -g agent-browser
|
|
||||||
|
|
||||||
# Download do motor do navegador (primeira execução)
|
|
||||||
agent-browser install
|
|
||||||
```
|
|
||||||
|
|
||||||
Documentação de referência: **https://agent-browser.dev/**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Protocolo Operacional Padrão
|
|
||||||
|
|
||||||
Todo teste ou navegação de interface executado pela IA deve seguir o fluxo:
|
|
||||||
|
|
||||||
### 1. Abertura com Janela Visível
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Abrir sempre visível ao operador humano
|
|
||||||
agent-browser open --headed http://localhost:8080
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Inspeção de Elementos Interativos
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2)
|
|
||||||
agent-browser snapshot -i
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Interações por Referência Direta
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Interagir diretamente com os elementos identificados no snapshot
|
|
||||||
agent-browser fill @e1 "usuario@exemplo.com"
|
|
||||||
agent-browser fill @e2 "senhaSegura123"
|
|
||||||
agent-browser click @e3
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Validação e Evidência
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Aguardar estabilização se houver transição assíncrona
|
|
||||||
agent-browser wait 1000
|
|
||||||
|
|
||||||
# Obter novo snapshot para verificar estado pós-ação
|
|
||||||
agent-browser snapshot -i
|
|
||||||
|
|
||||||
# Capturar evidência gráfica do teste
|
|
||||||
agent-browser screenshot evidencias/teste-login-sucesso.png
|
|
||||||
|
|
||||||
# Verificar erros no console do navegador
|
|
||||||
agent-browser console
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5. Finalização
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Fechar a sessão do navegador ao concluir o teste
|
|
||||||
agent-browser close
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Boas Práticas e Proibições
|
|
||||||
|
|
||||||
### Proibido ❌
|
|
||||||
- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`.
|
|
||||||
- **Proibido despejar o HTML/DOM completo** no contexto da IA (consome milhares de tokens desnecessários; use sempre `snapshot -i`).
|
|
||||||
- **Proibido navegar para URLs desconhecidas** ou inventadas pela IA fora do escopo aprovado do teste.
|
|
||||||
- **Proibido deixar processos ou janelas orfãs** após a conclusão do trabalho (sempre executar `agent-browser close`).
|
|
||||||
|
|
||||||
### Permitido e Recomendado ✅
|
|
||||||
- Manter sessões persistentes quando necessário via `--session <nome>` e `--restore`.
|
|
||||||
- Usar `agent-browser screenshot --annotate` para inspecionar layouts complexos com visão computacional.
|
|
||||||
- Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Impacto
|
|
||||||
|
|
||||||
- **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real.
|
|
||||||
- **Eficiência de tokens**: A árvore de acessibilidade reduz o consumo de contexto em até 90% comparado a inspeções de DOM HTML bruto.
|
|
||||||
- **Confiabilidade**: Interações determinísticas por `@ref` eliminam fragilidade de seletores CSS dinâmicos.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Referências
|
|
||||||
|
|
||||||
- Documentação Oficial: https://agent-browser.dev/
|
|
||||||
- Skill associada: `skills/testar-interface-agent-browser/SKILL.md`
|
|
||||||
- Ferramentas CLI: `.agent/TOOLS`
|
|
||||||
|
|
@ -66,5 +66,5 @@ Regras obrigatórias para TypeScript neste projeto:
|
||||||
## Referências
|
## Referências
|
||||||
|
|
||||||
- Skill: `global/skills/diagnosticar-erros-build/SKILL` (quando erros de tipagem causam falhas de build em cascata)
|
- Skill: `global/skills/diagnosticar-erros-build/SKILL` (quando erros de tipagem causam falhas de build em cascata)
|
||||||
- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|
- Workflow: `global/workflows/otimizar-codigos` (padrão de documentação para casts temporários)
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -139,7 +139,7 @@ export const zProdutoCriar = z.object({
|
||||||
nome: z.string().trim().min(1),
|
nome: z.string().trim().min(1),
|
||||||
preco: z.coerce.number().positive(),
|
preco: z.coerce.number().positive(),
|
||||||
ativo: z.boolean().default(true),
|
ativo: z.boolean().default(true),
|
||||||
codigo: z.string().toUpperCase().nullish(),
|
codigo: z.string().toUpperCase().optional(),
|
||||||
tags: z.array(z.string()).default([]),
|
tags: z.array(z.string()).default([]),
|
||||||
})
|
})
|
||||||
|
|
||||||
|
|
@ -149,35 +149,7 @@ produto.nome = produto.nome.trim()
|
||||||
produto.codigo = produto.codigo?.toUpperCase()
|
produto.codigo = produto.codigo?.toUpperCase()
|
||||||
```
|
```
|
||||||
|
|
||||||
### 8. Colunas e Registros que Podem ser Nulos Devem Usar `.nullish()`
|
### 8. Composição e Enums Zod
|
||||||
|
|
||||||
Em schemas de tabelas, entidades e contratos de dados que mapeiam colunas do banco de dados ou campos de formulário/API que podem ser nulos ou omitidos, **DEVE-SE obrigatoriamente usar `.nullish()`** (nunca `.optional()` ou `.nullable()` isolados).
|
|
||||||
|
|
||||||
**Por que `.nullish()` é obrigatório?**
|
|
||||||
- **Bancos relacionais (PostgreSQL/Knex)**: colunas nulas retornam `null`.
|
|
||||||
- **Formulários e payloads parciais**: frequentemente omitem o campo (`undefined`) ou enviam `null` ao limpar.
|
|
||||||
- `.optional()` aceita apenas `undefined` — **falha** com `Expected string, received null` ao receber dados do banco ou payload com `null`.
|
|
||||||
- `.nullable()` aceita apenas `null` — **falha** com `Required` ao omitir o campo em atualizações parciais (`undefined`).
|
|
||||||
- `.nullish()` aceita ambos (`T | null | undefined`), garantindo interoperabilidade total entre banco, API e frontend sem erros de runtime.
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// ✅ CORRETO — coluna/registro opcional ou nulo com .nullish()
|
|
||||||
export const zPontosBase = z.object({
|
|
||||||
id: z.string().max(64).nullish(),
|
|
||||||
nome: z.string().min(1),
|
|
||||||
descricao: z.string().max(5000).nullish(),
|
|
||||||
codigo_empreendimento: zUUID.nullish(),
|
|
||||||
coordenadas: zCoordenadas.nullish(),
|
|
||||||
})
|
|
||||||
|
|
||||||
// ❌ ERRADO — quebra ao ler do banco quando a coluna for NULL
|
|
||||||
descricao: z.string().optional()
|
|
||||||
|
|
||||||
// ❌ ERRADO — quebra se o campo for omitido no payload (undefined)
|
|
||||||
descricao: z.string().nullable()
|
|
||||||
```
|
|
||||||
|
|
||||||
### 9. Composição e Enums Zod
|
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
// ✅ Composição de schemas via extend/partial
|
// ✅ Composição de schemas via extend/partial
|
||||||
|
|
|
||||||
|
|
@ -1,118 +0,0 @@
|
||||||
---
|
|
||||||
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.
|
|
||||||
|
|
@ -1,118 +0,0 @@
|
||||||
---
|
|
||||||
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.
|
|
||||||
|
|
@ -72,26 +72,6 @@ export const zUsuarioCriar = z.object({
|
||||||
| `z{Modulo}Config` | Configuração |
|
| `z{Modulo}Config` | Configuração |
|
||||||
| `z{Modulo}Ambiente` | Variáveis de ambiente |
|
| `z{Modulo}Ambiente` | Variáveis de ambiente |
|
||||||
|
|
||||||
### 2.4. Colunas e Campos que Podem ser Nulos: Usar `.nullish()`
|
|
||||||
|
|
||||||
Toda coluna do banco de dados relacional ou campo de entidade/registro que puder ser nulo ou omitido **DEVE** utilizar `.nullish()` (nunca `.optional()` ou `.nullable()` isolados):
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// ✅ CORRETO — aceita null (do banco PostgreSQL) e undefined (payload omitido)
|
|
||||||
export const zPontoCriar = z.object({
|
|
||||||
nome: z.string().min(1),
|
|
||||||
descricao: z.string().max(5000).nullish(),
|
|
||||||
codigo_empreendimento: zUUID.nullish(),
|
|
||||||
coordenadas: zCoordenadas.nullish(),
|
|
||||||
})
|
|
||||||
|
|
||||||
// ❌ ERRADO — quebra com null retornado pelo Knex/PostgreSQL
|
|
||||||
descricao: z.string().optional(),
|
|
||||||
|
|
||||||
// ❌ ERRADO — quebra quando a chave é omitida no payload (undefined)
|
|
||||||
descricao: z.string().nullable(),
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## PASSO 3 — Derivar o Tipo com `z.infer<>`
|
## PASSO 3 — Derivar o Tipo com `z.infer<>`
|
||||||
|
|
@ -195,7 +175,6 @@ Zero erros = concluído.
|
||||||
- [ ] A validação usa `safeParse` (exceto em boot/middleware)?
|
- [ ] A validação usa `safeParse` (exceto em boot/middleware)?
|
||||||
- [ ] A nomenclatura segue o padrão `z{Entidade}{Acao}`?
|
- [ ] A nomenclatura segue o padrão `z{Entidade}{Acao}`?
|
||||||
- [ ] Transformações (trim, coerce, default) estão no schema, não no handler?
|
- [ ] Transformações (trim, coerce, default) estão no schema, não no handler?
|
||||||
- [ ] Colunas e campos que podem ser nulos/opcionais utilizam `.nullish()` (em vez de `.optional()` ou `.nullable()` isolados)?
|
|
||||||
- [ ] Schemas derivados usam composição (.partial, .extend, .pick), não duplicação?
|
- [ ] Schemas derivados usam composição (.partial, .extend, .pick), não duplicação?
|
||||||
- [ ] `tsc --noEmit` passa sem erros?
|
- [ ] `tsc --noEmit` passa sem erros?
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -182,5 +182,5 @@ pnpm install && pnpm build
|
||||||
## Referências
|
## Referências
|
||||||
|
|
||||||
- Rules: `global/rules/typescript-sem-any`
|
- Rules: `global/rules/typescript-sem-any`
|
||||||
- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|
- Workflow: `global/workflows/otimizar-codigos`
|
||||||
- Skill: `global/skills/mapear-codigo-fonte/SKILL`
|
- Skill: `global/skills/mapear-codigo-fonte/SKILL`
|
||||||
|
|
|
||||||
|
|
@ -182,5 +182,5 @@ pnpm install && pnpm build
|
||||||
## Referências
|
## Referências
|
||||||
|
|
||||||
- Rules: `global/rules/typescript-sem-any`
|
- Rules: `global/rules/typescript-sem-any`
|
||||||
- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|
- Workflow: `global/workflows/otimizar-codigos`
|
||||||
- Skill: `global/skills/mapear-codigo-fonte/SKILL`
|
- Skill: `global/skills/mapear-codigo-fonte/SKILL`
|
||||||
|
|
|
||||||
|
|
@ -12,15 +12,9 @@ Use esta skill ao iniciar trabalho em um monorepo desconhecido, ao onboardar em
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## PASSO 1 — Identificar a Identidade do Módulo e o Gerenciador de Pacotes
|
## PASSO 1 — Identificar a Raiz e o Gerenciador de Pacotes
|
||||||
|
|
||||||
1. Consultar obrigatoriamente `<base_projeto>/memorias-ia/modulo.yml` para obter:
|
Localize os arquivos que definem a estratégia de monorepo:
|
||||||
- `modulo-id`: identificador canônico do módulo
|
|
||||||
- `modulo-caminho`: rota/prefixo de URL base
|
|
||||||
- `modulo-descricao`: escopo funcional e propósito de negócio
|
|
||||||
- `modulo-tipo`: arquitetura e stack técnica
|
|
||||||
|
|
||||||
2. Localize os arquivos que definem a estratégia de monorepo:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Identificar o gerenciador e workspace config
|
# Identificar o gerenciador e workspace config
|
||||||
|
|
@ -29,7 +23,6 @@ ls -la package.json pnpm-workspace.yaml lerna.json turbo.json nx.json tsconfig.b
|
||||||
|
|
||||||
Elementos a extrair:
|
Elementos a extrair:
|
||||||
|
|
||||||
- **Identidade do Módulo**: `modulo-id` e `modulo-caminho` em `memorias-ia/modulo.yml`
|
|
||||||
- **Gerenciador**: `pnpm` (workspaces em `pnpm-workspace.yaml`), `npm/yarn` (workspaces em `package.json`), ou `nx`/`turbo`
|
- **Gerenciador**: `pnpm` (workspaces em `pnpm-workspace.yaml`), `npm/yarn` (workspaces em `package.json`), ou `nx`/`turbo`
|
||||||
- **Pacotes compartilhados**: diretórios listados em `packages:` ou `workspaces:`
|
- **Pacotes compartilhados**: diretórios listados em `packages:` ou `workspaces:`
|
||||||
- **Apps/serviços**: diretórios de aplicações deployáveis
|
- **Apps/serviços**: diretórios de aplicações deployáveis
|
||||||
|
|
@ -164,4 +157,4 @@ Descrever como os dados fluem entre pacotes.
|
||||||
## Referências
|
## Referências
|
||||||
|
|
||||||
- Rules: `global/rules/typescript-sem-any`
|
- Rules: `global/rules/typescript-sem-any`
|
||||||
- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|
- Workflow: `global/workflows/otimizar-codigos`
|
||||||
|
|
|
||||||
|
|
@ -164,4 +164,4 @@ Descrever como os dados fluem entre pacotes.
|
||||||
## Referências
|
## Referências
|
||||||
|
|
||||||
- Rules: `global/rules/typescript-sem-any`
|
- Rules: `global/rules/typescript-sem-any`
|
||||||
- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|
- Workflow: `global/workflows/otimizar-codigos`
|
||||||
|
|
|
||||||
|
|
@ -1,166 +0,0 @@
|
||||||
---
|
|
||||||
name: testar-interface-agent-browser
|
|
||||||
description: >
|
|
||||||
Executar testes automatizados de interface (E2E), navegação e validação visual
|
|
||||||
no frontend utilizando a CLI agent-browser, com janela sempre visível (--headed).
|
|
||||||
scope: global
|
|
||||||
---
|
|
||||||
|
|
||||||
# Skill: Testar Interface com agent-browser
|
|
||||||
|
|
||||||
## Objetivo
|
|
||||||
|
|
||||||
Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuário, preencher formulários, inspecionar componentes gráficos e validar fluxos no frontend de maneira rápida, determinística e econômica em tokens, garantindo que o operador humano sempre acompanhe a execução na tela.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ⚠️ Princípio Fundamental: Navegador Sempre Visível ao Operador
|
|
||||||
|
|
||||||
Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na área de trabalho do operador:
|
|
||||||
|
|
||||||
- Usar sempre a flag `--headed` na abertura:
|
|
||||||
```bash
|
|
||||||
agent-browser open --headed <url>
|
|
||||||
```
|
|
||||||
- Ou exportar no ambiente:
|
|
||||||
```bash
|
|
||||||
export AGENT_BROWSER_HEADED=true
|
|
||||||
```
|
|
||||||
- **Nunca executar em modo headless silencioso**, a menos que o operador humano solicite expressamente essa exceção.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Pré-requisitos e Instalação
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Verificar se o agent-browser já está instalado
|
|
||||||
which agent-browser || bun i -g agent-browser
|
|
||||||
|
|
||||||
# Baixar o binário do Chromium gerenciado pelo daemon (na primeira vez)
|
|
||||||
agent-browser install
|
|
||||||
```
|
|
||||||
|
|
||||||
Documentação oficial: **https://agent-browser.dev/**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Fluxo Operacional Passo a Passo
|
|
||||||
|
|
||||||
### 1. Iniciar Sessão Visível
|
|
||||||
Abra a aplicação frontend mantendo a janela visível ao operador:
|
|
||||||
```bash
|
|
||||||
agent-browser open --headed http://localhost:8080
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Obter Snapshot Interativo
|
|
||||||
Gere a árvore de acessibilidade enxuta com referências numéricas:
|
|
||||||
```bash
|
|
||||||
agent-browser snapshot -i
|
|
||||||
```
|
|
||||||
*Saída de exemplo:*
|
|
||||||
```text
|
|
||||||
- heading "Qualificação de Fornecedores" [ref=e1]
|
|
||||||
- textbox "CNPJ" [ref=e2]
|
|
||||||
- textbox "Razão Social" [ref=e3]
|
|
||||||
- button "Pesquisar" [ref=e4]
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Interagir com Determinismo
|
|
||||||
Utilize as referências identificadas (`@e1`, `@e2`, etc.):
|
|
||||||
```bash
|
|
||||||
# Preenchimento de campos de texto
|
|
||||||
agent-browser fill @e2 "12.345.678/0001-90"
|
|
||||||
agent-browser fill @e3 "Indústria Modelo LTDA"
|
|
||||||
|
|
||||||
# Acionamento de botões e links
|
|
||||||
agent-browser click @e4
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Aguardar Transição e Validar Estado
|
|
||||||
Se a ação disparar chamada assíncrona ou animação, aguarde a estabilização:
|
|
||||||
```bash
|
|
||||||
# Aguardar 1 a 2 segundos
|
|
||||||
agent-browser wait 1500
|
|
||||||
|
|
||||||
# Capturar novo snapshot para verificar se a lista ou mensagem apareceu
|
|
||||||
agent-browser snapshot -i
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5. Verificar Logs de Erro no Console e Rede
|
|
||||||
Assegure que nenhum erro de script ou requisição 500 ocorreu silenciosamente:
|
|
||||||
```bash
|
|
||||||
# Inspecionar mensagens do console do browser
|
|
||||||
agent-browser console
|
|
||||||
|
|
||||||
# Verificar requisições de rede falhadas
|
|
||||||
agent-browser network
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6. Registrar Evidência Visual
|
|
||||||
Capture um screenshot para comprovação do resultado do teste:
|
|
||||||
```bash
|
|
||||||
# Screenshot padrão ou anotado com identificadores visuais
|
|
||||||
agent-browser screenshot evidencias/resultado-sucesso.png
|
|
||||||
# agent-browser screenshot --annotate evidencias/resultado-anotado.png
|
|
||||||
```
|
|
||||||
|
|
||||||
### 7. Encerrar Navegador
|
|
||||||
Finalize a sessão limpando os processos do daemon:
|
|
||||||
```bash
|
|
||||||
agent-browser close
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Tabela Rápida de Comandos
|
|
||||||
|
|
||||||
| Ação | Comando |
|
|
||||||
|---|---|
|
|
||||||
| **Abrir tela (visível)** | `agent-browser open --headed <url>` |
|
|
||||||
| **Snapshot de elementos** | `agent-browser snapshot -i` |
|
|
||||||
| **Clicar elemento** | `agent-browser click @ref` |
|
|
||||||
| **Preencher campo** | `agent-browser fill @ref "valor"` |
|
|
||||||
| **Selecionar dropdown** | `agent-browser select @ref "opcao"` |
|
|
||||||
| **Pressionar tecla** | `agent-browser press Enter` |
|
|
||||||
| **Obter texto** | `agent-browser get text @ref` |
|
|
||||||
| **Aguardar tempo** | `agent-browser wait <ms>` |
|
|
||||||
| **Aguardar seletor** | `agent-browser wait --selector "<seletor>"` |
|
|
||||||
| **Inspecionar console** | `agent-browser console` |
|
|
||||||
| **Inspecionar rede** | `agent-browser network` |
|
|
||||||
| **Screenshot** | `agent-browser screenshot <arquivo.png>` |
|
|
||||||
| **Auditoria a11y (WCAG)** | `agent-browser a11y` |
|
|
||||||
| **Fechar sessão** | `agent-browser close` |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Sessões Persistentes e Autenticação
|
|
||||||
|
|
||||||
Para fluxos que necessitam manter login ativo entre comandos:
|
|
||||||
```bash
|
|
||||||
# Iniciar sessão nomeada com auto-restore
|
|
||||||
agent-browser --session auth-test --restore open --headed http://localhost:8080/login
|
|
||||||
|
|
||||||
# Verificar status da sessão
|
|
||||||
agent-browser session info --json
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Skills Nativas do agent-browser
|
|
||||||
|
|
||||||
O binário `agent-browser` possui guias aprofundados integrados que podem ser consultados a qualquer momento:
|
|
||||||
```bash
|
|
||||||
# Guia completo do core (todas as opções e referências)
|
|
||||||
agent-browser skills get core --full
|
|
||||||
|
|
||||||
# Guia para testes exploratórios e caça a bugs (dogfooding)
|
|
||||||
agent-browser skills get dogfood
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Boas Práticas no Ecossistema Azteca (Vue 3 / Vuetify)
|
|
||||||
|
|
||||||
1. **Campos Vuetify (`v-text-field`, `v-select`)**: O `snapshot -i` mapeia diretamente o `textbox` e o `combobox`. Utilize `agent-browser fill @ref` ou `agent-browser click @ref`.
|
|
||||||
2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser wait 500 && agent-browser snapshot -i` para interagir com o conteúdo do diálogo.
|
|
||||||
3. **Reporte de Teste**: Apresente ao operador o roteiro executado, evidências de screenshot e verificação de logs do console.
|
|
||||||
|
|
@ -1,103 +0,0 @@
|
||||||
---
|
|
||||||
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,30 +1,71 @@
|
||||||
---
|
---
|
||||||
type: workflow
|
type: workflow
|
||||||
name: otimizar-codigos
|
name: otimizar-codigos
|
||||||
description: Agente especialista em limpeza e refatoração de código (Alias compatível para /codigo-limpo)
|
description: Agente especialista em limpeza e refatoração de código
|
||||||
scope: global
|
scope: global
|
||||||
updatedAt: "2026-09-16"
|
updatedAt: "2026-06-03"
|
||||||
---
|
---
|
||||||
|
|
||||||
# Workflow: /otimizar-codigos (Alias para /codigo-limpo)
|
Você é um agente especialista em limpeza e refatoração de código para projetos TypeScript, Vue 3, TSX e JSX.
|
||||||
|
|
||||||
> ⚡ **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**.
|
Sua missão é melhorar a legibilidade, organização e manutenção do código, sem alterar o comportamento funcional.
|
||||||
|
|
||||||
## As 12 Regras Canônicas
|
## Regras principais
|
||||||
|
|
||||||
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.
|
1. Não altere regras de negócio.
|
||||||
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.
|
2. Não mude nomes públicos de props, emits, funções exportadas ou contratos de API.
|
||||||
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.
|
3. Não remova validações existentes.
|
||||||
4. **Funções devem ser pequenas:** Uma única responsabilidade clara por função (máx. 25-30 linhas).
|
4. Não altere layout visual sem necessidade.
|
||||||
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.
|
5. Nenhum arquivo `.vue`, `.ts`, `.tsx` ou `.jsx` deve ultrapassar 250 linhas.
|
||||||
6. **Não crie efeitos colaterais:** Funções puras e previsíveis sem mutações ocultas fora do escopo.
|
6. Se o arquivo estiver grande, proponha separação em:
|
||||||
7. **Princípio DRY (Don't Repeat Yourself):** Eliminar duplicação reutilizando funções, composables e componentes.
|
- composables
|
||||||
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`.
|
- helpers
|
||||||
9. **Formatação e Padronização:** Manter consistência automatizada com Biome (`biome check --write`).
|
- constants
|
||||||
10. **Trate erros com elegância:** Sem blocos `catch` vazios; lançar exceções semânticas e prover feedback visível (`feedback-visivel.md`).
|
- dispatch tables
|
||||||
11. **Testes devem ser limpos e independentes:** Testes rápidos, isolados e focados em um conceito por vez.
|
- arquivos `.css` separados
|
||||||
12. **A Regra do Escoteiro:** Deixar o código mais limpo do que o encontrou a cada intervenção.
|
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).
|
||||||
|
|
||||||
---
|
## O que limpar
|
||||||
|
|
||||||
Para a documentação completa, detalhes operacionais e exemplos práticos, consulte **[`global/workflows/codigo-limpo.md`](./codigo-limpo.md)**.
|
- 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.
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
{
|
{
|
||||||
"versao": "3.2.0",
|
"versao": "3.2.0",
|
||||||
"atualizadoEm": "2026-09-16",
|
"atualizadoEm": "2026-09-02",
|
||||||
"projeto": "e-licencie",
|
"projeto": "e-licencie",
|
||||||
"artefatos": {
|
"artefatos": {
|
||||||
"global": {
|
"global": {
|
||||||
|
|
@ -28,12 +28,10 @@
|
||||||
"global/rules/typescript-sem-any.md",
|
"global/rules/typescript-sem-any.md",
|
||||||
"global/rules/zod-validacao-padrao.md",
|
"global/rules/zod-validacao-padrao.md",
|
||||||
"global/rules/ddd-documentacao-primeiro.md",
|
"global/rules/ddd-documentacao-primeiro.md",
|
||||||
"global/rules/identidade-modulo.md",
|
"global/rules/identidade-modulo.md"
|
||||||
"global/rules/testes-interface-agent-browser.md"
|
|
||||||
],
|
],
|
||||||
"workflows": [
|
"workflows": [
|
||||||
"global/workflows/aprimora-ia.md",
|
"global/workflows/aprimora-ia.md",
|
||||||
"global/workflows/codigo-limpo.md",
|
|
||||||
"global/workflows/doc.md",
|
"global/workflows/doc.md",
|
||||||
"global/workflows/documentacao.md",
|
"global/workflows/documentacao.md",
|
||||||
"global/workflows/documentar-regras-negocio.md",
|
"global/workflows/documentar-regras-negocio.md",
|
||||||
|
|
@ -41,7 +39,6 @@
|
||||||
"global/workflows/ux.md"
|
"global/workflows/ux.md"
|
||||||
],
|
],
|
||||||
"skills": [
|
"skills": [
|
||||||
"global/skills/codigo-limpo/SKILL.md",
|
|
||||||
"global/skills/criar-schema-zod/SKILL.md",
|
"global/skills/criar-schema-zod/SKILL.md",
|
||||||
"global/skills/diagnosticar-antes-corrigir/SKILL.md",
|
"global/skills/diagnosticar-antes-corrigir/SKILL.md",
|
||||||
"global/skills/diagnosticar-erros-build/SKILL.md",
|
"global/skills/diagnosticar-erros-build/SKILL.md",
|
||||||
|
|
@ -52,8 +49,7 @@
|
||||||
"global/skills/documentar-regras-negocio/SKILL.md",
|
"global/skills/documentar-regras-negocio/SKILL.md",
|
||||||
"global/skills/mapear-codigo-fonte/SKILL.md",
|
"global/skills/mapear-codigo-fonte/SKILL.md",
|
||||||
"global/skills/onboarding-projeto/SKILL.md",
|
"global/skills/onboarding-projeto/SKILL.md",
|
||||||
"global/skills/orquestrar-agentes/SKILL.md",
|
"global/skills/orquestrar-agentes/SKILL.md"
|
||||||
"global/skills/testar-interface-agent-browser/SKILL.md"
|
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
"documentacao": {
|
"documentacao": {
|
||||||
|
|
@ -185,8 +181,7 @@
|
||||||
"persona": "agents/testes/persona",
|
"persona": "agents/testes/persona",
|
||||||
"config": "agents/testes/agent.json",
|
"config": "agents/testes/agent.json",
|
||||||
"skills": [
|
"skills": [
|
||||||
"agents/testes/skills/diagnosticar-cobertura-testes/SKILL.md",
|
"agents/testes/skills/diagnosticar-cobertura-testes/SKILL.md"
|
||||||
"skills/testar-interface-agent-browser/SKILL.md"
|
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
"ux": {
|
"ux": {
|
||||||
|
|
|
||||||
|
|
@ -63,4 +63,4 @@ Sem esta regra, arquivos crescem silenciosamente até se tornarem intocáveis
|
||||||
## Referências
|
## Referências
|
||||||
|
|
||||||
- Script: `verificar-linhas.sh`
|
- Script: `verificar-linhas.sh`
|
||||||
- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|
- Workflow: `global/workflows/otimizar-codigos`
|
||||||
|
|
|
||||||
|
|
@ -1,133 +0,0 @@
|
||||||
---
|
|
||||||
type: rule
|
|
||||||
name: testes-interface-agent-browser
|
|
||||||
description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) ao operador.
|
|
||||||
scope: global
|
|
||||||
trigger: always_on
|
|
||||||
updatedAt: "2026-09-16"
|
|
||||||
---
|
|
||||||
|
|
||||||
# Regra: Testes Automatizados de Interface e Navegação com agent-browser
|
|
||||||
|
|
||||||
## Contexto
|
|
||||||
|
|
||||||
Quando uma IA precisa testar o frontend, validar jornadas de usuário, inspecionar componentes gráficos ou simular interações na tela, é crucial utilizar uma ferramenta rápida, determinística e econômica em tokens. Além disso, o operador humano deve sempre ter visibilidade do que a IA está executando em tempo real na interface gráfica.
|
|
||||||
|
|
||||||
Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** para qualquer teste de interface ou automação de navegador conduzida por agentes de IA.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Regra
|
|
||||||
|
|
||||||
Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar realizar testes automatizados de interface (E2E), navegar no frontend ou inspecionar telas ativas, **DEVE OBRIGATORIAMENTE**:
|
|
||||||
|
|
||||||
1. **Utilizar o `agent-browser`** como ferramenta oficial de automação de navegador.
|
|
||||||
2. **Executar SEMPRE em Modo Visível (`--headed`)**:
|
|
||||||
- A janela do navegador **deve sempre aparecer na área de trabalho do operador**.
|
|
||||||
- É **terminantemente proibido** rodar testes ocultos (headless silencioso), a menos que o operador humano solicite expressamente essa exceção.
|
|
||||||
- Usar a flag `--headed` nos comandos de abertura (`agent-browser open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
|
|
||||||
3. **Utilizar o modelo de referências (`@ref`)**:
|
|
||||||
- Mapear a tela via `agent-browser snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
|
|
||||||
- Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
|
|
||||||
4. **Registrar evidências e fechar sessão**:
|
|
||||||
- Registrar comprovações visuais com `agent-browser screenshot <arquivo.png>`.
|
|
||||||
- Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Instalação e Configuração
|
|
||||||
|
|
||||||
O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Instalação global via bun (recomendado)
|
|
||||||
bun i -g agent-browser
|
|
||||||
|
|
||||||
# Download do motor do navegador (primeira execução)
|
|
||||||
agent-browser install
|
|
||||||
```
|
|
||||||
|
|
||||||
Documentação de referência: **https://agent-browser.dev/**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Protocolo Operacional Padrão
|
|
||||||
|
|
||||||
Todo teste ou navegação de interface executado pela IA deve seguir o fluxo:
|
|
||||||
|
|
||||||
### 1. Abertura com Janela Visível
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Abrir sempre visível ao operador humano
|
|
||||||
agent-browser open --headed http://localhost:8080
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Inspeção de Elementos Interativos
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2)
|
|
||||||
agent-browser snapshot -i
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Interações por Referência Direta
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Interagir diretamente com os elementos identificados no snapshot
|
|
||||||
agent-browser fill @e1 "usuario@exemplo.com"
|
|
||||||
agent-browser fill @e2 "senhaSegura123"
|
|
||||||
agent-browser click @e3
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Validação e Evidência
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Aguardar estabilização se houver transição assíncrona
|
|
||||||
agent-browser wait 1000
|
|
||||||
|
|
||||||
# Obter novo snapshot para verificar estado pós-ação
|
|
||||||
agent-browser snapshot -i
|
|
||||||
|
|
||||||
# Capturar evidência gráfica do teste
|
|
||||||
agent-browser screenshot evidencias/teste-login-sucesso.png
|
|
||||||
|
|
||||||
# Verificar erros no console do navegador
|
|
||||||
agent-browser console
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5. Finalização
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Fechar a sessão do navegador ao concluir o teste
|
|
||||||
agent-browser close
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Boas Práticas e Proibições
|
|
||||||
|
|
||||||
### Proibido ❌
|
|
||||||
- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`.
|
|
||||||
- **Proibido despejar o HTML/DOM completo** no contexto da IA (consome milhares de tokens desnecessários; use sempre `snapshot -i`).
|
|
||||||
- **Proibido navegar para URLs desconhecidas** ou inventadas pela IA fora do escopo aprovado do teste.
|
|
||||||
- **Proibido deixar processos ou janelas orfãs** após a conclusão do trabalho (sempre executar `agent-browser close`).
|
|
||||||
|
|
||||||
### Permitido e Recomendado ✅
|
|
||||||
- Manter sessões persistentes quando necessário via `--session <nome>` e `--restore`.
|
|
||||||
- Usar `agent-browser screenshot --annotate` para inspecionar layouts complexos com visão computacional.
|
|
||||||
- Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Impacto
|
|
||||||
|
|
||||||
- **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real.
|
|
||||||
- **Eficiência de tokens**: A árvore de acessibilidade reduz o consumo de contexto em até 90% comparado a inspeções de DOM HTML bruto.
|
|
||||||
- **Confiabilidade**: Interações determinísticas por `@ref` eliminam fragilidade de seletores CSS dinâmicos.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Referências
|
|
||||||
|
|
||||||
- Documentação Oficial: https://agent-browser.dev/
|
|
||||||
- Skill associada: `skills/testar-interface-agent-browser/SKILL.md`
|
|
||||||
- Ferramentas CLI: `.agent/TOOLS`
|
|
||||||
|
|
@ -66,5 +66,5 @@ Regras obrigatórias para TypeScript neste projeto:
|
||||||
## Referências
|
## Referências
|
||||||
|
|
||||||
- Skill: `global/skills/diagnosticar-erros-build/SKILL` (quando erros de tipagem causam falhas de build em cascata)
|
- Skill: `global/skills/diagnosticar-erros-build/SKILL` (quando erros de tipagem causam falhas de build em cascata)
|
||||||
- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|
- Workflow: `global/workflows/otimizar-codigos` (padrão de documentação para casts temporários)
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -139,7 +139,7 @@ export const zProdutoCriar = z.object({
|
||||||
nome: z.string().trim().min(1),
|
nome: z.string().trim().min(1),
|
||||||
preco: z.coerce.number().positive(),
|
preco: z.coerce.number().positive(),
|
||||||
ativo: z.boolean().default(true),
|
ativo: z.boolean().default(true),
|
||||||
codigo: z.string().toUpperCase().nullish(),
|
codigo: z.string().toUpperCase().optional(),
|
||||||
tags: z.array(z.string()).default([]),
|
tags: z.array(z.string()).default([]),
|
||||||
})
|
})
|
||||||
|
|
||||||
|
|
@ -149,35 +149,7 @@ produto.nome = produto.nome.trim()
|
||||||
produto.codigo = produto.codigo?.toUpperCase()
|
produto.codigo = produto.codigo?.toUpperCase()
|
||||||
```
|
```
|
||||||
|
|
||||||
### 8. Colunas e Registros que Podem ser Nulos Devem Usar `.nullish()`
|
### 8. Composição e Enums Zod
|
||||||
|
|
||||||
Em schemas de tabelas, entidades e contratos de dados que mapeiam colunas do banco de dados ou campos de formulário/API que podem ser nulos ou omitidos, **DEVE-SE obrigatoriamente usar `.nullish()`** (nunca `.optional()` ou `.nullable()` isolados).
|
|
||||||
|
|
||||||
**Por que `.nullish()` é obrigatório?**
|
|
||||||
- **Bancos relacionais (PostgreSQL/Knex)**: colunas nulas retornam `null`.
|
|
||||||
- **Formulários e payloads parciais**: frequentemente omitem o campo (`undefined`) ou enviam `null` ao limpar.
|
|
||||||
- `.optional()` aceita apenas `undefined` — **falha** com `Expected string, received null` ao receber dados do banco ou payload com `null`.
|
|
||||||
- `.nullable()` aceita apenas `null` — **falha** com `Required` ao omitir o campo em atualizações parciais (`undefined`).
|
|
||||||
- `.nullish()` aceita ambos (`T | null | undefined`), garantindo interoperabilidade total entre banco, API e frontend sem erros de runtime.
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// ✅ CORRETO — coluna/registro opcional ou nulo com .nullish()
|
|
||||||
export const zPontosBase = z.object({
|
|
||||||
id: z.string().max(64).nullish(),
|
|
||||||
nome: z.string().min(1),
|
|
||||||
descricao: z.string().max(5000).nullish(),
|
|
||||||
codigo_empreendimento: zUUID.nullish(),
|
|
||||||
coordenadas: zCoordenadas.nullish(),
|
|
||||||
})
|
|
||||||
|
|
||||||
// ❌ ERRADO — quebra ao ler do banco quando a coluna for NULL
|
|
||||||
descricao: z.string().optional()
|
|
||||||
|
|
||||||
// ❌ ERRADO — quebra se o campo for omitido no payload (undefined)
|
|
||||||
descricao: z.string().nullable()
|
|
||||||
```
|
|
||||||
|
|
||||||
### 9. Composição e Enums Zod
|
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
// ✅ Composição de schemas via extend/partial
|
// ✅ Composição de schemas via extend/partial
|
||||||
|
|
|
||||||
|
|
@ -1,118 +0,0 @@
|
||||||
---
|
|
||||||
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.
|
|
||||||
|
|
@ -1,118 +0,0 @@
|
||||||
---
|
|
||||||
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.
|
|
||||||
|
|
@ -141,4 +141,4 @@ O arquivo `./COMERCIAL/<nome-do-modulo>.md` deve seguir esta estrutura:
|
||||||
- Rule: `global/rules/escrita-natural` (padrão obrigatório de redação)
|
- Rule: `global/rules/escrita-natural` (padrão obrigatório de redação)
|
||||||
- Workflow: `agents/comercial/workflows/orcamento` (texto para documentos de orçamento e proposta — apresentação + lista de funcionalidades)
|
- Workflow: `agents/comercial/workflows/orcamento` (texto para documentos de orçamento e proposta — apresentação + lista de funcionalidades)
|
||||||
- Workflow: `agents/comercial/workflows/marketing` (peças de marketing digital — LinkedIn, Instagram, WhatsApp, E-mail)
|
- Workflow: `agents/comercial/workflows/marketing` (peças de marketing digital — LinkedIn, Instagram, WhatsApp, E-mail)
|
||||||
- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`) (para documentação técnica, não comercial)
|
- Workflow: `global/workflows/otimizar-codigos` (para documentação técnica, não comercial)
|
||||||
|
|
|
||||||
|
|
@ -185,5 +185,5 @@ Caso contrário, seguir os passos acima para criar a primeira implementação.
|
||||||
|
|
||||||
## Referências
|
## Referências
|
||||||
|
|
||||||
- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|
- Workflow: `global/workflows/otimizar-codigos`
|
||||||
- Skill: `global/skills/documentar-decisao-tecnica/SKILL` (para decisões que geram fluxogramas)
|
- Skill: `global/skills/documentar-decisao-tecnica/SKILL` (para decisões que geram fluxogramas)
|
||||||
|
|
|
||||||
|
|
@ -72,26 +72,6 @@ export const zUsuarioCriar = z.object({
|
||||||
| `z{Modulo}Config` | Configuração |
|
| `z{Modulo}Config` | Configuração |
|
||||||
| `z{Modulo}Ambiente` | Variáveis de ambiente |
|
| `z{Modulo}Ambiente` | Variáveis de ambiente |
|
||||||
|
|
||||||
### 2.4. Colunas e Campos que Podem ser Nulos: Usar `.nullish()`
|
|
||||||
|
|
||||||
Toda coluna do banco de dados relacional ou campo de entidade/registro que puder ser nulo ou omitido **DEVE** utilizar `.nullish()` (nunca `.optional()` ou `.nullable()` isolados):
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// ✅ CORRETO — aceita null (do banco PostgreSQL) e undefined (payload omitido)
|
|
||||||
export const zPontoCriar = z.object({
|
|
||||||
nome: z.string().min(1),
|
|
||||||
descricao: z.string().max(5000).nullish(),
|
|
||||||
codigo_empreendimento: zUUID.nullish(),
|
|
||||||
coordenadas: zCoordenadas.nullish(),
|
|
||||||
})
|
|
||||||
|
|
||||||
// ❌ ERRADO — quebra com null retornado pelo Knex/PostgreSQL
|
|
||||||
descricao: z.string().optional(),
|
|
||||||
|
|
||||||
// ❌ ERRADO — quebra quando a chave é omitida no payload (undefined)
|
|
||||||
descricao: z.string().nullable(),
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## PASSO 3 — Derivar o Tipo com `z.infer<>`
|
## PASSO 3 — Derivar o Tipo com `z.infer<>`
|
||||||
|
|
@ -195,7 +175,6 @@ Zero erros = concluído.
|
||||||
- [ ] A validação usa `safeParse` (exceto em boot/middleware)?
|
- [ ] A validação usa `safeParse` (exceto em boot/middleware)?
|
||||||
- [ ] A nomenclatura segue o padrão `z{Entidade}{Acao}`?
|
- [ ] A nomenclatura segue o padrão `z{Entidade}{Acao}`?
|
||||||
- [ ] Transformações (trim, coerce, default) estão no schema, não no handler?
|
- [ ] Transformações (trim, coerce, default) estão no schema, não no handler?
|
||||||
- [ ] Colunas e campos que podem ser nulos/opcionais utilizam `.nullish()` (em vez de `.optional()` ou `.nullable()` isolados)?
|
|
||||||
- [ ] Schemas derivados usam composição (.partial, .extend, .pick), não duplicação?
|
- [ ] Schemas derivados usam composição (.partial, .extend, .pick), não duplicação?
|
||||||
- [ ] `tsc --noEmit` passa sem erros?
|
- [ ] `tsc --noEmit` passa sem erros?
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -182,5 +182,5 @@ pnpm install && pnpm build
|
||||||
## Referências
|
## Referências
|
||||||
|
|
||||||
- Rules: `global/rules/typescript-sem-any`
|
- Rules: `global/rules/typescript-sem-any`
|
||||||
- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|
- Workflow: `global/workflows/otimizar-codigos`
|
||||||
- Skill: `global/skills/mapear-codigo-fonte/SKILL`
|
- Skill: `global/skills/mapear-codigo-fonte/SKILL`
|
||||||
|
|
|
||||||
|
|
@ -164,4 +164,4 @@ Descrever como os dados fluem entre pacotes.
|
||||||
## Referências
|
## Referências
|
||||||
|
|
||||||
- Rules: `global/rules/typescript-sem-any`
|
- Rules: `global/rules/typescript-sem-any`
|
||||||
- Workflow: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|
- Workflow: `global/workflows/otimizar-codigos`
|
||||||
|
|
|
||||||
|
|
@ -1,39 +1,71 @@
|
||||||
---
|
---
|
||||||
type: workflow
|
type: workflow
|
||||||
name: otimizar-codigos
|
name: otimizar-codigos
|
||||||
description: Agente especialista em limpeza e refatoração de código (Alias compatível para /codigo-limpo)
|
description: Agente especialista em limpeza e refatoração de código
|
||||||
scope: global
|
scope: global
|
||||||
updatedAt: "2026-09-16"
|
updatedAt: "2026-06-03"
|
||||||
---
|
---
|
||||||
|
|
||||||
# Skill: /otimizar-codigos (Alias para /codigo-limpo)
|
Você é um agente especialista em limpeza e refatoração de código para projetos TypeScript, Vue 3, TSX e JSX.
|
||||||
|
|
||||||
> ⚡ **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**.
|
Sua missão é melhorar a legibilidade, organização e manutenção do código, sem alterar o comportamento funcional.
|
||||||
|
|
||||||
Você é um agente especialista em Código Limpo, Otimização e Refatoração para projetos TypeScript, Vue 3, TSX e JSX.
|
## Regras principais
|
||||||
|
|
||||||
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.
|
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).
|
||||||
|
|
||||||
## As 12 Regras Canônicas
|
## O que limpar
|
||||||
|
|
||||||
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.
|
- imports não utilizados
|
||||||
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.
|
- variáveis não utilizadas
|
||||||
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.
|
- funções duplicadas
|
||||||
4. **Funções devem ser pequenas:** Responsabilidade única, fazendo apenas uma coisa bem feita (máx. 25-30 linhas).
|
- nomes confusos
|
||||||
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.
|
- blocos muito grandes
|
||||||
6. **Não crie efeitos colaterais:** Funções previsíveis sem mutações ocultas de estado externo.
|
- condicionais repetidas
|
||||||
7. **Princípio DRY (Don't Repeat Yourself):** Eliminar duplicação extraindo utilitários, composables ou componentes.
|
- código morto
|
||||||
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`.
|
- comentários óbvios
|
||||||
9. **Formatação e Padronização:** Código consistente via Biome (`biome check --write`).
|
- funções inline complexas
|
||||||
10. **Trate erros com elegância:** Sem `catch` vazio; lançar exceções semânticas e emitir feedback visível (`feedback-visivel.md`).
|
- tipagens fracas ou `any` desnecessário
|
||||||
11. **Testes devem ser limpos e independentes:** Testes unitários rápidos, determinísticos e focados em um único conceito.
|
- componentes com responsabilidade demais
|
||||||
12. **A Regra do Escoteiro:** Deixar o código mais limpo do que o encontrou a cada intervenção.
|
|
||||||
|
|
||||||
## Diretrizes Operacionais
|
## Padrões desejados
|
||||||
|
|
||||||
- Nunca altere regras de negócio nem quebre contratos públicos de API/props.
|
- Preferir funções pequenas e nomeadas.
|
||||||
- Nunca use `any` ou `@ts-ignore`.
|
- Usar `computed`, `ref` e `reactive` de forma clara.
|
||||||
- O `<script setup lang="ts">` de componentes Vue não deve ser desmembrado do `.vue`.
|
- Usar `PropType<T>` quando a prop tiver tipo complexo.
|
||||||
- CSS longo pode ser extraído para `Nome.css` co-localizado.
|
- 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.
|
||||||
|
|
||||||
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)**.
|
## 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.
|
||||||
|
|
@ -131,4 +131,4 @@ refactor(<módulo>): <técnica aplicada>
|
||||||
- Rule: `agents/refatorar/rules/refatoracao-segura`
|
- Rule: `agents/refatorar/rules/refatoracao-segura`
|
||||||
- Rule: `agents/refatorar/rules/solid-compliance`
|
- Rule: `agents/refatorar/rules/solid-compliance`
|
||||||
- Rule: `agents/refatorar/rules/design-patterns-pragmatico`
|
- Rule: `agents/refatorar/rules/design-patterns-pragmatico`
|
||||||
- Workflow global: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|
- Workflow global: `global/workflows/otimizar-codigos`
|
||||||
|
|
|
||||||
|
|
@ -1,166 +0,0 @@
|
||||||
---
|
|
||||||
name: testar-interface-agent-browser
|
|
||||||
description: >
|
|
||||||
Executar testes automatizados de interface (E2E), navegação e validação visual
|
|
||||||
no frontend utilizando a CLI agent-browser, com janela sempre visível (--headed).
|
|
||||||
scope: global
|
|
||||||
---
|
|
||||||
|
|
||||||
# Skill: Testar Interface com agent-browser
|
|
||||||
|
|
||||||
## Objetivo
|
|
||||||
|
|
||||||
Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuário, preencher formulários, inspecionar componentes gráficos e validar fluxos no frontend de maneira rápida, determinística e econômica em tokens, garantindo que o operador humano sempre acompanhe a execução na tela.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ⚠️ Princípio Fundamental: Navegador Sempre Visível ao Operador
|
|
||||||
|
|
||||||
Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na área de trabalho do operador:
|
|
||||||
|
|
||||||
- Usar sempre a flag `--headed` na abertura:
|
|
||||||
```bash
|
|
||||||
agent-browser open --headed <url>
|
|
||||||
```
|
|
||||||
- Ou exportar no ambiente:
|
|
||||||
```bash
|
|
||||||
export AGENT_BROWSER_HEADED=true
|
|
||||||
```
|
|
||||||
- **Nunca executar em modo headless silencioso**, a menos que o operador humano solicite expressamente essa exceção.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Pré-requisitos e Instalação
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Verificar se o agent-browser já está instalado
|
|
||||||
which agent-browser || bun i -g agent-browser
|
|
||||||
|
|
||||||
# Baixar o binário do Chromium gerenciado pelo daemon (na primeira vez)
|
|
||||||
agent-browser install
|
|
||||||
```
|
|
||||||
|
|
||||||
Documentação oficial: **https://agent-browser.dev/**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Fluxo Operacional Passo a Passo
|
|
||||||
|
|
||||||
### 1. Iniciar Sessão Visível
|
|
||||||
Abra a aplicação frontend mantendo a janela visível ao operador:
|
|
||||||
```bash
|
|
||||||
agent-browser open --headed http://localhost:8080
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Obter Snapshot Interativo
|
|
||||||
Gere a árvore de acessibilidade enxuta com referências numéricas:
|
|
||||||
```bash
|
|
||||||
agent-browser snapshot -i
|
|
||||||
```
|
|
||||||
*Saída de exemplo:*
|
|
||||||
```text
|
|
||||||
- heading "Qualificação de Fornecedores" [ref=e1]
|
|
||||||
- textbox "CNPJ" [ref=e2]
|
|
||||||
- textbox "Razão Social" [ref=e3]
|
|
||||||
- button "Pesquisar" [ref=e4]
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Interagir com Determinismo
|
|
||||||
Utilize as referências identificadas (`@e1`, `@e2`, etc.):
|
|
||||||
```bash
|
|
||||||
# Preenchimento de campos de texto
|
|
||||||
agent-browser fill @e2 "12.345.678/0001-90"
|
|
||||||
agent-browser fill @e3 "Indústria Modelo LTDA"
|
|
||||||
|
|
||||||
# Acionamento de botões e links
|
|
||||||
agent-browser click @e4
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Aguardar Transição e Validar Estado
|
|
||||||
Se a ação disparar chamada assíncrona ou animação, aguarde a estabilização:
|
|
||||||
```bash
|
|
||||||
# Aguardar 1 a 2 segundos
|
|
||||||
agent-browser wait 1500
|
|
||||||
|
|
||||||
# Capturar novo snapshot para verificar se a lista ou mensagem apareceu
|
|
||||||
agent-browser snapshot -i
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5. Verificar Logs de Erro no Console e Rede
|
|
||||||
Assegure que nenhum erro de script ou requisição 500 ocorreu silenciosamente:
|
|
||||||
```bash
|
|
||||||
# Inspecionar mensagens do console do browser
|
|
||||||
agent-browser console
|
|
||||||
|
|
||||||
# Verificar requisições de rede falhadas
|
|
||||||
agent-browser network
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6. Registrar Evidência Visual
|
|
||||||
Capture um screenshot para comprovação do resultado do teste:
|
|
||||||
```bash
|
|
||||||
# Screenshot padrão ou anotado com identificadores visuais
|
|
||||||
agent-browser screenshot evidencias/resultado-sucesso.png
|
|
||||||
# agent-browser screenshot --annotate evidencias/resultado-anotado.png
|
|
||||||
```
|
|
||||||
|
|
||||||
### 7. Encerrar Navegador
|
|
||||||
Finalize a sessão limpando os processos do daemon:
|
|
||||||
```bash
|
|
||||||
agent-browser close
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Tabela Rápida de Comandos
|
|
||||||
|
|
||||||
| Ação | Comando |
|
|
||||||
|---|---|
|
|
||||||
| **Abrir tela (visível)** | `agent-browser open --headed <url>` |
|
|
||||||
| **Snapshot de elementos** | `agent-browser snapshot -i` |
|
|
||||||
| **Clicar elemento** | `agent-browser click @ref` |
|
|
||||||
| **Preencher campo** | `agent-browser fill @ref "valor"` |
|
|
||||||
| **Selecionar dropdown** | `agent-browser select @ref "opcao"` |
|
|
||||||
| **Pressionar tecla** | `agent-browser press Enter` |
|
|
||||||
| **Obter texto** | `agent-browser get text @ref` |
|
|
||||||
| **Aguardar tempo** | `agent-browser wait <ms>` |
|
|
||||||
| **Aguardar seletor** | `agent-browser wait --selector "<seletor>"` |
|
|
||||||
| **Inspecionar console** | `agent-browser console` |
|
|
||||||
| **Inspecionar rede** | `agent-browser network` |
|
|
||||||
| **Screenshot** | `agent-browser screenshot <arquivo.png>` |
|
|
||||||
| **Auditoria a11y (WCAG)** | `agent-browser a11y` |
|
|
||||||
| **Fechar sessão** | `agent-browser close` |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Sessões Persistentes e Autenticação
|
|
||||||
|
|
||||||
Para fluxos que necessitam manter login ativo entre comandos:
|
|
||||||
```bash
|
|
||||||
# Iniciar sessão nomeada com auto-restore
|
|
||||||
agent-browser --session auth-test --restore open --headed http://localhost:8080/login
|
|
||||||
|
|
||||||
# Verificar status da sessão
|
|
||||||
agent-browser session info --json
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Skills Nativas do agent-browser
|
|
||||||
|
|
||||||
O binário `agent-browser` possui guias aprofundados integrados que podem ser consultados a qualquer momento:
|
|
||||||
```bash
|
|
||||||
# Guia completo do core (todas as opções e referências)
|
|
||||||
agent-browser skills get core --full
|
|
||||||
|
|
||||||
# Guia para testes exploratórios e caça a bugs (dogfooding)
|
|
||||||
agent-browser skills get dogfood
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Boas Práticas no Ecossistema Azteca (Vue 3 / Vuetify)
|
|
||||||
|
|
||||||
1. **Campos Vuetify (`v-text-field`, `v-select`)**: O `snapshot -i` mapeia diretamente o `textbox` e o `combobox`. Utilize `agent-browser fill @ref` ou `agent-browser click @ref`.
|
|
||||||
2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser wait 500 && agent-browser snapshot -i` para interagir com o conteúdo do diálogo.
|
|
||||||
3. **Reporte de Teste**: Apresente ao operador o roteiro executado, evidências de screenshot e verificação de logs do console.
|
|
||||||
|
|
@ -42,7 +42,7 @@ if [ -n "$RESULTADO" ]; then
|
||||||
echo "$RESULTADO"
|
echo "$RESULTADO"
|
||||||
VIOLACOES=$(printf '%s\n' "$RESULTADO" | wc -l | tr -d ' ')
|
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❌ %s arquivo(s) violam o limite de %s linhas.\n" "$VIOLACOES" "$LIMITE"
|
||||||
printf "\n Resolva usando a orientação: .agent/global/workflows/codigo-limpo.md (ou /codigo-limpo)\n"
|
printf "\n Resolva usando a orientação: .agent/global/workflows/otimizar-codigos\n"
|
||||||
exit 1
|
exit 1
|
||||||
fi
|
fi
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue