aplimoramento de agent
This commit is contained in:
parent
b361f25955
commit
f597436be3
83 changed files with 1312 additions and 574 deletions
|
|
@ -18,10 +18,12 @@ O agente existe para **ampliar a capacidade humana**, não para substituir decis
|
|||
|
||||
O agente pode executar sem perguntar:
|
||||
|
||||
- Consultar `memorias-ia/modulo.yml` para obter identificador (`modulo-id`), rotas (`modulo-caminho`), descrição (`modulo-descricao`) e tipo (`modulo-tipo`)
|
||||
- Criar `memorias-ia/modulo.yml` a partir do template quando inexistente em novo projeto
|
||||
- Corrigir erros de tipagem em arquivos que já está modificando
|
||||
- Aplicar formatação (`biome check --write`)
|
||||
- Atualizar referências quebradas entre artefatos
|
||||
- Criar ou atualizar documentação de regras de negócio em `../../wiki/dev/<modulo>/`
|
||||
- Criar ou atualizar documentação de regras de negócio em `<base_projeto>/../wiki/dev/<modulo-id>/`
|
||||
- Gerar JSDoc em funções compartilhadas
|
||||
- Extrair CSS para arquivo co-localizado
|
||||
- Aplicar padrões de nomenclatura já definidos em rules
|
||||
|
|
@ -42,7 +44,8 @@ O agente deve **propor e aguardar aprovação**:
|
|||
|
||||
O agente **nunca** deve:
|
||||
|
||||
- Deletar memória/ADRs sem instrução explícita do operador
|
||||
- Deletar ou corromper `memorias-ia/modulo.yml` ou memórias/ADRs sem instrução explícita do operador
|
||||
- Assumir ou inventar IDs de módulos ou rotas sem consultar `memorias-ia/modulo.yml`
|
||||
- Alterar artefatos globais (sufixo `.global`) sem justificativa
|
||||
- Inventar regras de negócio não documentadas
|
||||
- Assumir comportamento de API sem verificar o código-fonte
|
||||
|
|
|
|||
|
|
@ -26,20 +26,21 @@ Todo desenvolvimento e manutenção no ecossistema deve obrigatoriamente respeit
|
|||
| :--- | :--- | :--- | :--- |
|
||||
| **1. Código-Fonte** | `.ts`, `.vue`, `.js` | Desenvolvedores / IA | Comentários claros e coerentes quanto à sua aplicação prática, contexto e raciocínio de negócio (JSDoc no topo de funções, serviços e rotas). |
|
||||
| **2. Ajuda na Tela (UI)** | `*-front/src/.../{componente}.ajuda.md` | Usuários da UI | Ajuda contextual co-localizada: para `modalX.vue`, o arquivo de ajuda **DEVE** ser `modalX.ajuda.md`. Detalha objetivo, botões, campos e instruções de uso. |
|
||||
| **3. Wiki do Usuário** | `../../wiki/<modulo>/` | Usuários / Operadores | Aplicação VitePress com acesso dos usuários. Manuais de operação completos, tutoriais de uso, conceitos de negócio e fluxos da aplicação. |
|
||||
| **4. Wiki de Desenvolvimento** | `../../wiki/dev/<modulo>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica detalhada, modelos de banco, regras de negócio (`{modulo}.regras-negocio.md`), fluxos de filas (BullMQ), CRONs e ADRs. |
|
||||
| **3. Wiki do Usuário** | `<base_projeto>/../wiki/<modulo-id>/` | Usuários / Operadores | Aplicação VitePress com acesso dos usuários. Manuais de operação completos, tutoriais de uso, conceitos de negócio e fluxos da aplicação. |
|
||||
| **4. Wiki de Desenvolvimento** | `<base_projeto>/../wiki/dev/<modulo-id>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica detalhada, modelos de banco, regras de negócio (`{modulo}.regras-negocio.md`), fluxos de filas (BullMQ), CRONs e ADRs. |
|
||||
| **5. Integração de IA** | Rota de Backend `/llm.md` | Agentes de IA / LLMs | Documentação gerada/servida dinamicamente contendo schemas Zod, enums canônicos, endpoints e contratos para consumo por LLMs. |
|
||||
| **6. Memória das Ações da IA** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | Registros de sessões da IA, otimizações executadas, histórico de decisões arquiteturais e relatórios de aprimoramento contínuo. |
|
||||
| **6. Memória das Ações da IA e Identidade** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | Arquivo mandatório `modulo.yml` (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`), registros de sessões, histórico de decisões e relatórios de aprimoramento. |
|
||||
|
||||
> ℹ️ **Estrutura da Wiki VitePress (`../../wiki`)**:
|
||||
> - `../../wiki/<modulo>/` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes**.
|
||||
> - `../../wiki/dev/<modulo>/` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**.
|
||||
> ℹ️ **Estrutura da Wiki VitePress (`<base_projeto>/../wiki`)**:
|
||||
> - `<base_projeto>/../wiki/<modulo-id>/` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes** (onde `<modulo-id>` é o ID do módulo em `memorias-ia/modulo.yml`).
|
||||
> - `<base_projeto>/../wiki/dev/<modulo-id>/` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**.
|
||||
|
||||
> 🧩 **Polimorfismo do `.agent` e Personalização por Projeto**:
|
||||
> O repositório `.agent` é **polimórfico e genérico**, sendo compartilhado entre múltiplos projetos do ecossistema. Toda personalização de cada projeto reside em:
|
||||
> - `./memorias-ia/` (na raiz do projeto pai): Registros de ações, sessões e decisões da IA.
|
||||
> - `../../wiki/<modulo>/`: Documentação do módulo com acesso dos usuários (VitePress).
|
||||
> - `../../wiki/dev/<modulo>/`: Documentação técnica do módulo com acesso interno dev (VitePress).
|
||||
> 🧩 **Polimorfismo do `.agent` e Identidade do Projeto**:
|
||||
> O repositório `.agent` é **polimórfico e genérico**, sendo compartilhado entre múltiplos projetos do ecossistema. Toda personalização e identidade de cada projeto reside em:
|
||||
> - `./memorias-ia/modulo.yml` (na raiz do projeto pai): **Identificador mandatório** (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`). Sempre consultado quando precisar de IDs, rotas base ou stack.
|
||||
> - `./memorias-ia/`: Registros de ações, sessões e decisões da IA.
|
||||
> - `<base_projeto>/../wiki/<modulo-id>/`: Documentação do módulo com acesso dos usuários (VitePress).
|
||||
> - `<base_projeto>/../wiki/dev/<modulo-id>/`: Documentação técnica do módulo com acesso interno dev (VitePress).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -50,8 +51,8 @@ Para toda nova demanda, módulo ou funcionalidade, execute os passos abaixo:
|
|||
1. **Identificar os Pilares Impactados**:
|
||||
- É alteração de código? $\rightarrow$ Planejar comentários contextuais claros (Pilar 1).
|
||||
- É tela/modal com ajuda ao usuário? $\rightarrow$ Criar/atualizar `modalX.ajuda.md` co-localizado (Pilar 2).
|
||||
- É funcionalidade com impacto no usuário final? $\rightarrow$ Criar/atualizar documentação em `../../wiki/<modulo>/` (Pilar 3).
|
||||
- É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `../../wiki/dev/<modulo>/` (Pilar 4).
|
||||
- É funcionalidade com impacto no usuário final? $\rightarrow$ Criar/atualizar documentação em `<base_projeto>/../wiki/<modulo>/` (Pilar 3).
|
||||
- É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `<base_projeto>/../wiki/dev/<modulo>/` (Pilar 4).
|
||||
- É endpoint, schema ou contrato de API? $\rightarrow$ Assegurar reflexão na rota `/llm.md` (Pilar 5).
|
||||
- É ação estruturante ou otimização de IA? $\rightarrow$ Registrar memória em `<base_projeto>/memorias-ia/` (Pilar 6).
|
||||
|
||||
|
|
@ -82,14 +83,14 @@ A etapa de documentação prévia pode ser simplificada apenas para:
|
|||
|
||||
✅ **Correto**:
|
||||
- Criou um novo modal `ModalParametros.vue` $\rightarrow$ criou `ModalParametros.ajuda.md` na mesma pasta explicando campos e botões para o usuário.
|
||||
- Criou um serviço de cálculo de efluentes $\rightarrow$ inseriu JSDoc claro quanto à sua aplicação prática, documentou a regra técnica em `../../wiki/dev/e-licencie.sigma/` e o guia de uso em `../../wiki/e-licencie.sigma/`.
|
||||
- Criou um serviço de cálculo de efluentes $\rightarrow$ inseriu JSDoc claro quanto à sua aplicação prática, documentou a regra técnica em `<base_projeto>/../wiki/dev/e-licencie.sigma/` e o guia de uso em `<base_projeto>/../wiki/e-licencie.sigma/`.
|
||||
- Criou endpoints novos no backend $\rightarrow$ rota `/llm.md` atualizada automaticamente via gerador de contratos.
|
||||
- Realizou otimização no ecossistema de agentes $\rightarrow$ registrou relatório em `<base_projeto>/memorias-ia/`.
|
||||
|
||||
❌ **Incorreto**:
|
||||
- Criou `modalX.vue` e colocou ajuda em formato desconhecido ou fora da pasta do componente.
|
||||
- Implementou código sem comentários ou com JSDoc que apenas repete os tipos sem explicar a aplicação real no sistema.
|
||||
- Criou regras técnicas complexas sem atualizar `../../wiki/dev/<modulo>/`.
|
||||
- Criou regras técnicas complexas sem atualizar `<base_projeto>/../wiki/dev/<modulo>/`.
|
||||
- Gravou registros de ações da IA em pastas despadronizadas fora de `<base_projeto>/memorias-ia/`.
|
||||
|
||||
---
|
||||
|
|
|
|||
77
rules/identidade-modulo.md
Normal file
77
rules/identidade-modulo.md
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
---
|
||||
type: rule
|
||||
name: identidade-modulo
|
||||
description: Identificação obrigatória do projeto/módulo via memorias-ia/modulo.yml (modulo-id, modulo-caminho, modulo-descricao, modulo-tipo).
|
||||
scope: global
|
||||
trigger: always_on
|
||||
priority: critica
|
||||
updatedAt: "2026-09-02"
|
||||
---
|
||||
|
||||
# Regra: Identidade do Projeto via `memorias-ia/modulo.yml`
|
||||
|
||||
## Contexto
|
||||
|
||||
O framework `.agent` é polimórfico e genérico, sendo compartilhado como submódulo Git entre múltiplos projetos do ecossistema. Para que qualquer agente saiba com precisão e sem ambiguidades qual é o projeto hospedeiro, seu identificador canônico, suas rotas de URL, sua descrição e sua stack técnica, a identidade do módulo é centralizada em um arquivo padronizado.
|
||||
|
||||
---
|
||||
|
||||
## Regra de Existência Obrigatória
|
||||
|
||||
Todo projeto que utiliza o `.agent` **DEVE conter obrigatoriamente** na raiz do projeto pai o arquivo:
|
||||
|
||||
```
|
||||
<base_projeto>/memorias-ia/modulo.yml
|
||||
```
|
||||
|
||||
Caso o arquivo não exista ou esteja incompleto ao iniciar uma interação em um novo projeto, a prioridade máxima do agente é diagnosticá-lo e criá-lo/solicitá-lo com base no template antes de executar qualquer implementação.
|
||||
|
||||
---
|
||||
|
||||
## Estrutura Canônica de `memorias-ia/modulo.yml`
|
||||
|
||||
O arquivo deve conter estritamente as 4 chaves abaixo:
|
||||
|
||||
```yaml
|
||||
modulo-id: <identificador-do-modulo>
|
||||
modulo-caminho: <rota-na-url>
|
||||
modulo-descricao: <texto-descritivo>
|
||||
modulo-tipo: <texto-tipo-arquitetura>
|
||||
```
|
||||
|
||||
### Definição dos Campos
|
||||
|
||||
| Campo | Tipo | Descrição | Exemplo |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki e referências de regras de negócio. | `e-licencie.sigma` |
|
||||
| **`modulo-caminho`** | `string` | Rota / prefixo utilizado na URL e navegação do módulo (base route para front, proxy e endpoints). | `/sigma/` |
|
||||
| **`modulo-descricao`** | `string` | Descrição textual do propósito funcional e escopo de negócio do módulo. | `Módulo para gestão de monitoramentos ambientais` |
|
||||
| **`modulo-tipo`** | `string` | Descrição textual da arquitetura e tecnologias empregadas no módulo. | `aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres` |
|
||||
|
||||
---
|
||||
|
||||
## Regra Universal de Consulta
|
||||
|
||||
Sempre que qualquer agente, persona, workflow ou skill necessitar de:
|
||||
1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`<base_projeto>/../wiki/<modulo-id>/`), Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo-id>/`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`<base_projeto>/../wiki/dev/<modulo-id>/adrs/`) ou relatórios;
|
||||
2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `<modulo-caminho>llm.md`), links de navegação ou proxies;
|
||||
3. **Propósito ou Stack (`modulo-descricao` e `modulo-tipo`)**: para contextualizar novos agentes, gerar propostas comerciais, marketing, reels, análises de arquitetura ou testes;
|
||||
|
||||
👉 **O agente DEVE obrigatoriamente ler e extrair as informações de `memorias-ia/modulo.yml`.**
|
||||
|
||||
---
|
||||
|
||||
## Proibições
|
||||
|
||||
- **NUNCA** assumir, deduzir ou "chutar" o ID ou a rota do módulo via heurísticas incertas quando o arquivo existir.
|
||||
- **NUNCA** codificar IDs ou rotas de módulos hardcoded em regras e artefatos globais do `.agent`.
|
||||
- **NUNCA** deletar ou corromper o arquivo `memorias-ia/modulo.yml`.
|
||||
|
||||
---
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `global/rules/ddd-documentacao-primeiro.md`
|
||||
- Rule: `global/rules/regras-negocio-md.md`
|
||||
- Template: `.agent/DOCUMENTACAO/templates/modulo.yml.template`
|
||||
- Hub: `.agent/DOCUMENTACAO/README`
|
||||
|
|
@ -1,21 +1,23 @@
|
|||
---
|
||||
type: rule
|
||||
name: regras-negocio-md
|
||||
description: O conteúdo de regras de negócio deve ficar em ../../wiki/dev/<modulo>/.
|
||||
description: O conteúdo de regras de negócio deve ficar em <base_projeto>/../wiki/dev/<modulo>/.
|
||||
scope: global
|
||||
trigger: always_on
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Regra: Conteúdo de Regras de Negócio em `../../wiki/dev/<modulo>/`
|
||||
# Regra: Conteúdo de Regras de Negócio em `<base_projeto>/../wiki/dev/<modulo>/`
|
||||
|
||||
> **Escopo global** — aplica-se a todos os projetos do ecossistema Azteca.
|
||||
|
||||
## Contexto
|
||||
|
||||
Toda lógica de negócio não-trivial — regras de decisão, critérios de bloqueio, estratégias de processamento, priorizações e fluxos de dados — deve ter seu conteúdo documentado em linguagem natural na **Wiki de Desenvolvimento** em `../../wiki/dev/<modulo>/`.
|
||||
Toda lógica de negócio não-trivial — regras de decisão, critérios de bloqueio, estratégias de processamento, priorizações e fluxos de dados — deve ter seu conteúdo documentado em linguagem natural na **Wiki de Desenvolvimento** em `<base_projeto>/../wiki/dev/<modulo>/`.
|
||||
|
||||
> 💡 **Aplicação VitePress (`../../wiki`)**: O diretório `../../wiki` é uma aplicação VitePress na qual `../../wiki/<modulo>/` é voltado ao acesso dos **usuários**, e `../../wiki/dev/<modulo>/` é reservado ao **acesso interno exclusivo da equipe de desenvolvimento**.
|
||||
> 💡 **Aplicação VitePress (`<base_projeto>/../wiki`) e Resolução do Módulo**:
|
||||
> - O diretório `<base_projeto>/../wiki` é uma aplicação VitePress na qual `<base_projeto>/../wiki/<modulo-id>/` é voltado ao acesso dos **usuários**, e `<base_projeto>/../wiki/dev/<modulo-id>/` é reservado ao **acesso interno exclusivo da equipe de desenvolvimento**.
|
||||
> - O identificador `<modulo-id>` (ou `<modulo>`) **DEVE** ser obtido obrigatoriamente do campo `modulo-id` em `memorias-ia/modulo.yml` na raiz do projeto (ex: `e-licencie.sigma`).
|
||||
|
||||
Isso garante centralização, governança técnica e facilidade de consulta por desenvolvedores, arquitetos e agentes de IA.
|
||||
|
||||
|
|
@ -23,7 +25,7 @@ Isso garante centralização, governança técnica e facilidade de consulta por
|
|||
|
||||
## Regra
|
||||
|
||||
**Todo o conteúdo detalhado de regras de negócio DEVE ficar em `../../wiki/dev/<modulo>/`.**
|
||||
**Todo o conteúdo detalhado de regras de negócio DEVE ficar em `<base_projeto>/../wiki/dev/<modulo>/`.**
|
||||
|
||||
Considera-se lógica não-trivial qualquer módulo que:
|
||||
- Possui 3 ou mais critérios de decisão distintos
|
||||
|
|
@ -35,7 +37,7 @@ Considera-se lógica não-trivial qualquer módulo que:
|
|||
O módulo TypeScript deve conter, na primeira linha útil do arquivo, a referência:
|
||||
|
||||
```typescript
|
||||
// Regras de negócio: ver ../../wiki/dev/<modulo>/{modulo}.regras-negocio.md
|
||||
// Regras de negócio: ver <base_projeto>/../wiki/dev/<modulo>/{modulo}.regras-negocio.md
|
||||
```
|
||||
|
||||
A documentação na **Wiki de Desenvolvimento** é a **fonte de verdade da lógica operacional**. Os comentários JSDoc no código explicam a aplicação prática da função e apontam para a wiki para o detalhamento dos critérios.
|
||||
|
|
@ -44,7 +46,7 @@ A documentação na **Wiki de Desenvolvimento** é a **fonte de verdade da lógi
|
|||
|
||||
## Estrutura do Documento de Regras na Wiki de Desenvolvimento
|
||||
|
||||
**Localização:** `../../wiki/dev/<modulo>/` (ex.: `../../wiki/dev/e-licencie.sigma/regras-negocio/` ou `../../wiki/dev/e-licencie.sigma/{modulo}.regras-negocio.md`)
|
||||
**Localização:** `<base_projeto>/../wiki/dev/<modulo>/` (ex.: `<base_projeto>/../wiki/dev/e-licencie.sigma/regras-negocio/` ou `<base_projeto>/../wiki/dev/e-licencie.sigma/{modulo}.regras-negocio.md`)
|
||||
|
||||
```markdown
|
||||
# Regras de Negócio — [Nome do Módulo / Serviço]
|
||||
|
|
@ -79,7 +81,7 @@ Tabelas, filas BullMQ, rotas e serviços externos tocados pelo módulo.
|
|||
|
||||
✅ **Correto** — referência no topo do módulo apontando para a Wiki de Desenvolvimento:
|
||||
```typescript
|
||||
// Regras de negócio: ver ../../wiki/dev/e-licencie.sigma/juntar_execucoes.regras-negocio.md
|
||||
// Regras de negócio: ver <base_projeto>/../wiki/dev/e-licencie.sigma/juntar_execucoes.regras-negocio.md
|
||||
|
||||
import { ... } from "..."
|
||||
|
||||
|
|
@ -117,4 +119,4 @@ export const compilarJuntarExecucoes = async (...) => {
|
|||
- Rule: `rules/jsdoc-padrao.md`
|
||||
- Skill: `skills/documentar-regras-negocio/SKILL.md`
|
||||
- Workflow: `global/workflows/documentar-regras-negocio.md`
|
||||
- Wiki de Desenvolvimento: `../../wiki/dev/<modulo>/`
|
||||
- Wiki de Desenvolvimento: `<base_projeto>/../wiki/dev/<modulo>/`
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue