vue-componentes/.agent/workflows/aprimorar-IA.global.md

type	name	description	scope	updatedAt
workflow	aprimorar-IA	Consolidar aprendizados da conversa atual e evoluir continuamente as regras, skills e fluxos da aplicação	global	2026-06-01

Workflow: Aprimorar Conhecimento da Aplicação

🎯 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.

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	Responsabilidade
Rules	.agent/rules/	Restrições e convenções que o agente deve respeitar sempre
Workflows	.agent/workflows/	Processos sequenciais com passos numerados para tarefas bem definidas
Skills	.agent/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

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:

# 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/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/skills/<nome-da-skill>/SKILL.md.

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:

---
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/rules/xxx.md`
- Workflow: `.agent/workflows/xxx.md`

Regras de organização:

• Uma skill por diretório: .agent/skills/<nome>/SKILL.md
• 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 (distribuídas via atualizar-agente.global.sh):

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/skills/<nome>/SKILL.md. 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

---

5️⃣ Atualização da Memória (Obrigatória quando aplicável)

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.md) ou ADR (adr-001-migracao-nuxt-4.md).
• 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.

---

6️⃣ 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.