refatoração dos agents

This commit is contained in:
Luiz Silva 2026-08-10 16:08:03 -03:00
parent 97acfb07df
commit 1177e31e56
104 changed files with 1068 additions and 3995 deletions

View file

@ -1,127 +0,0 @@
---
type: rule
name: coleta-automatica-memorias
description: Todo agente DEVE coletar e registrar conhecimento na Memória Azteca ao final de cada sessão de trabalho
scope: global
trigger: always_on
priority: alta
updatedAt: "2026-07-06"
---
# Regra: Coleta Automática de Memórias
## Contexto
A Memória Corporativa Azteca (`https://memoria-ia.idz.one`) perde informações valiosas quando agentes encerram sessões sem registrar o conhecimento gerado. Esta regra garante que **nenhuma decisão, solução ou padrão se perca** entre sessões.
## Regra Principal
> **Ao final de cada sessão de trabalho**, todo agente DEVE executar o protocolo de coleta abaixo. Isto é **obrigatório e autônomo** — não requer permissão do operador.
## Gatilhos de Coleta Automática
O agente **DEVE** registrar na memória quando **qualquer** dos seguintes eventos ocorrer durante a sessão:
### 🔴 Obrigatório (sempre registrar)
| Evento | Categoria | Tipo |
|--------|-----------|------|
| Bug resolvido que não era trivial | `solucao-problemas` | `solucao-problemas` |
| Decisão arquitetural tomada | `decisoes` | `adr` |
| Regra de negócio descoberta ou alterada | `regras-negocio` | `nota` |
| Novo módulo ou funcionalidade criada | `modulos` | `referencia` |
| Padrão técnico definido ou alterado | `tecnologias` | `referencia` |
| Workaround para problema de infra | `infraestrutura` | `solucao-problemas` |
### 🟡 Recomendado (registrar quando significativo)
| Evento | Categoria | Tipo |
|--------|-----------|------|
| Migração de banco executada | `tecnologias` | `referencia` |
| Integração com serviço externo configurada | `tecnologias` | `referencia` |
| Componente/padrão de UI definido | `tecnologias` | `referencia` |
| Informação sobre cliente ou implantação | `clientes` | `nota` |
| Refatoração significativa realizada | `decisoes` | `adr` |
## Protocolo de Coleta (Fim de Sessão)
### Passo 1 — Autodiagnóstico
Antes de encerrar, o agente DEVE se perguntar:
```
1. Resolvi algum bug não trivial?
2. Tomei alguma decisão técnica que outro agente precisaria saber?
3. Descobri uma regra de negócio nova?
4. Criei/alterei uma funcionalidade importante?
5. Defini um padrão que deve ser seguido?
6. Encontrei um workaround que outros precisarão?
```
Se **qualquer resposta for SIM** → executar Passo 2.
### Passo 2 — Buscar antes de criar
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/busca" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{"termo": "PALAVRAS_CHAVE_DO_TEMA"}'
```
- Se já existe memória sobre o tema → **editar** (não duplicar)
- Se não existe → **criar**
### Passo 3 — Registrar com qualidade
Campos obrigatórios: `titulo`, `conteudo`, `resumo`, `categoria`, `criado_por`, `tags`
**Regras de qualidade:**
| Campo | Regra |
|-------|-------|
| `titulo` | Pesquisável, com nome do módulo/contexto. Ex: "QUIPO — Regra de timeout em uploads" |
| `resumo` | 10-500 chars, síntese direta sem floreios |
| `conteudo` | Markdown estruturado com ### seções. Incluir: contexto, decisão, exemplo, impacto |
| `tags` | Mínimo 3 tags relevantes. Incluir nome do módulo/projeto |
| `criado_por` | Handle do agente com @ (ex: `@ag-back`) |
| `contexto` | Nome do projeto/módulo (ex: `QUIPO-PORTAL3`) |
### Passo 4 — Vincular memórias relacionadas
Após criar, verificar se existem memórias que devem ser vinculadas:
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/vinculos/criar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{
"codigo_memoria_a": CODIGO_NOVA,
"codigo_memoria_b": CODIGO_EXISTENTE,
"relacao": "{mem:CODIGO_NOVA} complementa/expande/resolve {mem:CODIGO_EXISTENTE}",
"criado_por": "@HANDLE"
}'
```
## Regra de Ouro
> Se a informação seria útil para **outro agente** ou para a **mesma tarefa daqui 1 semana** → **registre na memória**.
## Anti-padrões (PROIBIDO)
- ❌ Encerrar sessão com conhecimento não registrado
- ❌ Registrar sem `resumo` ou sem `tags`
- ❌ Criar memória sem buscar duplicatas antes
- ❌ Usar `criado_por` sem o prefixo `@`
- ❌ Registrar código-fonte (já está no repositório)
- ❌ Registrar dados sensíveis (senhas, tokens, dados pessoais)
## Impacto
Sem esta regra, **a auditoria de 2026-07-06 revelou que 6+ conversas significativas (tradução i18n, autenticação, build timestamps) não geraram nenhuma memória**. Esta regra previne perdas futuras.
## Referências
- Skill: `global/skills/memoria-persistente/SKILL`
- Rule: `global/rules/usar-memoria-persistente`
- Workflow: `global/workflows/aprimorar-IA`

View file

@ -98,5 +98,4 @@ Garante consistência visual entre todos os frontends e facilita troca de tema
## Referências
- Memória: https://memoria-ia.idz.one (código: 63)
- Rule: `estilos-design-system`

View file

@ -62,15 +62,15 @@ Cada agente aplica o protocolo mínimo acima com foco no seu domínio:
| Agente | Diagnóstico Específico |
|--------|----------------------|
| `@ag-back` | Verificar rotas, queries, schemas Zod, filas, logs de erro |
| `@ag-front` | Verificar componente, composable, props/emits, estados de UI, console do navegador |
| `@ag-refatorar` | Executar skill `diagnosticar-code-smells` antes de qualquer refatoração |
| `@ag-testes` | Mapear cobertura existente, identificar cenários ausentes |
| `@ag-deploy` | Verificar logs, healthchecks, variáveis de ambiente, estado dos containers |
| `@ag-arquiteto` | Verificar fronteiras de módulo, dependências, contratos de API |
| `@ag-ux` | Verificar fluxo de uso completo, estados de interface, mensagens ao usuário |
| `@ag-documentacao` | Verificar JSDoc existente, `.regras-negocio.md`, dessincronia código/docs |
| `@ag-agente` | Executar `auditar-agentes.sh`, verificar contradições entre personas |
| `@back` | Verificar rotas, queries, schemas Zod, filas, logs de erro |
| `@front` | Verificar componente, composable, props/emits, estados de UI, console do navegador |
| `@refatorar` | Executar skill `diagnosticar-code-smells` antes de qualquer refatoração |
| `@testes` | Mapear cobertura existente, identificar cenários ausentes |
| `@deploy` | Verificar logs, healthchecks, variáveis de ambiente, estado dos containers |
| `@arquiteto` | Verificar fronteiras de módulo, dependências, contratos de API |
| `@ux` | Verificar fluxo de uso completo, estados de interface, mensagens ao usuário |
| `@documentacao` | Verificar JSDoc existente, `.regras-negocio.md`, dessincronia código/docs |
| `@agente` | Auditar personas, verificar contradições entre personas |
## Exceções
@ -117,5 +117,5 @@ Sem esta regra:
- Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`
- Skill: `global/skills/diagnosticar-erros-build/SKILL`
- Skill: `agents/ag-refatorar/skills/diagnosticar-code-smells/SKILL`
- Skill: `agents/refatorar/skills/diagnosticar-code-smells/SKILL`
- Rule: `global/rules/autonomia-agente`

View file

@ -202,4 +202,3 @@ import { eBetha } from "p-ambiente";
- Rule: `css-global-betha` (variáveis --bth-*)
- Rule: `theme-provider-mui-betha` (arquitetura ThemeProvider)
- Rule: `modal-dialog-padrao-betha` (estrutura de modais)
- Memórias: https://memoria-ia.idz.one (códigos: 59, 62, 65)

View file

@ -24,9 +24,9 @@ Todo evento relevante (erro, aviso, conclusão de processo, falha de validação
| Camada | Responsável | Como |
|--------|-------------|------|
| **Frontend** | `@ag-front` + `@ag-ux` | Toast, banner, mensagem inline, estado de erro visível |
| **Backend** | `@ag-back` | `console.error()` / `console.warn()` com contexto suficiente |
| **Log de fila** | `@ag-back` + `@ag-deploy` | Registrar falha no job com payload + stack trace |
| **Frontend** | `@front` + `@ux` | Toast, banner, mensagem inline, estado de erro visível |
| **Backend** | `@back` | `console.error()` / `console.warn()` com contexto suficiente |
| **Log de fila** | `@back` + `@deploy` | Registrar falha no job com payload + stack trace |
---
@ -89,7 +89,7 @@ processor.on('failed', (job, erro) => {
## Camadas e responsabilidades detalhadas
### Frontend (`@ag-front` + `@ag-ux`)
### Frontend (`@front` + `@ux`)
- Todo `catch` deve resultar em feedback visível ao usuário
- Nunca usar `catch (_) {}` sem ao menos logar no console do browser
@ -97,7 +97,7 @@ processor.on('failed', (job, erro) => {
- Estados de carregamento e erro devem ser explícitos na UI (não apenas esconder o spinner)
- Usar o padrão: `loading → sucesso | erro`, nunca ficar preso em "loading" silencioso
### Backend (`@ag-back`)
### Backend (`@back`)
- Toda exceção capturada deve ser logada com contexto: qual operação, qual entidade, qual erro
- `console.error()` para erros operacionais; `console.warn()` para situações de atenção
@ -105,7 +105,7 @@ processor.on('failed', (job, erro) => {
- O log deve incluir o suficiente para reproduzir o problema: IDs, parâmetros relevantes
- Erros internos não devem vazar para o cliente — traduzir para `ErroOperacional` ou equivalente
### Fila (`@ag-back` + `@ag-deploy`)
### Fila (`@back` + `@deploy`)
- Se o sistema usa BullMQ, Redis ou similar: configurar handler de `failed` e `error`
- Jobs que falham devem ser registrados com: jobId, nome, tentativas, payload relevante, erro
@ -125,6 +125,6 @@ processor.on('failed', (job, erro) => {
## Referências
- Rule: `global/rules/mensagens-usuario` (vocabulário para mensagens ao usuário)
- Persona: `agents/ag-front/persona` (estados de UI)
- Persona: `agents/ag-back/persona` (tratamento de erros)
- Persona: `agents/ag-ux/persona` (feedback imediato como princípio)
- Persona: `agents/front/persona` (estados de UI)
- Persona: `agents/back/persona` (tratamento de erros)
- Persona: `agents/ux/persona` (feedback imediato como princípio)

View file

@ -101,6 +101,5 @@ Evita modais com aparências inconsistentes entre telas e garante conformidade c
## Referências
- Memória: https://memoria-ia.idz.one (código: 61)
- Rule: `theme-provider-mui-betha`
- Rule: `estilos-design-system`

View file

@ -86,6 +86,5 @@ Evita divergências visuais entre telas e garante que a troca de marca (Betha
## Referências
- Memória: https://memoria-ia.idz.one (código: 60)
- Rule: `estilos-design-system`
- Rule: `css-global-betha`

View file

@ -1,102 +0,0 @@
---
type: rule
name: usar-memoria-persistente
description: Todo agente deve consultar e registrar conhecimento persistente na Memória Azteca sempre que relevante
scope: global
trigger: always_on
priority: alta
updatedAt: "2026-06-23"
---
# Regra: Usar Memória Persistente
## Contexto
O ecossistema Azteca possui uma memória centralizada em `https://memoria-ia.idz.one` acessível por todos os agentes via API REST. Informações descobertas durante o trabalho se perdem entre sessões se não forem registradas.
## Quando consultar a memória
O agente **deve** buscar na memória antes de:
- Tomar decisões arquiteturais (verificar se já existe ADR sobre o tema)
- Resolver um bug (verificar se já existe solução documentada)
- Implementar um padrão novo (verificar se já existe padrão definido)
- Trabalhar em módulo que não conhece (buscar contexto do módulo)
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/busca" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{"termo": "PALAVRA_CHAVE"}' | jq .
```
## Quando registrar na memória
O agente **deve** salvar na memória quando:
- Toma uma decisão arquitetural significativa
- Descobre e resolve um bug não trivial
- Define ou altera um padrão técnico
- Descobre uma regra de negócio nova
- Encontra um workaround para problema de infraestrutura
- Qualquer conhecimento que beneficiaria sessões futuras
## Como registrar
Usar a skill `global/skills/memoria-persistente/SKILL` para o protocolo completo.
**Mínimo obrigatório:**
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{
"titulo": "Descrição clara e pesquisável",
"conteudo": "Detalhes completos com contexto",
"resumo": "Síntese curta e pesquisável (10-500 chars)",
"categoria": "CATEGORIA",
"criado_por": "@HANDLE_DO_AGENTE"
}'
```
> **`resumo` é obrigatório.** Alimenta a busca vetorial com peso B. Sem ele a API retornará erro 400.
## Autonomia (obrigatório)
> **A memória é uma operação autônoma.** Consultar e registrar na memória **NÃO requer permissão do operador**. O agente deve executar as chamadas à API sempre que os critérios de consulta ou registro forem atendidos, sem perguntar.
Nunca diga ao operador "vou consultar a memória, tudo bem?" ou "deseja que eu registre?". **Faça.**
## Regra de ouro
> Se a informação seria útil para outro agente ou para a mesma tarefa daqui 1 semana — **salve na memória**.
## Vínculos entre memórias
Ao criar ou editar memórias, verificar se existem memórias relacionadas na base. Se sim, criar vínculos usando a rota `/api/vinculos/criar` com a sintaxe `{mem:ID}` no campo `relacao`.
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/vinculos/criar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{
"codigo_memoria_a": 1,
"codigo_memoria_b": 5,
"relacao": "{mem:1} define o padrão usado por {mem:5}",
"criado_por": "@HANDLE_DO_AGENTE"
}'
```
## Campo contexto
Use o campo opcional `contexto` para categorizar memórias por projeto, módulo ou cliente (ex: `Módulo Licenças`, `Projeto Edital Resíduos`, `Cliente XPTO`). Facilita filtros e buscas por escopo.
## Impacto
Sem esta regra, cada sessão começa do zero. Com ela, o ecossistema acumula conhecimento e fica mais inteligente a cada interação.
## Referências
- Skill: `global/skills/memoria-persistente/SKILL`
- API: `https://memoria-ia.idz.one`

View file

@ -149,57 +149,17 @@ produto.nome = produto.nome.trim()
produto.codigo = produto.codigo?.toUpperCase()
```
### 8. Composição de schemas em vez de duplicação
### 8. Composição e Enums Zod
```typescript
// ✅ CORRETO — composição
const zEndereco = z.object({
rua: z.string(),
cidade: z.string(),
uf: z.string().length(2),
})
// ✅ Composição de schemas via extend/partial
const zEndereco = z.object({ rua: z.string(), cidade: z.string() })
const zEmpresaCriar = z.object({ nome: z.string(), endereco: zEndereco })
const zEmpresaEditar = zEmpresaCriar.partial()
const zEmpresaCriar = z.object({
nome: z.string(),
endereco: zEndereco,
})
const zEmpresaEditar = zEmpresaCriar.partial() // todos opcionais
const zEmpresaResposta = zEmpresaCriar.extend({
codigo: z.string().uuid(),
criadoEm: z.string().datetime(),
})
// ❌ ERRADO — copiar campos entre schemas
const zEmpresaEditar = z.object({
nome: z.string().optional(), // duplicou!
endereco: z.object({ // duplicou!
rua: z.string().optional(),
cidade: z.string().optional(),
}),
})
```
### 9. Enums Zod para valores de domínio
```typescript
// ✅ CORRETO — enum Zod quando os valores vêm de dados externos
// ✅ Enum Zod para valores de domínio
export const zStatusLicenca = z.enum(["ativa", "vencida", "suspensa", "cancelada"])
export type tipoStatusLicenca = z.infer<typeof zStatusLicenca>
// Usar em outros schemas
const zLicencaCriar = z.object({
status: zStatusLicenca,
// ...
})
// ✅ TAMBÉM CORRETO — TypeScript enum quando já existe no projeto
// e o schema referencia o enum
import { StatusLicenca } from "./enums"
const zLicencaCriar = z.object({
status: z.nativeEnum(StatusLicenca),
})
```
### 10. Bibliotecas proibidas para validação
@ -233,57 +193,20 @@ app.post("/usuarios", async (req, res) => {
})
```
### Webhook com fila
### Variáveis de ambiente e Frontend
```typescript
// ✅ Correto — valida antes de enfileirar
const zPayloadWebhook = z.object({
tabela: z.enum(["empreendedores", "empreendimentos", "usuarios"]),
dados: z.array(z.unknown()).min(1),
})
app.post("/webhook/:tabela", async (req, res) => {
const resultado = zPayloadWebhook.safeParse({
tabela: req.params.tabela,
dados: req.body,
})
if (!resultado.success) {
return res.status(400).json({ erro: "Payload inválido" })
}
await fila.add("sync", resultado.data)
return res.json({ ok: true })
})
```
### Variáveis de ambiente
```typescript
// ✅ Correto — validar no boot da aplicação
const zAmbiente = z.object({
// ✅ Validar env no boot da aplicação
export const ambiente = () => z.object({
DATABASE_URL: z.string().url(),
REDIS_HOST: z.string().default("localhost"),
REDIS_PORT: z.coerce.number().default(6379),
BASE_URL: z.string().url(),
SESSAO_BACK: z.string().uuid(),
NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
})
export const ambiente = () => zAmbiente.parse(process.env)
```
### Frontend (formulário Vue)
```typescript
// ✅ Correto — schema compartilhado validando antes de enviar
import { zUsuarioCriar } from "projeto-comuns/tabelas/usuarios"
}).parse(process.env)
// ✅ Frontend: usar schema compartilhado antes de enviar
const salvar = async () => {
const resultado = zUsuarioCriar.safeParse(formulario.value)
if (!resultado.success) {
erros.value = resultado.error.flatten().fieldErrors
return
}
await api.post("/usuarios", resultado.data)
const res = zUsuarioCriar.safeParse(formulario.value)
if (!res.success) return (erros.value = res.error.flatten().fieldErrors)
await api.post("/usuarios", res.data)
}
```