.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-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, 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 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

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 identificador mandatório de sessão isolada no agent-browser (--session <modulo-id>).	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
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 (<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>);
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.

---

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/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