241 lines
8.5 KiB
Markdown
241 lines
8.5 KiB
Markdown
---
|
||
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** | — | `<base_projeto>/memorias-ia/` | Registros de sessões, otimizações dos agentes, decisões e relatórios da IA (raiz do pai) |
|
||
|
||
> 🧩 **Polimorfismo do `.agent` e Identidade por Projeto**:
|
||
> O `.agent` é polimórfico e genérico. A personalização e identidade de cada projeto específico é mantida fora do `.agent`:
|
||
> - `./memorias-ia/modulo.yml` (na raiz do projeto pai): Arquivo mandatório com `modulo-id`, `modulo-caminho`, `modulo-descricao` e `modulo-tipo`.
|
||
> - `./memorias-ia/`: Registros de ações, sessões e decisões da IA.
|
||
> - `<base_projeto>/../wiki/<modulo-id>/`: Documentação funcional com acesso dos usuários na aplicação VitePress.
|
||
> - `<base_projeto>/../wiki/dev/<modulo-id>/`: 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/<nome-da-skill>/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/<nome>/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/<nome>/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.
|