melhoria de colera de memorias

2026-07-07 08:49:20 -03:00 · 2026-07-07 08:49:20 -03:00 · b0bb8b00ac
commit b0bb8b00ac
parent f3c9e7b60c
3 changed files with 178 additions and 1 deletions
--- a/global/rules/coleta-automatica-memorias
+++ b/global/rules/coleta-automatica-memorias
@ -0,0 +1,127 @@
+---
+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`
--- a/global/workflows/aprimorar-IA
+++ b/global/workflows/aprimorar-IA
@ -197,11 +197,57 @@ Exemplos de skills de projeto:

 ## 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 apenas como extensão de base factual.
+* 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**.

 ---

@ -251,6 +297,9 @@ 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`

 ---