From b0bb8b00ac02a3415ca20e80df0575596e2ec6c7 Mon Sep 17 00:00:00 2001 From: Luiz Silva Date: Tue, 7 Jul 2026 08:49:20 -0300 Subject: [PATCH] melhoria de colera de memorias --- global/rules/coleta-automatica-memorias | 127 ++++++++++++++++++++++++ global/workflows/aprimorar-IA | 51 +++++++++- manifesto.json | 1 + 3 files changed, 178 insertions(+), 1 deletion(-) create mode 100644 global/rules/coleta-automatica-memorias diff --git a/global/rules/coleta-automatica-memorias b/global/rules/coleta-automatica-memorias new file mode 100644 index 0000000..bdd5a53 --- /dev/null +++ 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` diff --git a/global/workflows/aprimorar-IA b/global/workflows/aprimorar-IA index 1ee5e4a..7f549dc 100644 --- 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` --- diff --git a/manifesto.json b/manifesto.json index 916cab0..a210d6d 100644 --- a/manifesto.json +++ b/manifesto.json @@ -7,6 +7,7 @@ "rules": [ "global/rules/autonomia-agente", "global/rules/carta-principios-agente-azteca", + "global/rules/coleta-automatica-memorias", "global/rules/consultar-banco-query-ia", "global/rules/escrita-natural", "global/rules/estilos-design-system",