melhorias em compoenentes de numero
This commit is contained in:
parent
5124844773
commit
303eda1b99
27 changed files with 3056 additions and 55 deletions
300
.agent/workflows/aprimorar-IA.global.md
Normal file
300
.agent/workflows/aprimorar-IA.global.md
Normal file
|
|
@ -0,0 +1,300 @@
|
|||
---
|
||||
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/<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:
|
||||
|
||||
```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/<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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue