feat(identidade): padronizar modulo-acesso e modulo-wiki no framework e validar-setup
This commit is contained in:
parent
d43631be13
commit
19df29ea45
18 changed files with 193 additions and 104 deletions
|
|
@ -2,7 +2,7 @@
|
|||
# Este arquivo é obrigatório na raiz de todos os projetos que utilizam .agent.
|
||||
# Ele define a identidade oficial e as configurações de rota do módulo.
|
||||
|
||||
# Identificador único do módulo (utilizado para pacotes, wikis <base_projeto>/../wiki/<modulo-id>/ e regras de negócio)
|
||||
# Identificador único do módulo (utilizado para pacotes, wikis <modulo-wiki>/<modulo-id>/ e regras de negócio)
|
||||
modulo-id: nome-do-modulo.submodulo
|
||||
|
||||
# Rota/prefixo utilizado na URL e navegação do módulo (com barras inicial e final)
|
||||
|
|
@ -13,3 +13,11 @@ modulo-descricao: Descrição detalhada do módulo para contextualização opera
|
|||
|
||||
# Descrição da arquitetura, stack tecnológica e banco de dados
|
||||
modulo-tipo: aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres
|
||||
|
||||
# Credenciais padrão para autenticação em testes (agent-browser, E2E, QA)
|
||||
modulo-acesso:
|
||||
usuario: usuario@exemplo.com.br
|
||||
senha: "123"
|
||||
|
||||
# Caminho para a Wiki do projeto (quando omitido ou vazio, o padrão adotado é ../wiki/)
|
||||
modulo-wiki: ../wiki
|
||||
|
|
|
|||
|
|
@ -26,21 +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** | `<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. |
|
||||
| **3. Wiki do Usuário** | `<modulo-wiki>/<modulo-id>/` | Usuários / Operadores | Aplicação VitePress com acesso dos usuários (caminho definido em `modulo-wiki` em `modulo.yml`, fallback padrão: `../wiki/`). Manuais de operação completos, tutoriais de uso, conceitos de negócio e fluxos da aplicação. |
|
||||
| **4. Wiki de Desenvolvimento** | `<modulo-wiki>/dev/<modulo-id>/` | Desenvolvedores / Arquitetos | Seçã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 e Identidade** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | `modulo.yml` (identidade), índice central `historico-acoes.md` (`Data \| Memória / Ação \| Arquivo Memoria \| Citações no Código-Fonte`) e sessões individuais `sessao-AAAA-MM-DD-slug.md`. |
|
||||
|
||||
> ℹ️ **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**.
|
||||
> ℹ️ **Estrutura da Wiki VitePress (`<modulo-wiki>`, padrão: `<base_projeto>/../wiki`)**:
|
||||
> - `<modulo-wiki>/<modulo-id>/` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes** (onde `<modulo-id>` e `<modulo-wiki>` são extraídos de `memorias-ia/modulo.yml`, com fallback padrão para `../wiki/`).
|
||||
> - `<modulo-wiki>/dev/<modulo-id>/` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**.
|
||||
|
||||
> 🧩 **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/modulo.yml` (na raiz do projeto pai): **Identificador mandatório** (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`, `modulo-acesso`, `modulo-wiki`). Sempre consultado quando precisar de IDs, rotas base, credenciais de teste ou stack.
|
||||
> - `./memorias-ia/`: Registros individuais `sessao-AAAA-MM-DD-slug.md` e índice cumulativo `historico-acoes.md`.
|
||||
> - `<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).
|
||||
> - `<modulo-wiki>/<modulo-id>/`: Documentação do módulo com acesso dos usuários (VitePress).
|
||||
> - `<modulo-wiki>/dev/<modulo-id>/`: Documentação técnica do módulo com acesso interno dev (VitePress).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -51,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 `<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).
|
||||
- É funcionalidade com impacto no usuário final? $\rightarrow$ Criar/atualizar documentação em `<modulo-wiki>/<modulo>/` (Pilar 3).
|
||||
- É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `<modulo-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/sessao-AAAA-MM-DD-slug.md` e indexar em `historico-acoes.md` (Pilar 6).
|
||||
|
||||
|
|
|
|||
|
|
@ -1,18 +1,18 @@
|
|||
---
|
||||
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).
|
||||
description: Identificação obrigatória do projeto/módulo via memorias-ia/modulo.yml (modulo-id, modulo-caminho, modulo-descricao, modulo-tipo, modulo-acesso, modulo-wiki).
|
||||
scope: global
|
||||
trigger: always_on
|
||||
priority: critica
|
||||
updatedAt: "2026-09-02"
|
||||
updatedAt: "2026-10-06"
|
||||
---
|
||||
|
||||
# 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.
|
||||
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, sua stack técnica, suas credenciais de teste e o caminho da sua Wiki, a identidade do módulo é centralizada em um arquivo padronizado.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -30,13 +30,21 @@ Caso o arquivo não exista ou esteja incompleto ao iniciar uma interação em um
|
|||
|
||||
## Estrutura Canônica de `memorias-ia/modulo.yml`
|
||||
|
||||
O arquivo deve conter estritamente as 4 chaves abaixo:
|
||||
O arquivo contém os seguintes campos estruturados:
|
||||
|
||||
```yaml
|
||||
modulo-id: <identificador-do-modulo>
|
||||
modulo-caminho: <rota-na-url>
|
||||
modulo-descricao: <texto-descritivo>
|
||||
modulo-tipo: <texto-tipo-arquitetura>
|
||||
|
||||
# Credenciais padrão para autenticação em testes (agent-browser, E2E, QA)
|
||||
modulo-acesso:
|
||||
usuario: <login-ou-email>
|
||||
senha: <senha-de-teste>
|
||||
|
||||
# Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/)
|
||||
modulo-wiki: <caminho-da-wiki>
|
||||
```
|
||||
|
||||
### Definição dos Campos
|
||||
|
|
@ -47,15 +55,19 @@ modulo-tipo: <texto-tipo-arquitetura>
|
|||
| **`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` |
|
||||
| **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`). | `{ usuario: "admin@gov.br", senha: "123" }` |
|
||||
| **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `./QUIPO-WIKI` ou `../wiki` |
|
||||
|
||||
---
|
||||
|
||||
## 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;
|
||||
1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`), Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`<modulo-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;
|
||||
4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística em rotinas de teste e validação de interface;
|
||||
5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia.
|
||||
|
||||
👉 **O agente DEVE obrigatoriamente ler e extrair as informações de `memorias-ia/modulo.yml`.**
|
||||
|
||||
|
|
@ -63,8 +75,8 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de:
|
|||
|
||||
## 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** assumir, deduzir ou "chutar" o ID, a rota, credenciais de teste ou caminho de wiki via heurísticas incertas quando o arquivo existir.
|
||||
- **NUNCA** codificar IDs, rotas ou credenciais hardcoded em regras e artefatos globais do `.agent`.
|
||||
- **NUNCA** deletar ou corromper o arquivo `memorias-ia/modulo.yml`.
|
||||
|
||||
---
|
||||
|
|
@ -73,5 +85,6 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de:
|
|||
|
||||
- Rule: `global/rules/ddd-documentacao-primeiro.md`
|
||||
- Rule: `global/rules/regras-negocio-md.md`
|
||||
- Rule: `global/rules/testes-interface-agent-browser.md`
|
||||
- Template: `.agent/DOCUMENTACAO/templates/modulo.yml.template`
|
||||
- Hub: `.agent/DOCUMENTACAO/README`
|
||||
|
|
|
|||
|
|
@ -53,22 +53,23 @@ A IA **PODE** realizar commits na aplicação principal, **ESTRITAMENTE CONDICIO
|
|||
|
||||
---
|
||||
|
||||
### 2. No Repositório da Wiki (`<base_projeto>/../wiki`) — COMMIT, PUSH E RESOLUÇÃO DE CONFLITOS DIRETO NA MASTER
|
||||
### 2. No Repositório da Wiki (`<modulo-wiki>`, padrão: `<base_projeto>/../wiki`) — COMMIT, PUSH E RESOLUÇÃO DE CONFLITOS DIRETO NA MASTER
|
||||
|
||||
Na Wiki, a IA possui permissão total e obrigação de manter a documentação atualizada diretamente na branch `master`:
|
||||
Na Wiki (caminho resolvido dinamicamente via `modulo-wiki` em `memorias-ia/modulo.yml`, com fallback mandatório para `<base_projeto>/../wiki`), a IA possui permissão total e obrigação de manter a documentação atualizada diretamente na branch `master`:
|
||||
|
||||
1. **Commit e Push Diretos na Master**:
|
||||
```bash
|
||||
git -C <base_projeto>/../wiki add -A
|
||||
git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): <descrição sucinta das alterações>"
|
||||
git -C <base_projeto>/../wiki push origin master
|
||||
# <modulo-wiki> extraído de memorias-ia/modulo.yml (fallback padrão: ../wiki)
|
||||
git -C <modulo-wiki> add -A
|
||||
git -C <modulo-wiki> commit -m "docs(<modulo-id>): <descrição sucinta das alterações>"
|
||||
git -C <modulo-wiki> push origin master
|
||||
```
|
||||
|
||||
2. **Resolução de Conflitos Direto na Master**:
|
||||
Se ao dar push houver rejeição ou divergência com o upstream remoto:
|
||||
- A IA executa `git -C <base_projeto>/../wiki pull --rebase origin master`.
|
||||
- A IA executa `git -C <modulo-wiki> pull --rebase origin master`.
|
||||
- Havendo conflitos de merge, a IA resolve as marcações diretamente na `master`, preservando a coerência da documentação dos 6 pilares.
|
||||
- Adiciona os arquivos resolvidos (`git -C <base_projeto>/../wiki add -A`), finaliza o rebase (`git -C <base_projeto>/../wiki rebase --continue` ou commit) e envia com `git push origin master`.
|
||||
- Adiciona os arquivos resolvidos (`git -C <modulo-wiki> add -A`), finaliza o rebase (`git -C <modulo-wiki> rebase --continue` ou commit) e envia com `git push origin master`.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -7,17 +7,18 @@ trigger: always_on
|
|||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Regra: Conteúdo de Regras de Negócio em `<base_projeto>/../wiki/dev/<modulo>/`
|
||||
# Regra: Conteúdo de Regras de Negócio em `<modulo-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 `<base_projeto>/../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 `<modulo-wiki>/dev/<modulo>/`.
|
||||
|
||||
> 💡 **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`).
|
||||
> 💡 **Aplicação VitePress (`<modulo-wiki>`, padrão: `<base_projeto>/../wiki`) e Resolução do Módulo**:
|
||||
> - O caminho da Wiki `<modulo-wiki>` **DEVE** ser obtido dinamicamente a partir do campo `modulo-wiki` em `memorias-ia/modulo.yml` (adotando compulsoriamente o fallback padrão `../wiki/` quando omitido ou não configurado).
|
||||
> - Na Wiki resolvida, `<modulo-wiki>/<modulo-id>/` é voltado ao acesso dos **usuários**, e `<modulo-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` ou `e-licencie-gov`).
|
||||
|
||||
Isso garante centralização, governança técnica e facilidade de consulta por desenvolvedores, arquitetos e agentes de IA.
|
||||
|
||||
|
|
@ -25,7 +26,8 @@ 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 `<base_projeto>/../wiki/dev/<modulo>/`.**
|
||||
**Todo o conteúdo detalhado de regras de negócio DEVE ficar em `<modulo-wiki>/dev/<modulo>/`.**
|
||||
|
||||
|
||||
Considera-se lógica não-trivial qualquer módulo que:
|
||||
- Possui 3 ou mais critérios de decisão distintos
|
||||
|
|
|
|||
|
|
@ -32,6 +32,9 @@ Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar
|
|||
4. **Registrar evidências e fechar sessão**:
|
||||
- Registrar comprovações visuais com `agent-browser screenshot <arquivo.png>`.
|
||||
- Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo.
|
||||
5. **Credenciais Canônicas de Teste (`modulo-acesso`)**:
|
||||
- Sempre que o teste exigir autenticação (login, sessão administrativa), o agente **DEVE OBRIGATORIAMENTE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml`**.
|
||||
- É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -26,21 +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** | `<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. |
|
||||
| **3. Wiki do Usuário** | `<modulo-wiki>/<modulo-id>/` | Usuários / Operadores | Aplicação VitePress com acesso dos usuários (caminho definido em `modulo-wiki` em `modulo.yml`, fallback padrão: `../wiki/`). Manuais de operação completos, tutoriais de uso, conceitos de negócio e fluxos da aplicação. |
|
||||
| **4. Wiki de Desenvolvimento** | `<modulo-wiki>/dev/<modulo-id>/` | Desenvolvedores / Arquitetos | Seçã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 e Identidade** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | `modulo.yml` (identidade), índice central `historico-acoes.md` (`Data \| Memória / Ação \| Arquivo Memoria \| Citações no Código-Fonte`) e sessões individuais `sessao-AAAA-MM-DD-slug.md`. |
|
||||
|
||||
> ℹ️ **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**.
|
||||
> ℹ️ **Estrutura da Wiki VitePress (`<modulo-wiki>`, padrão: `<base_projeto>/../wiki`)**:
|
||||
> - `<modulo-wiki>/<modulo-id>/` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes** (onde `<modulo-id>` e `<modulo-wiki>` são extraídos de `memorias-ia/modulo.yml`, com fallback padrão para `../wiki/`).
|
||||
> - `<modulo-wiki>/dev/<modulo-id>/` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**.
|
||||
|
||||
> 🧩 **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/modulo.yml` (na raiz do projeto pai): **Identificador mandatório** (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`, `modulo-acesso`, `modulo-wiki`). Sempre consultado quando precisar de IDs, rotas base, credenciais de teste ou stack.
|
||||
> - `./memorias-ia/`: Registros individuais `sessao-AAAA-MM-DD-slug.md` e índice cumulativo `historico-acoes.md`.
|
||||
> - `<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).
|
||||
> - `<modulo-wiki>/<modulo-id>/`: Documentação do módulo com acesso dos usuários (VitePress).
|
||||
> - `<modulo-wiki>/dev/<modulo-id>/`: Documentação técnica do módulo com acesso interno dev (VitePress).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -51,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 `<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).
|
||||
- É funcionalidade com impacto no usuário final? $\rightarrow$ Criar/atualizar documentação em `<modulo-wiki>/<modulo>/` (Pilar 3).
|
||||
- É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `<modulo-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/sessao-AAAA-MM-DD-slug.md` e indexar em `historico-acoes.md` (Pilar 6).
|
||||
|
||||
|
|
|
|||
|
|
@ -1,18 +1,18 @@
|
|||
---
|
||||
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).
|
||||
description: Identificação obrigatória do projeto/módulo via memorias-ia/modulo.yml (modulo-id, modulo-caminho, modulo-descricao, modulo-tipo, modulo-acesso, modulo-wiki).
|
||||
scope: global
|
||||
trigger: always_on
|
||||
priority: critica
|
||||
updatedAt: "2026-09-02"
|
||||
updatedAt: "2026-10-06"
|
||||
---
|
||||
|
||||
# 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.
|
||||
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, sua stack técnica, suas credenciais de teste e o caminho da sua Wiki, a identidade do módulo é centralizada em um arquivo padronizado.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -30,13 +30,21 @@ Caso o arquivo não exista ou esteja incompleto ao iniciar uma interação em um
|
|||
|
||||
## Estrutura Canônica de `memorias-ia/modulo.yml`
|
||||
|
||||
O arquivo deve conter estritamente as 4 chaves abaixo:
|
||||
O arquivo contém os seguintes campos estruturados:
|
||||
|
||||
```yaml
|
||||
modulo-id: <identificador-do-modulo>
|
||||
modulo-caminho: <rota-na-url>
|
||||
modulo-descricao: <texto-descritivo>
|
||||
modulo-tipo: <texto-tipo-arquitetura>
|
||||
|
||||
# Credenciais padrão para autenticação em testes (agent-browser, E2E, QA)
|
||||
modulo-acesso:
|
||||
usuario: <login-ou-email>
|
||||
senha: <senha-de-teste>
|
||||
|
||||
# Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/)
|
||||
modulo-wiki: <caminho-da-wiki>
|
||||
```
|
||||
|
||||
### Definição dos Campos
|
||||
|
|
@ -47,15 +55,19 @@ modulo-tipo: <texto-tipo-arquitetura>
|
|||
| **`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` |
|
||||
| **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`). | `{ usuario: "admin@gov.br", senha: "123" }` |
|
||||
| **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `./QUIPO-WIKI` ou `../wiki` |
|
||||
|
||||
---
|
||||
|
||||
## 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;
|
||||
1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`), Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`<modulo-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;
|
||||
4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística em rotinas de teste e validação de interface;
|
||||
5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia.
|
||||
|
||||
👉 **O agente DEVE obrigatoriamente ler e extrair as informações de `memorias-ia/modulo.yml`.**
|
||||
|
||||
|
|
@ -63,8 +75,8 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de:
|
|||
|
||||
## 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** assumir, deduzir ou "chutar" o ID, a rota, credenciais de teste ou caminho de wiki via heurísticas incertas quando o arquivo existir.
|
||||
- **NUNCA** codificar IDs, rotas ou credenciais hardcoded em regras e artefatos globais do `.agent`.
|
||||
- **NUNCA** deletar ou corromper o arquivo `memorias-ia/modulo.yml`.
|
||||
|
||||
---
|
||||
|
|
@ -73,5 +85,6 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de:
|
|||
|
||||
- Rule: `global/rules/ddd-documentacao-primeiro.md`
|
||||
- Rule: `global/rules/regras-negocio-md.md`
|
||||
- Rule: `global/rules/testes-interface-agent-browser.md`
|
||||
- Template: `.agent/DOCUMENTACAO/templates/modulo.yml.template`
|
||||
- Hub: `.agent/DOCUMENTACAO/README`
|
||||
|
|
|
|||
|
|
@ -53,22 +53,23 @@ A IA **PODE** realizar commits na aplicação principal, **ESTRITAMENTE CONDICIO
|
|||
|
||||
---
|
||||
|
||||
### 2. No Repositório da Wiki (`<base_projeto>/../wiki`) — COMMIT, PUSH E RESOLUÇÃO DE CONFLITOS DIRETO NA MASTER
|
||||
### 2. No Repositório da Wiki (`<modulo-wiki>`, padrão: `<base_projeto>/../wiki`) — COMMIT, PUSH E RESOLUÇÃO DE CONFLITOS DIRETO NA MASTER
|
||||
|
||||
Na Wiki, a IA possui permissão total e obrigação de manter a documentação atualizada diretamente na branch `master`:
|
||||
Na Wiki (caminho resolvido dinamicamente via `modulo-wiki` em `memorias-ia/modulo.yml`, com fallback mandatório para `<base_projeto>/../wiki`), a IA possui permissão total e obrigação de manter a documentação atualizada diretamente na branch `master`:
|
||||
|
||||
1. **Commit e Push Diretos na Master**:
|
||||
```bash
|
||||
git -C <base_projeto>/../wiki add -A
|
||||
git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): <descrição sucinta das alterações>"
|
||||
git -C <base_projeto>/../wiki push origin master
|
||||
# <modulo-wiki> extraído de memorias-ia/modulo.yml (fallback padrão: ../wiki)
|
||||
git -C <modulo-wiki> add -A
|
||||
git -C <modulo-wiki> commit -m "docs(<modulo-id>): <descrição sucinta das alterações>"
|
||||
git -C <modulo-wiki> push origin master
|
||||
```
|
||||
|
||||
2. **Resolução de Conflitos Direto na Master**:
|
||||
Se ao dar push houver rejeição ou divergência com o upstream remoto:
|
||||
- A IA executa `git -C <base_projeto>/../wiki pull --rebase origin master`.
|
||||
- A IA executa `git -C <modulo-wiki> pull --rebase origin master`.
|
||||
- Havendo conflitos de merge, a IA resolve as marcações diretamente na `master`, preservando a coerência da documentação dos 6 pilares.
|
||||
- Adiciona os arquivos resolvidos (`git -C <base_projeto>/../wiki add -A`), finaliza o rebase (`git -C <base_projeto>/../wiki rebase --continue` ou commit) e envia com `git push origin master`.
|
||||
- Adiciona os arquivos resolvidos (`git -C <modulo-wiki> add -A`), finaliza o rebase (`git -C <modulo-wiki> rebase --continue` ou commit) e envia com `git push origin master`.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -7,17 +7,18 @@ trigger: always_on
|
|||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Regra: Conteúdo de Regras de Negócio em `<base_projeto>/../wiki/dev/<modulo>/`
|
||||
# Regra: Conteúdo de Regras de Negócio em `<modulo-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 `<base_projeto>/../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 `<modulo-wiki>/dev/<modulo>/`.
|
||||
|
||||
> 💡 **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`).
|
||||
> 💡 **Aplicação VitePress (`<modulo-wiki>`, padrão: `<base_projeto>/../wiki`) e Resolução do Módulo**:
|
||||
> - O caminho da Wiki `<modulo-wiki>` **DEVE** ser obtido dinamicamente a partir do campo `modulo-wiki` em `memorias-ia/modulo.yml` (adotando compulsoriamente o fallback padrão `../wiki/` quando omitido ou não configurado).
|
||||
> - Na Wiki resolvida, `<modulo-wiki>/<modulo-id>/` é voltado ao acesso dos **usuários**, e `<modulo-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` ou `e-licencie-gov`).
|
||||
|
||||
Isso garante centralização, governança técnica e facilidade de consulta por desenvolvedores, arquitetos e agentes de IA.
|
||||
|
||||
|
|
@ -25,7 +26,8 @@ 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 `<base_projeto>/../wiki/dev/<modulo>/`.**
|
||||
**Todo o conteúdo detalhado de regras de negócio DEVE ficar em `<modulo-wiki>/dev/<modulo>/`.**
|
||||
|
||||
|
||||
Considera-se lógica não-trivial qualquer módulo que:
|
||||
- Possui 3 ou mais critérios de decisão distintos
|
||||
|
|
|
|||
|
|
@ -32,6 +32,9 @@ Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar
|
|||
4. **Registrar evidências e fechar sessão**:
|
||||
- Registrar comprovações visuais com `agent-browser screenshot <arquivo.png>`.
|
||||
- Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo.
|
||||
5. **Credenciais Canônicas de Teste (`modulo-acesso`)**:
|
||||
- Sempre que o teste exigir autenticação (login, sessão administrativa), o agente **DEVE OBRIGATORIAMENTE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml`**.
|
||||
- É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -45,18 +45,18 @@ find <modulo>-front/src -name "modal*.vue" -o -name "Modal*.vue" | while read vu
|
|||
done
|
||||
```
|
||||
|
||||
### 3. Pilar 3 — Wiki do Usuário (`<base_projeto>/../wiki/<modulo-id>/`)
|
||||
### 3. Pilar 3 — Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`)
|
||||
|
||||
```sh
|
||||
# Verificar se existe documentação de usuário do módulo
|
||||
ls -la <base_projeto>/../wiki/<modulo-id>/*.md 2>/dev/null || echo "WIKI DE USUÁRIO AUSENTE EM <base_projeto>/../wiki/<modulo-id>/"
|
||||
# Verificar se existe documentação de usuário do módulo (modulo-wiki com fallback para ../wiki)
|
||||
ls -la <modulo-wiki>/<modulo-id>/*.md 2>/dev/null || echo "WIKI DE USUÁRIO AUSENTE EM <modulo-wiki>/<modulo-id>/"
|
||||
```
|
||||
|
||||
### 4. Pilar 4 — Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo-id>/`)
|
||||
### 4. Pilar 4 — Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`)
|
||||
|
||||
```sh
|
||||
# Verificar se existe documentação de desenvolvimento, regras de negócio ({modulo}.regras-negocio.md) e ADRs
|
||||
ls -la <base_projeto>/../wiki/dev/<modulo-id>/*.md 2>/dev/null || echo "WIKI DEV AUSENTE EM <base_projeto>/../wiki/dev/<modulo-id>/"
|
||||
ls -la <modulo-wiki>/dev/<modulo-id>/*.md 2>/dev/null || echo "WIKI DEV AUSENTE EM <modulo-wiki>/dev/<modulo-id>/"
|
||||
```
|
||||
|
||||
### 5. Pilar 5 — Rota de Integração de IA (`/llm.md`)
|
||||
|
|
@ -71,8 +71,8 @@ rg "llm\.md" --include='*.ts' <modulo>-back/src/ -n || echo "ROTA /llm.md NÃO E
|
|||
```sh
|
||||
# 1. Verificar arquivo obrigatório modulo.yml e chaves
|
||||
if [ -f "memorias-ia/modulo.yml" ]; then
|
||||
for chave in modulo-id modulo-caminho modulo-descricao modulo-tipo; do
|
||||
grep -q "^$chave:" memorias-ia/modulo.yml || echo "CHAVE AUSENTE EM modulo.yml: $chave"
|
||||
for chave in modulo-id modulo-caminho modulo-descricao modulo-tipo modulo-acesso modulo-wiki; do
|
||||
grep -q "^$chave:" memorias-ia/modulo.yml || echo "CHAVE AUSENTE OU RECOMENDADA EM modulo.yml: $chave"
|
||||
done
|
||||
else
|
||||
echo "CRÍTICO: memorias-ia/modulo.yml AUSENTE"
|
||||
|
|
@ -92,12 +92,13 @@ ls -la memorias-ia/ 2>/dev/null || echo "DIRETÓRIO memorias-ia/ NÃO ENCONTRADO
|
|||
## Resumo dos 6 Pilares
|
||||
- **Código-fonte sem JSDoc de aplicação:** N
|
||||
- **Modais/Telas sem .ajuda.md co-localizado:** N
|
||||
- **Wiki de Usuário (<base_projeto>/../wiki/<modulo-id>/):** Presente / Ausente
|
||||
- **Wiki de Desenvolvimento (<base_projeto>/../wiki/dev/<modulo-id>/):** Presente / Ausente
|
||||
- **Wiki de Usuário (<modulo-wiki>/<modulo-id>/):** Presente / Ausente
|
||||
- **Wiki de Desenvolvimento (<modulo-wiki>/dev/<modulo-id>/):** Presente / Ausente
|
||||
- **Rota /llm.md no backend:** Configurada / Ausente
|
||||
- **Identidade em memorias-ia/modulo.yml:** Conforme / Ausente
|
||||
- **Registros em memorias-ia/:** N registros
|
||||
|
||||
|
||||
## Ações Recomendadas
|
||||
1. ...
|
||||
```
|
||||
|
|
|
|||
|
|
@ -28,13 +28,14 @@ O objetivo é garantir que **nenhuma decisão fique apenas na cabeça** ou perdi
|
|||
|
||||
## PASSO 1 — Obter Identidade do Módulo e Localizar o Diretório de ADRs
|
||||
|
||||
1. Ler `modulo-id` em `<base_projeto>/memorias-ia/modulo.yml` (ex: `e-licencie.sigma`).
|
||||
2. Convenção de diretório: `<base_projeto>/../wiki/dev/<modulo-id>/adrs/` (na Wiki de Desenvolvimento).
|
||||
1. Ler `modulo-id` e `modulo-wiki` em `<base_projeto>/memorias-ia/modulo.yml` (fallback de wiki: `../wiki/`).
|
||||
2. Convenção de diretório: `<modulo-wiki>/dev/<modulo-id>/adrs/` (na Wiki de Desenvolvimento).
|
||||
|
||||
```bash
|
||||
mkdir -p <base_projeto>/../wiki/dev/<modulo-id>/adrs
|
||||
mkdir -p <modulo-wiki>/dev/<modulo-id>/adrs
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## PASSO 2 — Criar o Arquivo ADR
|
||||
|
|
@ -153,7 +154,7 @@ Antes de considerar completo:
|
|||
- [ ] As consequências (positivas e negativas) estão claras?
|
||||
- [ ] Os pacotes impactados estão listados?
|
||||
- [ ] O status está definido (proposto/aceito)?
|
||||
- [ ] O ADR foi salvo em `<base_projeto>/../wiki/dev/<modulo-id>/adrs/`?
|
||||
- [ ] O ADR foi salvo em `<modulo-wiki>/dev/<modulo-id>/adrs/`?
|
||||
- [ ] A decisão foi registrada na memória em `<base_projeto>/memorias-ia/`?
|
||||
- [ ] Alguém de fora do contexto entenderia este ADR?
|
||||
|
||||
|
|
@ -163,4 +164,5 @@ Antes de considerar completo:
|
|||
|
||||
- Rule: `rules/ddd-documentacao-primeiro.md`
|
||||
- Workflow: `global/workflows/aprimora-ia.md`
|
||||
- Wiki de Desenvolvimento: `<base_projeto>/../wiki/dev/<modulo-id>/adrs/`
|
||||
- Wiki de Desenvolvimento: `<modulo-wiki>/dev/<modulo-id>/adrs/`
|
||||
|
||||
|
|
|
|||
|
|
@ -11,9 +11,9 @@ description: >
|
|||
|
||||
Use esta skill ao iniciar um novo módulo SaaS ou ao perceber que o agente não conhece o vocabulário e as regras do domínio que o módulo aborda.
|
||||
|
||||
Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, etc.). O repositório `<base_projeto>/../wiki` é uma **aplicação VitePress**, onde a base factual do domínio é estruturada em dois níveis de acesso:
|
||||
1. **Wiki do Usuário (`<base_projeto>/../wiki/<modulo-id>/`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
|
||||
2. **Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo-id>/`):** Aplicação VitePress com **acesso interno exclusivo da equipe de desenvolvimento e arquitetura** (arquitetura técnica, diagramas, modelos de banco, regras de negócio e ADRs).
|
||||
Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, etc.). O repositório `<modulo-wiki>` (configurado em `memorias-ia/modulo.yml`, com fallback padrão para `<base_projeto>/../wiki`) é uma **aplicação VitePress**, onde a base factual do domínio é estruturada em dois níveis de acesso:
|
||||
1. **Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
|
||||
2. **Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`):** Aplicação VitePress com **acesso interno exclusivo da equipe de desenvolvimento e arquitetura** (arquitetura técnica, diagramas, modelos de banco, regras de negócio e ADRs).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -24,14 +24,16 @@ Consultar obrigatoriamente `<base_projeto>/memorias-ia/modulo.yml` na raiz do pr
|
|||
- `modulo-caminho`: rota base na URL (ex: `/sigma/`)
|
||||
- `modulo-descricao`: escopo funcional e propósito do módulo
|
||||
- `modulo-tipo`: stack tecnológica e arquitetura
|
||||
- `modulo-wiki`: caminho relativo ou absoluto para a Wiki (fallback: `../wiki/`)
|
||||
|
||||
Os destinos canônicos da documentação na aplicação VitePress (`<base_projeto>/../wiki`) são:
|
||||
- **Wiki do Usuário:** `<base_projeto>/../wiki/<modulo-id>/`
|
||||
- **Wiki de Desenvolvimento:** `<base_projeto>/../wiki/dev/<modulo-id>/`
|
||||
Os destinos canônicos da documentação na aplicação VitePress (`<modulo-wiki>`) são:
|
||||
- **Wiki do Usuário:** `<modulo-wiki>/<modulo-id>/`
|
||||
- **Wiki de Desenvolvimento:** `<modulo-wiki>/dev/<modulo-id>/`
|
||||
|
||||
---
|
||||
|
||||
## PASSO 2 — Criar Documentação na Wiki do Usuário (`<base_projeto>/../wiki/<modulo-id>/`)
|
||||
## PASSO 2 — Criar Documentação na Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`)
|
||||
|
||||
|
||||
Estruturar o guia do usuário e conceitos de negócio em linguagem clara e acessível:
|
||||
|
||||
|
|
@ -55,7 +57,7 @@ Breve descrição do propósito do módulo para o gestor e operador.
|
|||
|
||||
---
|
||||
|
||||
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo>/`)
|
||||
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo>/`)
|
||||
|
||||
Estruturar a especificação técnica, modelos de banco e arquitetura:
|
||||
|
||||
|
|
@ -86,8 +88,9 @@ Estruturar a especificação técnica, modelos de banco e arquitetura:
|
|||
|
||||
## Checklist Final
|
||||
|
||||
- [ ] Documentação de usuário criada/atualizada em `<base_projeto>/../wiki/<modulo>/`?
|
||||
- [ ] Documentação técnica criada/atualizada em `<base_projeto>/../wiki/dev/<modulo>/`?
|
||||
- [ ] Documentação de usuário criada/atualizada em `<modulo-wiki>/<modulo>/`?
|
||||
- [ ] Documentação técnica criada/atualizada em `<modulo-wiki>/dev/<modulo>/`?
|
||||
|
||||
- [ ] Glossário com os termos centrais do domínio documentado?
|
||||
- [ ] Regras e entidades técnicas alinhadas com os schemas Zod do `*-comuns`?
|
||||
- [ ] Rota `/llm.md` no backend reflete o módulo?
|
||||
|
|
|
|||
|
|
@ -7,13 +7,13 @@ updatedAt: "2026-09-02"
|
|||
|
||||
# Workflow / Skill: Documentar Regras de Negócio de um Módulo
|
||||
|
||||
Use este workflow para criar ou atualizar o arquivo de regras de negócio de qualquer módulo TypeScript com lógica não-trivial, armazenado na **Wiki de Desenvolvimento** em `<base_projeto>/../wiki/dev/<modulo-id>/`.
|
||||
Use este workflow para criar ou atualizar o arquivo de regras de negócio de qualquer módulo TypeScript com lógica não-trivial, armazenado na **Wiki de Desenvolvimento** em `<modulo-wiki>/dev/<modulo-id>/`.
|
||||
|
||||
---
|
||||
|
||||
[1] Obter a identidade do módulo e ler o código TypeScript
|
||||
|
||||
1. Ler `modulo-id` em `<base_projeto>/memorias-ia/modulo.yml` (ex: `e-licencie.sigma`).
|
||||
1. Ler `modulo-id` e `modulo-wiki` em `<base_projeto>/memorias-ia/modulo.yml` (fallback de wiki: `../wiki/`).
|
||||
2. Identificar e anotar no código:
|
||||
- Nome do arquivo e localização exata no código
|
||||
- Funções exportadas e suas responsabilidades
|
||||
|
|
@ -28,7 +28,7 @@ Use este workflow para criar ou atualizar o arquivo de regras de negócio de qua
|
|||
[2] Verificar se já existe a documentação de regras na Wiki de Desenvolvimento
|
||||
|
||||
```bash
|
||||
ls <base_projeto>/../wiki/dev/<modulo-id>/*regras-negocio*.md 2>/dev/null
|
||||
ls <modulo-wiki>/dev/<modulo-id>/*regras-negocio*.md 2>/dev/null
|
||||
```
|
||||
|
||||
- **Existe** → ler e identificar o que está desatualizado → ir para o passo [4]
|
||||
|
|
@ -38,7 +38,7 @@ ls <base_projeto>/../wiki/dev/<modulo-id>/*regras-negocio*.md 2>/dev/null
|
|||
|
||||
[3] Criar o arquivo de regras na Wiki de Desenvolvimento
|
||||
|
||||
**Localização:** `<base_projeto>/../wiki/dev/<modulo-id>/{nome-do-modulo}.regras-negocio.md` (ou `<base_projeto>/../wiki/dev/<modulo-id>/regras-negocio/`).
|
||||
**Localização:** `<modulo-wiki>/dev/<modulo-id>/{nome-do-modulo}.regras-negocio.md` (ou `<modulo-wiki>/dev/<modulo-id>/regras-negocio/`).
|
||||
|
||||
Preencher com a estrutura padrão:
|
||||
- Contexto operacional
|
||||
|
|
@ -55,9 +55,10 @@ Preencher com a estrutura padrão:
|
|||
Garantir que a primeira linha útil do arquivo TypeScript seja:
|
||||
|
||||
```typescript
|
||||
// Regras de negócio: ver <base_projeto>/../wiki/dev/<modulo>/{modulo}.regras-negocio.md
|
||||
// Regras de negócio: ver <modulo-wiki>/dev/<modulo>/{modulo}.regras-negocio.md
|
||||
```
|
||||
|
||||
|
||||
Se já existia e está correto → sem mudança necessária.
|
||||
|
||||
---
|
||||
|
|
@ -100,7 +101,8 @@ Zero erros = concluído.
|
|||
|
||||
Se o módulo introduziu ou alterou arquitetura ou regras consolidadas do módulo:
|
||||
|
||||
- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `<base_projeto>/../wiki/dev/<modulo>/`.
|
||||
- Criar ou atualizar ADR em `<base_projeto>/../wiki/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
|
||||
- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `<modulo-wiki>/dev/<modulo>/`.
|
||||
- Criar ou atualizar ADR em `<modulo-wiki>/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
|
||||
- Registrar decisões e ações na memória em `<base_projeto>/memorias-ia/`.
|
||||
- **Sincronização Git:** Executar commit e push exclusivamente na Wiki (`git -C <base_projeto>/../wiki add -A && git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): regras de negócio" && git -C <base_projeto>/../wiki push`). Na aplicação (`<base_projeto>`), nunca mexer no git.
|
||||
- **Sincronização Git:** Executar commit e push exclusivamente na Wiki (`git -C <modulo-wiki> add -A && git -C <modulo-wiki> commit -m "docs(<modulo-id>): regras de negócio" && git -C <modulo-wiki> push`). Na aplicação (`<base_projeto>`), nunca comitar em master.
|
||||
|
||||
|
|
|
|||
|
|
@ -68,11 +68,12 @@ Utilize os modelos canônicos disponíveis em `.agent/DOCUMENTACAO/templates/`:
|
|||
| :--- | :--- | :--- |
|
||||
| **Pilar 1: Código** | `.ts`, `.vue`, `.js` | JSDoc no topo das funções |
|
||||
| **Pilar 2: Ajuda UI** | `*-front/src/.../{componente}.ajuda.md` | `DOCUMENTACAO/templates/ajuda-tela.md.template` |
|
||||
| **Pilar 3: Wiki Usuário** | `<base_projeto>/../wiki/<modulo-id>/index.md` | `DOCUMENTACAO/templates/modulo-dominio.md.template` |
|
||||
| **Pilar 4: Wiki Dev** | `<base_projeto>/../wiki/dev/<modulo-id>/` | `DOCUMENTACAO/templates/regra-negocio.md.template` e `adr.md.template` |
|
||||
| **Pilar 3: Wiki Usuário** | `<modulo-wiki>/<modulo-id>/index.md` | `DOCUMENTACAO/templates/modulo-dominio.md.template` |
|
||||
| **Pilar 4: Wiki Dev** | `<modulo-wiki>/dev/<modulo-id>/` | `DOCUMENTACAO/templates/regra-negocio.md.template` e `adr.md.template` |
|
||||
| **Pilar 5: IA (/llm.md)** | `GET <modulo-caminho>llm.md` | `DOCUMENTACAO/templates/contrato-api.md.template` |
|
||||
| **Pilar 6: Memórias IA** | `memorias-ia/sessao-*.md` | Frontmatter `type: session_memory` |
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Extensibilidade Local (`.agent-local/`) — Opcional
|
||||
|
|
|
|||
|
|
@ -133,6 +133,25 @@ agent-browser close
|
|||
|
||||
---
|
||||
|
||||
## 🔑 Autenticação e Credenciais Canônicas (`modulo-acesso`)
|
||||
|
||||
Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso`:
|
||||
|
||||
```bash
|
||||
# Extrair credenciais canônicas de teste de memorias-ia/modulo.yml
|
||||
USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}')
|
||||
SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}')
|
||||
|
||||
# Preenchimento determinístico no formulário de login
|
||||
agent-browser fill @e1 "$USUARIO"
|
||||
agent-browser fill @e2 "$SENHA"
|
||||
agent-browser click @e3
|
||||
```
|
||||
|
||||
> ⚠️ **Atenção:** Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste.
|
||||
|
||||
---
|
||||
|
||||
## Sessões Persistentes e Autenticação
|
||||
|
||||
Para fluxos que necessitam manter login ativo entre comandos:
|
||||
|
|
@ -144,6 +163,7 @@ agent-browser --session auth-test --restore open --headed http://localhost:8080/
|
|||
agent-browser session info --json
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skills Nativas do agent-browser
|
||||
|
|
|
|||
|
|
@ -15,10 +15,10 @@ NEGRITO="\033[1m"
|
|||
RESET="\033[0m"
|
||||
|
||||
# Identificar a raiz do projeto pai
|
||||
if [ -d "../memorias-ia" ] || [ -f "../package.json" ]; then
|
||||
ROOT_DIR=".."
|
||||
elif [ -d "memorias-ia" ] || [ -f "package.json" ]; then
|
||||
if [ -d "memorias-ia" ] || [ -f "memorias-ia/modulo.yml" ] || [ -f "package.json" ]; then
|
||||
ROOT_DIR="."
|
||||
elif [ -d "../memorias-ia" ] || [ -f "../memorias-ia/modulo.yml" ] || [ -f "../package.json" ]; then
|
||||
ROOT_DIR=".."
|
||||
else
|
||||
ROOT_DIR="."
|
||||
fi
|
||||
|
|
@ -71,6 +71,20 @@ if [ -f "$MODULO_YML" ]; then
|
|||
TOTAL_ERROS=$((TOTAL_ERROS + 1))
|
||||
fi
|
||||
|
||||
# Validar modulo-acesso (credenciais de teste para automação e QA)
|
||||
if grep -q "modulo-acesso:" "$MODULO_YML"; then
|
||||
echo -e " ${VERDE}✓${RESET} modulo-acesso: credenciais de teste configuradas."
|
||||
else
|
||||
echo -e " ${AMARELO}⚠${RESET} modulo-acesso: credenciais de teste não configuradas em modulo.yml."
|
||||
fi
|
||||
|
||||
# Resolver modulo-wiki (caminho da wiki com fallback mandatório para ../wiki)
|
||||
MODULO_WIKI=$(grep -E "^modulo-wiki:" "$MODULO_YML" | awk '{print $2}' || true)
|
||||
if [ -z "$MODULO_WIKI" ]; then
|
||||
MODULO_WIKI="../wiki"
|
||||
fi
|
||||
echo -e " ${VERDE}✓${RESET} modulo-wiki resolvido: ${NEGRITO}$MODULO_WIKI${RESET}"
|
||||
|
||||
# Validar memorias-ia/historico-acoes.md (Pilar 6 - Índice de Ações)
|
||||
HISTORICO_MD="$ROOT_DIR/memorias-ia/historico-acoes.md"
|
||||
if [ -f "$HISTORICO_MD" ]; then
|
||||
|
|
@ -89,11 +103,11 @@ fi
|
|||
# 2. Validar Wiki do Usuário (Pilar 3)
|
||||
echo -e "\n${NEGRITO}[2/6] Wiki do Usuário (Pilar 3)${RESET}"
|
||||
if [ -n "$MODULO_ID" ]; then
|
||||
WIKI_USER_DIR="$ROOT_DIR/../wiki/$MODULO_ID"
|
||||
WIKI_USER_DIR="$ROOT_DIR/$MODULO_WIKI/$MODULO_ID"
|
||||
if [ -d "$WIKI_USER_DIR" ]; then
|
||||
echo -e " ${VERDE}✓${RESET} Diretório encontrado em: <base_projeto>/../wiki/$MODULO_ID/"
|
||||
echo -e " ${VERDE}✓${RESET} Diretório encontrado em: $MODULO_WIKI/$MODULO_ID/"
|
||||
else
|
||||
echo -e " ${AMARELO}⚠${RESET} Diretório <base_projeto>/../wiki/$MODULO_ID/ não encontrado."
|
||||
echo -e " ${AMARELO}⚠${RESET} Diretório $MODULO_WIKI/$MODULO_ID/ não encontrado."
|
||||
TOTAL_AVISOS=$((TOTAL_AVISOS + 1))
|
||||
fi
|
||||
else
|
||||
|
|
@ -103,11 +117,11 @@ fi
|
|||
# 3. Validar Wiki de Desenvolvimento (Pilar 4)
|
||||
echo -e "\n${NEGRITO}[3/6] Wiki de Desenvolvimento (Pilar 4)${RESET}"
|
||||
if [ -n "$MODULO_ID" ]; then
|
||||
WIKI_DEV_DIR="$ROOT_DIR/../wiki/dev/$MODULO_ID"
|
||||
WIKI_DEV_DIR="$ROOT_DIR/$MODULO_WIKI/dev/$MODULO_ID"
|
||||
if [ -d "$WIKI_DEV_DIR" ]; then
|
||||
echo -e " ${VERDE}✓${RESET} Diretório encontrado em: <base_projeto>/../wiki/dev/$MODULO_ID/"
|
||||
echo -e " ${VERDE}✓${RESET} Diretório encontrado em: $MODULO_WIKI/dev/$MODULO_ID/"
|
||||
else
|
||||
echo -e " ${AMARELO}⚠${RESET} Diretório <base_projeto>/../wiki/dev/$MODULO_ID/ não encontrado."
|
||||
echo -e " ${AMARELO}⚠${RESET} Diretório $MODULO_WIKI/dev/$MODULO_ID/ não encontrado."
|
||||
TOTAL_AVISOS=$((TOTAL_AVISOS + 1))
|
||||
fi
|
||||
else
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue