106 lines
6.2 KiB
Markdown
106 lines
6.2 KiB
Markdown
---
|
|
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, modulo-acesso, modulo-wiki).
|
|
scope: global
|
|
trigger: always_on
|
|
priority: critica
|
|
updatedAt: "2026-10-14"
|
|
---
|
|
|
|
# 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, sua stack técnica, suas credenciais de teste e o caminho da sua Wiki, 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 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 para autenticação em testes (agent-browser, E2E, QA)
|
|
# Formato Simples (aplicação com contexto único de acesso):
|
|
modulo-acesso:
|
|
usuario: <login-ou-email>
|
|
senha: <senha-de-teste>
|
|
|
|
# Ou Formato Multi-Contexto (quando a aplicação possui acessos distintos - evita mistura de tokens):
|
|
# modulo-acesso:
|
|
# interno:
|
|
# usuario: <login-operador>
|
|
# senha: <senha-operador>
|
|
# cliente:
|
|
# usuario: <login-cliente>
|
|
# senha: <senha-cliente>
|
|
# externo:
|
|
# usuario: <login-cidadao>
|
|
# senha: <senha-cidadao>
|
|
# anonimo: null # acesso público/deslogado
|
|
|
|
# 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
|
|
|
|
| Campo | Tipo | Descrição | Exemplo |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki, referências de regras de negócio e prefixo da sessão isolada no `agent-browser` (`--session <modulo-id>_<contexto?>`). | `nome-do-modulo` |
|
|
| **`modulo-caminho`** | `string` | Rota / prefixo utilizado na URL e navegação do módulo (base route para front, proxy e endpoints). | `/modulo/` ou `/` |
|
|
| **`modulo-descricao`** | `string` | Descrição textual do propósito funcional e escopo de negócio do módulo. | `Módulo para gestão operacional e ambiental` |
|
|
| **`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`) ou organizadas por contexto (`interno`, `externo`, `cliente`, `anonimo`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`), prevenindo mistura de tokens. | `{ usuario: "admin@exemplo.com", senha: "123" }` ou subchaves de contexto |
|
|
| **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `../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 (`<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/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session <modulo-id>_<contexto?>`)**;
|
|
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 as credenciais do contexto específico (`interno`, `externo`, `cliente`, etc.) ou credenciais diretas de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística sem contaminação de cookies/tokens entre perfis;
|
|
5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou escrita na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia;
|
|
6. **Sincronização do Submódulo (`.agent`) e Verificação Diária do Bun**: Ao iniciar qualquer sessão ou interação no projeto hospedeiro, o agente DEVE assegurar que o submódulo `.agent` esteja atualizado com a branch `master` remota executando `git submodule update --init --recursive --remote` e que o runtime Bun seja verificado uma vez por dia com `bun upgrade --stable` (automatizado via `.agent/scripts/atualizar-submodulo.sh`).
|
|
|
|
👉 **O agente DEVE obrigatoriamente ler e extrair as informações de `memorias-ia/modulo.yml`.**
|
|
|
|
---
|
|
|
|
## Proibições
|
|
|
|
- **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`.
|
|
|
|
---
|
|
|
|
## Referências
|
|
|
|
- Rule: `global/rules/atualizacao-submodulo-sessao.md`
|
|
- 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`
|