--- 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: ```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/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//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: ```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/rules/xxx.md` - Workflow: `.agent/workflows/xxx.md` ``` ### Regras de organização: - Uma skill por diretório: `.agent/skills//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//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.