.agent/rules/identidade-modulo.md

type	name	description	scope	trigger	priority	updatedAt
rule	identidade-modulo	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).	global	always_on	critica	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:

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