publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

refatoração dos agents

Browse source
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
Download patch file Download diff file Expand all files Collapse all files

127
global/rules/coleta-automatica-memorias
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`

1
global/rules/css-global-betha
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`

20
global/rules/diagnostico-antes-correcao
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`

1
global/rules/estilos-design-system
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)

18
global/rules/feedback-visivel
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)

1
global/rules/modal-dialog-padrao-betha
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`

1
global/rules/theme-provider-mui-betha
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`

102
global/rules/usar-memoria-persistente
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`

105
global/rules/zod-validacao-padrao
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)
}
```

8
global/skills/diagnosticar-antes-corrigir/SKILL
View file

@ -54,11 +54,7 @@ npx tsc --noEmit -p <caminho>/tsconfig.json 2>&1 | head -30
### 2.3. Consultar memória (obrigatório)
```sh
# Buscar problemas semelhantes já resolvidos
curl -s -X POST "https://memoria-ia.idz.one/api/busca/rapida" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{"termo": "PALAVRAS_CHAVE_DO_PROBLEMA"}' | jq '.items[] | {codigo, titulo, resumo}'
grep -rn "PALAVRAS_CHAVE_DO_PROBLEMA" .
```
### 2.4. Verificar regras de negócio documentadas
@ -188,5 +184,5 @@ A etapa de diagnóstico **nunca é eliminada** — apenas simplificada proporcio
- Rule: `global/rules/diagnostico-antes-correcao`
- 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`

8
global/skills/documentar-dominio-modulo/SKILL
View file

@ -33,7 +33,7 @@ Determinar qual área da ciência/gestão o módulo aborda:
## PASSO 2 — Criar o Arquivo de Domínio
Criar em `.agent/memoria/dominio-<modulo>.md`:
Criar documento no arquivo `.regras-negocio.md` do módulo:
```markdown
# Domínio: <Nome do Módulo>
@ -116,7 +116,7 @@ Após documentar o domínio:
## Checklist Final
- [ ] Arquivo `dominio-<modulo>.md` criado em `.agent/memoria/`?
- [ ] Arquivo `.regras-negocio.md` do módulo criado e validado?
- [ ] Glossário com pelo menos os 10 termos centrais do módulo?
- [ ] Entidades principais listadas com descrição?
- [ ] Legislação base documentada com formato de citação?
@ -127,5 +127,5 @@ Após documentar o domínio:
- Rule: `global/rules/mensagens-usuario`
- Rule: `global/rules/regras-negocio-md`
- Workflow: `agents/ag-comercial/workflows/comercial`
- Workflow: `agents/ag-front/workflows/adicionar-ajuda`
- Workflow: `agents/comercial/workflows/comercial`
- Workflow: `agents/front/workflows/adicionar-ajuda`

457
global/skills/memoria-persistente/SKILL
View file

@ -1,457 +0,0 @@
---
name: memoria-persistente
scope: global
description: >
Ferramenta para todos os agentes registrarem e consultarem conhecimento persistente
no serviço Memória Azteca (https://memoria-ia.idz.one). Usar sempre que houver
informação que deve sobreviver entre sessões — decisões, soluções, padrões, bugs etc.
---
# Skill: Memória Persistente
Use esta skill sempre que precisar **registrar** ou **consultar** conhecimento que deve persistir entre conversas. Toda informação que seria perdida ao encerrar a sessão e que tem valor futuro deve ser salva na memória.
> **Autonomia:** Consultar e registrar na memória **NÃO requer permissão do operador**. Execute as chamadas sempre que os critérios forem atendidos, sem perguntar.
---
## Configuração fixa
```
URL_BASE=https://memoria-ia.idz.one
CHAVE=banana
```
Todos os requests usam:
- Método: `POST`
- Header: `Content-Type: application/json`
- Header de autenticação: `CHAVE: banana`
---
## QUANDO USAR
### Salvar na memória ✅
- Decisões arquiteturais (ADRs)
- Soluções para problemas encontrados
- Padrões técnicos definidos durante o trabalho
- Bugs conhecidos e seus workarounds
- Regras de negócio descobertas
- Informações sobre clientes e integrações
- Configurações de infraestrutura
- Qualquer conhecimento que outro agente ou sessão futura precisará
### NÃO salvar ❌
- Logs temporários ou outputs de debug
- Código-fonte (que já está no repositório)
- Dados sensíveis (senhas, tokens reais, dados pessoais)
---
## PASSO 1 — Buscar antes de criar
Antes de criar uma memória, **sempre** verificar se já existe algo relacionado:
### Busca full-text (recomendado)
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/busca" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{"termo": "validação zod"}'
```
### Busca rápida (títulos e resumos)
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/busca/rapida" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{"termo": "deploy docker"}'
```
### Listar com filtros
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/listar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{"categoria": "solucao-problemas", "contexto": "Módulo Licenças", "limite": 10}'
```
### Listar por tags
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/listar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{"tags": ["api", "resposta"], "limite": 10}'
```
### Buscar por código específico
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/buscar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{"codigo": "abc123"}'
```
---
## PASSO 2 — Criar memória
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{
"titulo": "Título claro e descritivo",
"conteudo": "Descrição detalhada do conhecimento...",
"resumo": "Resumo curto e pesquisável da memória (10-500 chars)",
"categoria": "modulos",
"tipo": "referencia",
"tags": ["tag1", "tag2"],
"contexto": "Módulo Licenças",
"criado_por": "@ag-back"
}'
```
### Campos obrigatórios
| Campo | Descrição |
|-------|-----------|
| `titulo` | Nome claro e pesquisável da memória (min 3, max 300) |
| `conteudo` | Corpo completo do conhecimento em Markdown (min 10) |
| `resumo` | Resumo curto e pesquisável (min 10, max 500) — usado na busca vetorial com peso B |
| `categoria` | Slug da categoria (ver tabela abaixo) |
| `criado_por` | Handle do agente que está criando (ex: `@ag-back`) |
### Campos opcionais
| Campo | Descrição |
|-------|-----------|
| `tipo` | Tipo da memória: `nota`, `adr`, `solucao-problemas`, `referencia`, `procedimento` (default: `nota`) |
| `tags` | Array de strings para facilitar busca e filtragem |
| `contexto` | Contexto da memória (ex: `Módulo Licenças`, `Projeto Edital Resíduos`, `Cliente XPTO`) |
### Categorias disponíveis
| Slug | Nome | Quando usar |
|------|------|-------------|
| `modulos` | Módulos | Funcionalidades e módulos do ecossistema |
| `tecnologias` | Tecnologias | Padrões técnicos, libs, frameworks |
| `regras-negocio` | Regras de Negócio | Regras de negócio do domínio ambiental |
| `infraestrutura` | Infraestrutura | Deploy, servidores, CI/CD |
| `decisoes` | Decisões Arquiteturais | ADRs e decisões de design |
| `clientes` | Clientes | Informações sobre clientes e integrações |
| `solucao-problemas` | Solução de Problemas | Problemas conhecidos e soluções |
| `corporativo` | Corporativo | Informações corporativas, estratégia e governança |
---
## PASSO 3 — Editar memória existente
Quando a informação já existe mas precisa ser atualizada:
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/editar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{
"codigo": "CODIGO_DA_MEMORIA",
"titulo": "Título atualizado",
"conteudo": "Conteúdo revisado...",
"tags": ["tag-nova"]
}'
```
> Enviar apenas os campos que precisam mudar, além do `codigo` (obrigatório).
---
## PASSO 4 — Excluir memória (lógico)
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/excluir" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{"codigo": "CODIGO_DA_MEMORIA"}'
```
> ⚠️ Exclusão lógica — a memória é marcada como inativa, não é removida.
---
## PASSO 5 — Consultar metadados
### Listar categorias
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/categorias/listar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{}'
```
### Listar tags
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/tags/listar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{}'
```
### Tags mais usadas
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/tags/populares" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{}'
```
---
## Referência rápida de rotas
| Rota | Finalidade |
|------|-----------|
| `GET /api/status` | Checar healthcheck da API da memória |
| `POST /api/busca` | Busca full-text em todas as memórias |
| `POST /api/busca/rapida` | Busca simplificada (títulos e resumos) |
| `POST /api/memorias/criar` | Criar nova memória |
| `POST /api/memorias/editar` | Editar memória existente |
| `POST /api/memorias/buscar` | Buscar por código |
| `POST /api/memorias/listar` | Listar com filtros e paginação |
| `POST /api/memorias/excluir` | Exclusão lógica |
| `POST /api/memorias/mesclar` | Fundir duas memórias e inativar a origem |
| `POST /api/memorias/sinalizar` | Marcar memória como obsoleta ou que precisa de revisão |
| `POST /api/memorias/batch` | Operações em lote (criar e editar múltiplos registros) |
| `POST /api/memorias/historico` | Ver histórico de alterações de uma memória |
| `POST /api/vinculos/criar` | Criar vínculo entre memórias |
| `POST /api/vinculos/listar` | Listar vínculos de uma memória |
| `POST /api/vinculos/excluir` | Excluir vínculo |
| `POST /api/categorias/listar` | Listar categorias disponíveis |
| `POST /api/tags/listar` | Listar todas as tags |
| `POST /api/tags/populares` | Tags mais usadas |
| `POST /api/contextos/listar` | Listar todos os contextos existentes |
---
## PASSO 6 — Vínculos entre memórias
Vínculos permitem relacionar memórias entre si usando a sintaxe `{mem:ID}` no campo `relacao`.
### Regras de vínculo
- `codigo_memoria_a` e `codigo_memoria_b` **não podem ser iguais**
- O campo `relacao` **deve** conter `{mem:codigo_memoria_a}` e `{mem:codigo_memoria_b}`
- A relação é bidirecional — aparece ao consultar qualquer uma das memórias vinculadas
### Criar vínculo
```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} é sócio de {mem:5}",
"criado_por": "@ag-arquiteto"
}'
```
### Exemplos de relação
```
{mem:1} é sócio de {mem:5}
{mem:3} e {mem:7} são concorrentes
{mem:2} depende de {mem:4}
{mem:10} substituiu {mem:6}
```
### Listar vínculos de uma memória
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/vinculos/listar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{"codigo_memoria": 1}'
```
### Excluir vínculo
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/vinculos/excluir" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{"codigo": 42}'
```
### Quando criar vínculos
- Ao registrar decisões que impactam outras memórias existentes
- Ao descobrir relações entre pessoas, módulos ou conceitos já documentados
- Ao resolver um problema cuja causa está documentada em outra memória
---
## PASSO 7 — Operações de Manutenção e Qualidade
Para garantir a qualidade da rede de conhecimento a longo prazo:
### Sinalizar como obsoleta ou em revisão
Se uma memória não faz mais sentido ou o código mudou, sinalize-a (não exclua, a menos que seja lixo):
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/sinalizar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{
"codigo": 42,
"obsoleto": true,
"motivo": "Este padrão foi refatorado e substituído pelo novo helper",
"sinalizado_por": "@ag-back"
}'
```
### Mesclar memórias duplicadas
Se houver duas memórias sobre o mesmo assunto:
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/mesclar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{
"codigo_origem": 10,
"codigo_destino": 5,
"acao_origem": "sinalizar",
"realizado_por": "@ag-memoria"
}'
```
*(As tags e vínculos da origem irão para o destino. A origem será sinalizada ou excluída de acordo com `acao_origem`)*
### Operações em Lote (Batch)
Se precisar importar ou registrar múltiplas memórias rapidamente:
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/batch" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{
"criar": [
{ "titulo": "Regra 1", "conteudo": "...", "resumo": "...", "categoria": "regras-negocio", "criado_por": "@ag-memoria" }
],
"editar": [
{ "codigo": 8, "tags": ["nova-tag"], "atualizado_por": "@ag-memoria" }
]
}'
```
---
## Boas práticas
1. **Buscar antes de criar** — evitar duplicatas na base
2. **Títulos pesquisáveis** — usar palavras-chave que outro agente buscaria
3. **Resumo obrigatório** — sempre preencher `resumo` com uma síntese curta e pesquisável (10-500 chars); o resumo alimenta a busca vetorial com peso B
4. **Identificar o autor** — sempre preencher `criado_por` com o handle do agente
5. **Tags relevantes** — facilitar buscas futuras por contexto e filtragem por tags
6. **Conteúdo rico** — incluir contexto, decisão, motivo e exemplos quando possível
7. **Atualizar, não duplicar** — se a memória já existe, usar editar em vez de criar nova
8. **Vincular memórias relacionadas** — ao criar ou editar, verificar se existem memórias que devem ser vinculadas com `{mem:ID}`
9. **Contexto descritivo** — usar o campo `contexto` para categorizar por projeto, módulo ou cliente (ex: `Módulo Licenças`, `Cliente XPTO`)
10. **Pipe com jq** — para leitura limpa, adicionar `| jq .` ao final do curl
---
## Exemplos por agente
### @ag-back registrando uma decisão
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{
"titulo": "API de licenças usa paginação offset com limite 50",
"conteudo": "Endpoint POST /licencas/listar retorna no máximo 50 itens por página. Paginação via campos pagina e limite no body. Resposta inclui total para calcular páginas no front.",
"resumo": "Paginação offset com limite 50 no endpoint de licenças",
"categoria": "decisoes",
"tipo": "adr",
"tags": ["licencas", "paginacao", "api"],
"contexto": "Módulo Licenças",
"criado_por": "@ag-back"
}'
```
### @ag-testes registrando um bug conhecido
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{
"titulo": "Bug: timeout no upload de arquivos maiores que 10MB",
"conteudo": "O proxy nginx corta a conexão após 60s. Uploads grandes falham silenciosamente. Workaround: aumentar proxy_read_timeout para 300s no nginx.conf do servidor de produção.",
"resumo": "Timeout no upload acima de 10MB por limite do nginx. Solução: proxy_read_timeout 300s",
"categoria": "solucao-problemas",
"tipo": "solucao-problemas",
"tags": ["upload", "nginx", "timeout", "bug"],
"contexto": "Módulo Arquivos",
"criado_por": "@ag-testes"
}'
```
### @ag-front consultando padrões
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/busca" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{"termo": "composable padrão vue"}' | jq .
```
### @ag-arquiteto criando vínculo entre memórias
```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": 3,
"codigo_memoria_b": 7,
"relacao": "{mem:3} define o padrão de resposta usado por {mem:7}",
"criado_por": "@ag-arquiteto"
}'
```
---
## Checklist
- [ ] Busquei na memória antes de criar? (evitar duplicatas)
- [ ] O título é claro e pesquisável?
- [ ] O resumo está preenchido e é descritivo? (obrigatório, 10-500 chars)
- [ ] A categoria está correta?
- [ ] Preenchi `criado_por` com meu handle?
- [ ] O conteúdo tem contexto suficiente para ser útil no futuro?
- [ ] Adicionei tags relevantes?
- [ ] Existem memórias relacionadas que devem ser vinculadas?
---
## Referências
- API: `https://memoria-ia.idz.one`
- Painel Web: `https://memoria-ia.idz.one/painel`
- Rule: `global/rules/autonomia-agente`
- Skill: `global/skills/orquestrar-agentes/SKILL`

106
global/skills/orquestrar-agentes/SKILL
View file

@ -18,14 +18,14 @@ Antes de qualquer implementação, mapear quais agentes são necessários:
| Tarefa | Agente responsável |
|--------|-------------------|
| Definir arquitetura, contratos de API, schemas | `@ag-arquiteto` |
| Implementar backend (rotas, serviços, banco) | `@ag-back` |
| Implementar frontend (telas, componentes, fluxos) | `@ag-front` |
| Garantir qualidade e criar testes | `@ag-testes` |
| Configurar infraestrutura e deploy | `@ag-deploy` |
| Criar/atualizar documentação | `@ag-documentacao` |
| Revisar e melhorar UX | `@ag-ux` |
| Criar materiais de venda e marketing | `@ag-comercial` |
| Definir arquitetura, contratos de API, schemas | `@arquiteto` |
| Implementar backend (rotas, serviços, banco) | `@back` |
| Implementar frontend (telas, componentes, fluxos) | `@front` |
| Garantir qualidade e criar testes | `@testes` |
| Configurar infraestrutura e deploy | `@deploy` |
| Criar/atualizar documentação | `@documentacao` |
| Revisar e melhorar UX | `@ux` |
| Criar materiais de venda e marketing | `@comercial` |
---
@ -34,20 +34,20 @@ Antes de qualquer implementação, mapear quais agentes são necessários:
Toda tarefa complexa segue uma ordem de precedência:
```
1. @ag-arquiteto → define e especifica
2. @ag-back → implementa backend + schemas *-comuns
3. @ag-front → implementa frontend (consome *-comuns)
4. @ag-ux → revisa experiência (paralelo com front)
5. @ag-testes → valida qualidade
6. @ag-deploy → empacota e publica
7. @ag-documentacao → documenta (pode ser paralelo)
8. @ag-comercial → cria materiais (após documentação)
1. @arquiteto → define e especifica
2. @back → implementa backend + schemas *-comuns
3. @front → implementa frontend (consome *-comuns)
4. @ux → revisa experiência (paralelo com front)
5. @testes → valida qualidade
6. @deploy → empacota e publica
7. @documentacao → documenta (pode ser paralelo)
8. @comercial → cria materiais (após documentação)
```
Agentes podem trabalhar em paralelo quando não há dependência direta:
- `@ag-ux` e `@ag-front` podem colaborar em paralelo
- `@ag-documentacao` pode trabalhar em paralelo com `@ag-testes`
- `@ag-comercial` é sempre o último da cadeia
- `@ux` e `@front` podem colaborar em paralelo
- `@documentacao` pode trabalhar em paralelo com `@testes`
- `@comercial` é sempre o último da cadeia
---
@ -56,8 +56,8 @@ Agentes podem trabalhar em paralelo quando não há dependência direta:
Quando um agente precisa comunicar resultado ou delegar tarefa para outro, usar o formato:
```markdown
**De:** @ag-arquiteto
**Para:** @ag-back
**De:** @arquiteto
**Para:** @back
**Tipo:** especificação | resultado | bloqueio | revisão
## Contexto
@ -80,23 +80,23 @@ Quando um agente precisa comunicar resultado ou delegar tarefa para outro, usar
### Permitido ✅
```
@ag-arquiteto → pode delegar para qualquer agente
@ag-back → pode enviar schemas e endpoints para @ag-front (via *-comuns)
@ag-front → pode solicitar revisão de @ag-ux
@ag-ux → pode propor melhorias para @ag-front
@ag-testes → pode reportar bugs para @ag-back e @ag-front
@ag-documentacao → pode documentar artefatos de qualquer agente
@ag-deploy → recebe builds de @ag-back e @ag-front
@arquiteto → pode delegar para qualquer agente
@back → pode enviar schemas e endpoints para @front (via *-comuns)
@front → pode solicitar revisão de @ux
@ux → pode propor melhorias para @front
@testes → pode reportar bugs para @back e @front
@documentacao → pode documentar artefatos de qualquer agente
@deploy → recebe builds de @back e @front
```
### Proibido ❌
```
@ag-front ✗ não importa código de @ag-back diretamente
@ag-back ✗ não cria componentes Vue ou lógica de interface
@ag-comercial ✗ não promete features que @ag-arquiteto não aprovou
@ag-testes ✗ não modifica código de produção
@ag-ux ✗ não implementa código Vue — apenas orienta @ag-front
@front ✗ não importa código de @back diretamente
@back ✗ não cria componentes Vue ou lógica de interface
@comercial ✗ não promete features que @arquiteto não aprovou
@testes ✗ não modifica código de produção
@ux ✗ não implementa código Vue — apenas orienta @front
```
---
@ -105,10 +105,10 @@ Quando um agente precisa comunicar resultado ou delegar tarefa para outro, usar
Quando dois agentes têm visões diferentes:
1. **Técnico vs. UX:** `@ag-arquiteto` arbitra, priorizando viabilidade técnica com mínimo impacto na UX
2. **Back vs. Front (sobre contrato de API):** `@ag-arquiteto` define o contrato no schema `*-comuns`
3. **Documentação vs. Implementação:** O código é a verdade — `@ag-documentacao` atualiza para refletir o código
4. **Comercial vs. Produto:** `@ag-arquiteto` define o que existe; `@ag-comercial` comunica apenas o real
1. **Técnico vs. UX:** `@arquiteto` arbitra, priorizando viabilidade técnica com mínimo impacto na UX
2. **Back vs. Front (sobre contrato de API):** `@arquiteto` define o contrato no schema `*-comuns`
3. **Documentação vs. Implementação:** O código é a verdade — `@documentacao` atualiza para refletir o código
4. **Comercial vs. Produto:** `@arquiteto` define o que existe; `@comercial` comunica apenas o real
---
@ -117,45 +117,45 @@ Quando dois agentes têm visões diferentes:
### Fluxo: Nova feature completa
```
@ag-arquiteto → especifica schema e contrato de API
@arquiteto → especifica schema e contrato de API
↓
@ag-back → implementa endpoint + atualiza *-comuns
@back → implementa endpoint + atualiza *-comuns
↓
@ag-front → implementa tela consumindo *-comuns
@front → implementa tela consumindo *-comuns
↓ (paralelo)
@ag-ux → revisa UX da tela
@ux → revisa UX da tela
↓
@ag-testes → valida back + front
@testes → valida back + front
↓
@ag-deploy → publica
@deploy → publica
↓ (paralelo)
@ag-documentacao → documenta
@documentacao → documenta
↓
@ag-comercial → cria material de divulgação
@comercial → cria material de divulgação
```
### Fluxo: Correção de bug crítico
```
@ag-testes → identifica e documenta bug
@testes → identifica e documenta bug
↓
@ag-back ou @ag-front → corrige
@back ou @front → corrige
↓
@ag-testes → valida correção
@testes → valida correção
↓
@ag-deploy → hotfix
@deploy → hotfix
```
### Fluxo: Melhoria de UX
```
@ag-ux → identifica problema e propõe melhoria
@ux → identifica problema e propõe melhoria
↓
@ag-arquiteto → avalia impacto técnico
@arquiteto → avalia impacto técnico
↓
@ag-front → implementa
@front → implementa
↓
@ag-ux → valida
@ux → valida
```
---

97
global/workflows/aprimorar-IA → global/workflows/aprimora-ia
View file

@ -1,16 +1,16 @@
---
type: workflow
name: aprimorar-IA
description: Consolidar aprendizados da conversa atual e evoluir continuamente as regras, skills e fluxos da aplicação
name: aprimora-ia
description: Otimizar o ecossistema da IA conforme identificado durante a conversa e registrar eventos na memória
scope: global
updatedAt: "2026-06-01"
updatedAt: "2026-08-10"
---
# Workflow: Aprimorar Conhecimento da Aplicação
# Workflow: /aprimora-ia (Aprimoramento Contínuo e Registro de Memória)
## 🎯 Objetivo
Garantir que **toda decisão tomada** seja imediatamente incorporada ao conhecimento estruturado da aplicação, mantendo o sistema de rules, workflows e skills **coerente, atualizado, não redundante e sem contradições**.
Analisar os aprendizados, alterações e decisões tomadas ao longo da conversa, aplicando as devidas otimizações diretamente nos artefatos do ecossistema (Rules, Workflows, Skills e Personas).
Este workflow é **obrigatório** e deve ser executado sempre que houver qualquer definição nova.
@ -25,7 +25,8 @@ O conhecimento do agente está organizado em **três tipos de artefatos**, cada
| **Rules** | `.agent/base/global/rules/` | `.agent/local/rules/` | Restrições e convenções que o agente **deve respeitar sempre** |
| **Workflows** | `.agent/base/global/workflows/` | `.agent/local/workflows/` | Processos sequenciais com passos numerados para tarefas bem definidas |
| **Skills** | `.agent/base/global/skills/` | `.agent/local/skills/` | Guias operacionais completos e reutilizáveis para tarefas complexas recorrentes |
| **Memória** | — | `.agent/memoria/` | Registros históricos, contexto do projeto, fatos e decisões importantes |
| **Memória do Projeto** | — | `./.memoria-ia/` | Decisões de negócio, contexto do produto, especificações e ADRs (raiz do pai, versionado pelo pai) |
| **Evoluções da IA** | `.agent/memory/` | — | Relatórios de sessões `/aprimora-ia`, otimizações dos agentes e melhorias da IA (versionado pelo submódulo) |
### Diferenças entre os artefatos
@ -171,87 +172,12 @@ Instruções com código, regras e padrões.
- A skill **pode consolidar** conhecimento de múltiplas rules e workflows em um guia unificado
- Templates de código devem estar na própria skill (não em arquivos separados, a menos que sejam muito grandes)
### Skills globais (herdadas de `.agent/base/`):
| Skill | Escopo |
|-------|--------|
| `mapear-codigo-fonte` | Mapear e navegar a estrutura de qualquer monorepo TS |
| `diagnosticar-erros-build` | Diagnosticar erros de build em cascata entre pacotes |
| `documentar-decisao-tecnica` | Registrar decisões técnicas como ADRs |
### Skills de projeto (criadas localmente em cada monorepo):
Cada projeto pode criar skills adicionais específicas em `.agent/local/skills/<nome>/SKILL`.
Essas skills focam nos padrões e domínios exclusivos daquele projeto.
Exemplos de skills de projeto:
| Skill | Escopo |
|-------|--------|
| `criar-funcao-api` | Função de API end-to-end (comuns → back → front) |
| `criar-componente-vue3` | Componente Vue 3 com padrões obrigatórios do projeto |
| `consultar-banco-knex` | Queries Knex com padrões de leitura/escrita/JSONB |
| `implementar-permissoes` | Controle de acesso específico do domínio |
- Skills globais residem em `global/skills/`
- Skills específicas do projeto residem em `.agent/local/skills/<nome>/SKILL`
---
## 5️⃣ Atualização da Memória (Obrigatória quando aplicável)
### 5A — Memória Local (arquivos)
Sempre que decisões críticas sobre a arquitetura da aplicação ou o contexto do domínio precisarem ser arquivadas temporária ou permanentemente de maneira descritiva (e não diretamente injetável em código ou regra de lint):
* Registre o novo documento no formato adequado mantendo a pasta limpa em `.agent/memoria/`.
* Exemplo: Manter diário de pendências (`diario-pendencias-modulo-x`) ou ADR (`adr-001-migracao-nuxt-4`).
* Atenção! Tudo que puder ser abstraído para formato técnico estrito deve virar **Skill** ou **Rule**. Use a Memória local apenas como extensão de base factual.
### 5B — Memória Corporativa (API Azteca — OBRIGATÓRIO)
**Todo conhecimento gerado durante a sessão DEVE ser registrado na Memória Corporativa** (`https://memoria-ia.idz.one`) seguindo a rule `global/rules/coleta-automatica-memorias`.
#### Gatilhos automáticos de registro:
| Evento na sessão | Categoria | Tipo | Registrar? |
|-------------------|-----------|------|:---:|
| Bug resolvido não trivial | `solucao-problemas` | `solucao-problemas` | 🔴 Obrigatório |
| Decisão arquitetural tomada | `decisoes` | `adr` | 🔴 Obrigatório |
| Regra de negócio descoberta/alterada | `regras-negocio` | `nota` | 🔴 Obrigatório |
| Novo módulo ou funcionalidade | `modulos` | `referencia` | 🔴 Obrigatório |
| Padrão técnico definido/alterado | `tecnologias` | `referencia` | 🔴 Obrigatório |
| Migração de banco executada | `tecnologias` | `referencia` | 🟡 Recomendado |
| Componente/padrão de UI definido | `tecnologias` | `referencia` | 🟡 Recomendado |
| Refatoração significativa | `decisoes` | `adr` | 🟡 Recomendado |
#### Protocolo:
1. **Buscar antes de criar** — evitar duplicatas (`POST /api/busca`)
2. **Criar com qualidade** — `titulo` pesquisável, `resumo` obrigatório, mínimo 3 `tags`, `criado_por` com @
3. **Vincular** — relacionar com memórias existentes via `/api/vinculos/criar`
4. **Contextualizar** — preencher `contexto` com nome do projeto/módulo
#### Exemplo de registro automático:
```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
-H 'Content-Type: application/json' \
-H "CHAVE: banana" \
-d '{
"titulo": "MODULO — Descrição clara do que foi feito/decidido",
"conteudo": "### Contexto\n...\n### Decisão\n...\n### Impacto\n...",
"resumo": "Síntese curta e pesquisável (10-500 chars)",
"categoria": "CATEGORIA",
"tipo": "TIPO",
"tags": ["modulo", "tag2", "tag3"],
"contexto": "NOME-DO-PROJETO",
"criado_por": "@HANDLE_DO_AGENTE"
}'
```
> ⚠️ **Anti-padrão:** Encerrar sessão do workflow `aprimorar-IA` sem ter registrado na Memória Corporativa é considerado **trabalho incompleto**.
---
## 6️⃣ Revisão de Impacto (Dirigida por Grafo)
## 5️⃣ Revisão de Impacto (Dirigida por Grafo)
Quando um artefato é alterado, a revisão deve ser **dirigida**, não exaustiva.
@ -297,9 +223,6 @@ Só é permitido encerrar se TODOS forem verdadeiros:
* [ ] Referências cruzadas estão válidas
* [ ] Estrutura está organizada por assunto
* [ ] Skills referenciam (não duplicam) rules
* [ ] **Conhecimento da sessão foi registrado na Memória Corporativa** (API Azteca)
* [ ] **Memórias criadas possuem `resumo`, `tags` (≥3) e `criado_por` com @**
* [ ] **Memórias relacionadas foram vinculadas** via `/api/vinculos/criar`
---

2
global/workflows/documentar-regras-negocio
View file

@ -101,5 +101,5 @@ Zero erros = concluído.
Se o workflow revelou novos padrões de negócio relevantes ao projeto:
- Criar ou atualizar ADR em `.agent/memoria/` via skill `documentar-decisao-tecnica`
- Criar ou atualizar ADR via skill `documentar-decisao-tecnica`
- Verificar se alguma rule precisa ser atualizada

19
global/workflows/ux
View file

@ -236,22 +236,11 @@ Após implementar:
---
## Anti-padrões a evitar
| ❌ Anti-padrão | ✅ Alternativa |
|---|---|
| Botão sem label de texto | Botão com ícone + texto, ou `aria-label` descritivo |
| Cor vermelha para ação primária | Vermelho apenas para destrutivas; primária usa `--cor-eli-primaria` |
| Modal com scroll interno extenso | Dividir em etapas ou usar drawer lateral |
| Tabela com 15+ colunas visíveis | Usar o modal de colunas para esconder as menos usadas |
| Placeholder como único label | Label fixo acima do campo + placeholder como exemplo |
| Ações alinhadas à esquerda em linha de tabela | Ações à direita, próximas ao fim da linha visual |
| Toast/snackbar sem ação de fechar | Sempre incluir botão de fechar ou auto-dismiss com tempo suficiente (5s+) |
| Estilos inline em `<template>` | Migrar para `<style scoped>` com classe BEM |
| Cor hex hardcoded no componente | Usar `var(--cor-eli-primaria)` e demais tokens com fallback |
| Texto escuro (`#333`) sobre `--cor-eli-primaria` | Usar branco (`#FFFFFF`) para garantir contraste WCAG AA |
| Amarelo/âmbar para sucesso | Âmbar é reservado para **aviso**; sucesso usa `--cor-eli-sucesso` (`#2E7D32`) |
| Misturar stops da paleta fora dos tokens | Usar apenas os tokens definidos; nunca interpolar valores avulsos |
| Usar `--cor-eli-media` ou `--cor-eli-acao` como fundo de cabeçalho | Usar `--cor-eli-primaria-suave` (`#BFC99C`) — verde mudo sem efeito limão |
| `var(--token)` sem fallback em componente de biblioteca | Sempre declarar `var(--token, #valor)` — o projeto destino pode não ter o token atualizado |
| Zebra de tabela sem fundo branco explícito nas linhas normais | Declarar `.eli-tabela__tr .eli-tabela__td { background: var(--cor-eli-superficie, #fff) }` antes da regra zebra |
| Modal com scroll extenso | Dividir em etapas ou usar drawer lateral |
| Tabela com 15+ colunas visíveis | Usar modal de colunas para ocultar secundárias |
| Estilos inline em template | Usar `<style scoped>` com tokens CSS e fallback |
| Cor hex hardcoded | Usar `var(--cor-eli-primaria, #688C00)` com fallback |