--- type: workflow name: aprimora-ia description: Otimizar o ecossistema da IA conforme identificado durante a conversa e registrar eventos na memória scope: global updatedAt: "2026-08-10" --- # Workflow: /aprimora-ia (Aprimoramento Contínuo e Registro de Memória) ## 🎯 Objetivo 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. --- ## Artefatos de Conhecimento O conhecimento do agente está organizado em **três tipos de artefatos**, cada um com responsabilidade distinta: | Artefato | Diretório (herdado) | Diretório (local) | Responsabilidade | |----------|---------------------|-------------------|------------------| | **Rules** | `.agent/rules/` | `.agent/rules/` | Restrições e convenções que o agente **deve respeitar sempre** | | **Workflows** | `.agent/workflows/` | `.agent/workflows/` | Processos sequenciais com passos numerados para tarefas bem definidas | | **Skills** | `.agent/skills/` | `.agent/skills/` | Guias operacionais completos e reutilizáveis para tarefas complexas recorrentes | | **Memória das Ações da IA** | — | `/memorias-ia/` | Registros de sessões, otimizações dos agentes, decisões e relatórios da IA (raiz do pai) | > 🧩 **Polimorfismo do `.agent` e Personalização por Projeto**: > O `.agent` é polimórfico e genérico. A personalização de cada projeto específico é mantida fora do `.agent`: > - `./memorias-ia/` (na raiz do projeto pai): Registros de ações, sessões e decisões da IA. > - `../../wiki//`: Documentação funcional com acesso dos usuários na aplicação VitePress. > - `../../wiki/dev//`: Documentação técnica com acesso interno dev na aplicação VitePress. ### Diferenças entre os artefatos | Critério | Rule | Workflow | Skill | Memória | |----------|------|----------|-------|---------| | **Formato** | Regra declarativa | Passos sequenciais | Guia prático com templates | Diários, ADRs, documentação de contexto puro | | **Quando usar** | Aplicada **automaticamente** em todo contexto | Acionado por **comando** (`/workflow`) | Consultado **sob demanda** ao iniciar tarefa complexa | Consultado **para restaurar contexto** e entender escopo | | **Exemplos** | "Nunca usar `any`" | "/migracao_banco" | "Criar função api2 end-to-end" | "ADR de transição para Nuxt 4", "Dicionário de dados" | | **Escopo** | Restrição transversal | Processo pontual | Padrão operacional completo | Registro histórico e base factual | ### Regra de escolha - Se é uma **restrição** que vale sempre → **Rule** - Se é um **processo com etapas** que o usuário aciona → **Workflow** - Se é um **guia operacional** com templates e checklist para tarefas complexas → **Skill** - Se o conteúdo serve como **referência cruzada** durante tarefas → **Skill** - Se é um **registro de estado, decisão técnica importante ou compreensão do domínio temporal** → **Memória** --- ## 1️⃣ Análise do Contexto Atual (Obrigatória) É obrigatório: - Revisar integralmente a conversa atual. - Identificar: - Regras de negócio novas ou alteradas. - Padrões técnicos definidos. - Convenções estabelecidas. - Decisões arquiteturais. - Ajustes de comportamento do sistema ou do agente. Para cada item identificado, classificar obrigatoriamente: - Já existe artefato correspondente (rule, workflow ou skill) → **ATUALIZAR** - Existe parcialmente → **REFATORAR** - Não existe → **CRIAR** - Impacta múltiplas áreas → **PROPAGAR** --- ## 2️⃣ Atualização das Rules (Obrigatória) ### Regras inegociáveis: - Toda nova regra **DEVE** ser registrada. - Nenhuma regra pode existir apenas na conversa. - É **PROIBIDO** deixar conhecimento implícito. ### Estrutura obrigatória: - Um arquivo = um único assunto. - Nome claro em `kebab-case`. - Limite máximo: ~10.000 caracteres. ### É obrigatório: - Evitar duplicação de conteúdo. - Atualizar regras antigas quando substituídas. - Remover ou ajustar regras conflitantes. - Garantir consistência semântica entre arquivos. ### Estrutura obrigatória da rule: ```md # Nome da Regra ## Contexto Quando se aplica. ## Regra Definição objetiva e obrigatória. ## Exemplos ✅ Correto ❌ Incorreto ## Impacto Problema que evita. ``` --- ## 3️⃣ Atualização dos Workflows (Obrigatória quando aplicável) Sempre que houver processo repetível identificado: * Criar ou atualizar workflow em `.agent/local/workflows/`. ### Obrigatório: * Frontmatter com `description`. * Passos numerados. * Clareza operacional (sem ambiguidade). * Comandos executáveis quando possível. * Uso de `// turbo` para comandos seguros. --- ## 4️⃣ Atualização das Skills (Obrigatória quando aplicável) Sempre que um padrão operacional complexo for definido, refinado ou corrigido: * Criar ou atualizar skill em `.agent/local/skills//SKILL`. ### Quando atualizar uma skill: - Nova regra afeta o padrão operacional descrito na skill (ex: nova convenção de tipagem afeta `criar-funcao-api2`) - Novo workflow introduz etapas que complementam ou substituem uma skill - Um erro recorrente revela que a skill está incompleta ou desatualizada - Uma decisão arquitetural muda o fluxo descrito na skill ### Estrutura obrigatória da skill: ```md --- name: nome-da-skill description: > Descrição em uma linha do que a skill faz. --- # Skill: Nome Descritivo Parágrafo de contexto explicando quando usar. ## PASSO N — Título do Passo Instruções com código, regras e padrões. ## Checklist Final - [ ] Item de verificação ## Referências - Regras: `.agent/local/rules/xxx` - Workflow: `.agent/local/workflows/xxx` ``` ### Regras de organização: - Uma skill por diretório: `.agent/local/skills//SKILL` - Skills globais são identificadas pelo campo `scope: global` no frontmatter - Nome do diretório em `kebab-case` - A skill **não deve duplicar** conteúdo de rules — referencia-as via seção `Referências` - 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 residem em `global/skills/` - Skills específicas do projeto residem em `.agent/local/skills//SKILL` --- ## 5️⃣ Revisão de Impacto (Dirigida por Grafo) Quando um artefato é alterado, a revisão deve ser **dirigida**, não exaustiva. ### Processo: 1. Identificar o artefato alterado 2. Consultar a seção `Referências` do artefato para encontrar dependentes diretos 3. Verificar consistência APENAS entre o artefato alterado e seus dependentes 4. Se uma inconsistência for encontrada, propagar para o próximo nível ### Regras de escopo: | Se alterou... | Revisar... | |---|---| | Uma **Rule** | Workflows e skills que a **referenciam** | | Um **Workflow** | Skills que o **referenciam** | | Uma **Skill** | Rules e workflows na seção Referências | | **Memória/ADR** | Nada — memória é registro, não dependência | ### É PROIBIDO: * Revisar artefatos **sem relação** com a mudança * Afirmar que "tudo foi revisado" sem listar quais artefatos foram verificados * Criar artefatos sem verificar se já existe um com o mesmo escopo ### A revisão DEVE verificar: * Não existem regras conflitantes entre o artefato alterado e seus dependentes * Referências cruzadas continuam válidas (arquivos existem, nomes corretos) * Skills refletem fielmente as rules que referenciam * Não há duplicação de conteúdo entre artefatos --- ## 7⃣ Verificação Final (Checklist obrigatório) Só é permitido encerrar se TODOS forem verdadeiros: * [ ] Artefatos dependentes do alterado foram revisados * [ ] Não existe conflito entre artefatos revisados * [ ] Não existe duplicação de conteúdo * [ ] Nenhuma regra ficou implícita * [ ] Referências cruzadas estão válidas * [ ] Estrutura está organizada por assunto * [ ] Skills referenciam (não duplicam) rules --- ## ⚠️ Regra Suprema > Se existir qualquer dúvida, conflito ou inconsistência > entre o artefato alterado e seus dependentes, > o trabalho é considerado **INCOMPLETO**. A revisão é dirigida, não opcional.