publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
.agent/global/skills/documentar-dominio-modulo/SKILL.md

4.9 KiB
Raw Blame History

name scope updatedAt description
documentar-dominio-modulo global 2026-10-14 Guia para documentar o domínio científico/técnico de cada módulo nas wikis de usuário (<modulo-wiki>/<modulo-id>/) e de desenvolvimento (<modulo-wiki>/dev/<modulo-id>/).

Skill: Documentar Domínio de um Módulo

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 operacional ou ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, atendimento, etc.). O repositório <modulo-wiki> (configurado em memorias-ia/modulo.yml, com fallback padrão para ../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).

PASSO 1 — Identificar a Identidade e Domínio do Módulo via memorias-ia/modulo.yml

Consultar obrigatoriamente <base_projeto>/memorias-ia/modulo.yml na raiz do projeto pai:

  • modulo-id: identificador canônico do módulo
  • modulo-caminho: rota base na URL
  • 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 (<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 (<modulo-wiki>/<modulo-id>/)

Estruturar o guia do usuário e conceitos de negócio em linguagem clara e acessível:

# [Nome do Módulo] — Guia do Usuário

## Visão Geral
Breve descrição do propósito do módulo para o gestor e operador.

## Glossário do Domínio
| Termo | Definição | Sigla |
|---|---|---|
| Ponto de Monitoramento | Local físico onde são coletadas amostras | PM |
| Parâmetro Ambiental | Variável físico-química monitorada (ex: DBO, DQO) | — |

## Fluxos Operacionais do Usuário
1. Cadastro de entidades base.
2. Lançamento e acompanhamento de registros.
3. Emissão de relatórios e acompanhamento de conformidade.

Inclusão de Imagens, Diagramas e Manuais em PDF

Para enriquecer a Wiki com capturas de tela ou manuais, envie os arquivos para o MinIO Paiol antes de incluí-los no Markdown:

./.agent/scripts/upload-paiol-wiki.sh <caminho-do-arquivo> <slug-funcionalidade>

Utilize exclusivamente a URL pública gerada (https://paiol.idz.one/wiki/...) no Markdown. Nunca comite arquivos binários no Git da Wiki.

PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (<modulo-wiki>/dev/<modulo-id>/)

Estruturar a especificação técnica, modelos de banco e arquitetura:

# [Nome do Módulo] — Arquitetura e Engenharia

## Modelo de Dados e Entidades
- **Tabelas principais:** `<modulo>_entidade_a`, `<modulo>_entidade_b`, `<modulo>_parametros`
- **Schemas Zod canônicos:** `zEntidadeCriar`, `zRegistroAtualizar` em `<modulo>-comuns`

## Processamento Assíncrono e Filas (BullMQ)
- **Fila `processar_agenda`:** Recalcula status e prazos operacionais.

## Rotas e Integração de IA
- **Rota `/llm.md`:** Disponibiliza catálogo dinâmico de endpoints e contratos.

PASSO 4 — Conectar com Código e UI

  1. Verificar se mensagens e labels na UI seguem o vocabulário definido (rule mensagens-usuario).
  2. Verificar se componentes e modais possuem {componente}.ajuda.md co-localizado (skill adicionar-ajuda).
  3. Garantir que funções centrais e serviços possuem comentários claros de aplicação (rule jsdoc-padrao).
  4. Assegurar que regras com 3+ critérios possuam .regras-negocio.md na Wiki de Desenvolvimento (rule regras-negocio-md).

Checklist Final

  • Documentação de usuário criada/atualizada em <modulo-wiki>/<modulo-id>/?
  • Documentação técnica criada/atualizada em <modulo-wiki>/dev/<modulo-id>/?
  • Glossário com os termos centrais do domínio documentado?
  • Regras e entidades técnicas alinhadas com os schemas Zod do <modulo>-comuns?
  • Rota /llm.md no backend reflete o módulo?
  • Imagens, manuais e anexos hospedados no MinIO Paiol (sem binários no Git da Wiki)?

Referências

  • Rule: rules/ddd-documentacao-primeiro.md
  • Rule: rules/identidade-modulo.md
  • Rule: rules/jsdoc-padrao.md
  • Rule: rules/regras-negocio-md.md
  • Skill: skills/adicionar-ajuda/SKILL.md