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

description
Consolidar aprendizados da conversa atual e evoluir continuamente as regras, skills e fluxos da aplicação

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 snake_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 Arquivo de Registro de Decisão Arquitetural (adr-001-migracao-nuxt-4.md).
• Atenção! Tudo que puder ser abstraído para um formato técnico estrito/guiado, deve virar Skill ou Rule. Use a Memória apenas como extensão de base factual.

---

6️⃣ Revisão Global de TODO o Sistema de Conhecimento (OBRIGATÓRIA E INEGOCIÁVEL)

Esta é a etapa mais crítica.

Sempre que qualquer alteração ocorrer, é OBRIGATÓRIO revisar TODO o sistema de conhecimento, incluindo:

• TODOS os arquivos em .agent/rules/
• TODOS os arquivos em .agent/workflows/
• TODOS os arquivos em .agent/skills/
• TODOS os arquivos em .agent/memoria/

É PROIBIDO:

• Atualizar apenas um arquivo isolado.
• Assumir que o impacto é local.
• Ignorar arquivos existentes.
• Criar artefatos sem validar o restante do sistema.

---

A revisão DEVE obrigatoriamente verificar:

Consistência

• Não existem regras conflitantes.
• Não existem interpretações ambíguas.
• Skills refletem fielmente as rules e workflows atuais.

Atualização

• Nenhuma rule está desatualizada.
• Nenhum workflow usa regra antiga.
• Nenhuma skill contém padrões obsoletos.

Não duplicação

• Não existem regras repetidas em arquivos diferentes.
• Conteúdos redundantes foram consolidados.
• Skills referenciam rules (não copiam o conteúdo).

Propagação de impacto

• Toda mudança foi refletida em:

  • Rules relacionadas
  • Workflows relacionados
  • Skills relacionadas
  • Memória afetada pela mudança (ADRs, Diários)

Coerência estrutural

• Nomes de arquivos continuam válidos.
• Assuntos estão bem separados.
• Arquivos grandes foram divididos.
• Skills estão organizadas em diretórios individuais.

---

Regras obrigatórias desta etapa:

• Toda alteração é considerada global até prova contrária.
• Se uma rule muda, todos os workflows e skills relacionados DEVEM ser revisados.
• Se um workflow muda, todas as rules e skills relacionadas DEVEM ser revisadas.
• Se uma skill muda, as rules e workflows que ela referencia DEVEM ser verificados.
• Atualizações de contexto devem garantir que toda a memória conflitante seja suprimida ou tagueada.
• Nenhuma inconsistência pode permanecer.
• Nenhuma duplicação é aceitável.

---

7️⃣ Verificação Final (Checklist obrigatório)

Só é permitido encerrar se TODOS forem verdadeiros:

• Todas as rules foram revisadas
• Todos os workflows foram revisados
• Todas as skills foram revisadas
• Não existe conflito entre artefatos
• Não existe duplicação de conteúdo
• Nenhuma regra ficou implícita
• Todas as mudanças foram propagadas (rules ↔ workflows ↔ skills)
• Estrutura está organizada por assunto
• Nenhum arquivo excede ~10k caracteres
• Workflows refletem fielmente as rules atuais
• Skills referenciam (não duplicam) rules
• O sistema está consistente como um todo

---

⚠️ Regra Suprema

Se existir qualquer dúvida, conflito, duplicação ou inconsistência, o trabalho é considerado INCOMPLETO.

Não existe atualização parcial. Não existe impacto local. Não existe exceção.