chore(agent): remover permissoes de commit da IA no projeto e wiki (apenas sugerir texto) e manter push automatico exclusivo no .agent
This commit is contained in:
parent
212d2578f4
commit
26a4f98dab
116 changed files with 1162 additions and 1315 deletions
|
|
@ -29,10 +29,10 @@ O conhecimento do agente está organizado em **três tipos de artefatos**, cada
|
|||
|
||||
> 🧩 **Polimorfismo do `.agent` e Identidade por Projeto**:
|
||||
> O `.agent` é polimórfico e genérico. A personalização e identidade de cada projeto específico é mantida fora do `.agent`:
|
||||
> - `./memorias-ia/modulo.yml` (na raiz do projeto pai): Arquivo mandatório com `modulo-id`, `modulo-caminho`, `modulo-descricao` e `modulo-tipo`.
|
||||
> - `./memorias-ia/modulo.yml` (na raiz do projeto pai): Arquivo mandatório com `modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`, `modulo-acesso` e `modulo-wiki`.
|
||||
> - `./memorias-ia/`: Registros de ações, sessões e decisões da IA.
|
||||
> - `<base_projeto>/../wiki/<modulo-id>/`: Documentação funcional com acesso dos usuários na aplicação VitePress.
|
||||
> - `<base_projeto>/../wiki/dev/<modulo-id>/`: Documentação técnica com acesso interno dev na aplicação VitePress.
|
||||
> - `<modulo-wiki>/<modulo-id>/`: Documentação funcional com acesso dos usuários na aplicação VitePress (fallback de wiki: `../wiki/`).
|
||||
> - `<modulo-wiki>/dev/<modulo-id>/`: Documentação técnica com acesso interno dev na aplicação VitePress.
|
||||
|
||||
### Diferenças entre os artefatos
|
||||
|
||||
|
|
|
|||
|
|
@ -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. ...
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
---
|
||||
name: doc
|
||||
description: Alias rápido para /documentacao - acionar o Agente de Documentação & Memória com versionamento automático na Wiki
|
||||
description: Alias rápido para /documentacao - acionar o Agente de Documentação & Memória nos 6 pilares com sugestão de mensagem de commit para o operador humano
|
||||
scope: global
|
||||
updatedAt: "2026-09-05"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Skill: /doc (Alias para /documentacao)
|
||||
|
|
@ -32,19 +32,18 @@ Ao documentar a sessão (seja via `/doc` ou `/documentacao`):
|
|||
```
|
||||
|
||||
|
||||
## 🔄 Versionamento Git Obrigatório da Wiki (`<base_projeto>/../wiki`)
|
||||
## 💬 Sugestão de Mensagem de Commit (Commit Exclusivo por Humano)
|
||||
|
||||
Sempre que a documentação na Wiki (Pilares 3 e 4) for alterada ou criada:
|
||||
- O agente **DEVE obrigatoriamente executar commit, push e resolução de conflitos** das alterações diretamente na branch `master` do repositório da Wiki:
|
||||
```bash
|
||||
git -C <base_projeto>/../wiki add -A
|
||||
git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): sincronizar documentação"
|
||||
git -C <base_projeto>/../wiki pull --rebase origin master # se houver divergência, resolve na master
|
||||
git -C <base_projeto>/../wiki push origin master
|
||||
Sempre que documentações na aplicação (`<base_projeto>`) ou na Wiki (`<modulo-wiki>`, padrão `../wiki`) forem criadas ou alteradas:
|
||||
- O agente **NUNCA executa `git commit` ou `git push`** — o commit deve ser feito **exclusivamente pelo operador humano** (ver `rules/proibido-commit-ia.md`).
|
||||
- Ao concluir, o agente apresenta a sugestão de mensagem de commit pronta para o humano copiar:
|
||||
```markdown
|
||||
💬 **Sugestão de Commit (Wiki / Aplicação):**
|
||||
`docs(<modulo-id>): <descrição sucinta das alterações>`
|
||||
```
|
||||
|
||||
> 🔒 **Fronteira Git e Salvaguarda de Master:**
|
||||
> Na Wiki, commit, push e resolução de conflitos ocorrem diretamente na branch `master`. Na aplicação principal (`<base_projeto>`), a IA pode realizar commits apenas em branches de trabalho, sendo **terminantemente proibido comitar na branch `master`** (se estiver em `master`, deve criar uma nova branch; ver `rules/proibido-commit-ia.md`).
|
||||
> 🔒 **Fronteira Git:**
|
||||
> Apenas o submódulo `.agent` pode receber commit/push de forma automática pela IA. Tanto na aplicação principal (`<base_projeto>`) quanto na Wiki (`<modulo-wiki>`), a IA apenas sugere o texto do commit ao operador humano.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
---
|
||||
name: documentacao
|
||||
description: Acionar o Agente de Documentação & Memória para documentar o contexto da conversa ou gerar artefatos nos 6 pilares canônicos com versionamento automático na Wiki
|
||||
description: Acionar o Agente de Documentação & Memória para documentar o contexto da conversa ou gerar artefatos nos 6 pilares canônicos com sugestão de mensagem de commit para o operador humano
|
||||
scope: global
|
||||
updatedAt: "2026-09-05"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Skill / Workflow: /documentacao
|
||||
|
|
@ -21,14 +21,10 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
|
|||
4. **Pilar 4 (Wiki de Desenvolvimento):** Documenta regras de negócio (`{modulo}.regras-negocio.md`), modelos e ADRs em `<base_projeto>/../wiki/dev/<modulo>/` (aplicação VitePress com acesso interno dev).
|
||||
5. **Pilar 5 (Rota IA):** Assegura que novos schemas e rotas estejam refletidos na rota `/llm.md`.
|
||||
6. **Pilar 6 (Memória IA):** Registra o relatório completo da sessão no arquivo individual `<base_projeto>/memorias-ia/sessao-AAAA-MM-DD-slug.md` e atualiza o índice central `<base_projeto>/memorias-ia/historico-acoes.md` adicionando a linha correspondente na tabela com as colunas: `Data | Memória / Ação | Arquivo Memoria | Citações no Código-Fonte`.
|
||||
7. **Sincronização Git da Wiki (Obrigatório e Exclusivo):**
|
||||
- Se houver arquivos novos ou alterados em `<base_projeto>/../wiki/`:
|
||||
```bash
|
||||
git -C <base_projeto>/../wiki add -A
|
||||
git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): sincronizar documentação [contexto]"
|
||||
git -C <base_projeto>/../wiki push
|
||||
```
|
||||
- **Trava de Segurança da Aplicação:** Na aplicação (`<base_projeto>`), o agente **NÃO pode mexer no git** (o versionamento do código-fonte da aplicação permanece sob controle humano exclusivo).
|
||||
7. **Sugestão de Mensagem de Commit (Commit Exclusivo por Humano):**
|
||||
- O agente **NUNCA executa `git commit` ou `git push`** na aplicação (`<base_projeto>`) nem na Wiki (`<modulo-wiki>`).
|
||||
- Ao finalizar, apresenta ao operador humano a sugestão de mensagem de commit pronta para copiar:
|
||||
`💬 Sugestão de Commit: docs(<modulo-id>): <descrição sucinta das alterações>`
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -57,20 +53,20 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
|
|||
# Criar ajuda contextual modalX.ajuda.md para modal/tela
|
||||
/documentacao ajuda <caminho/modalX.vue>
|
||||
|
||||
# Documentar domínio na Wiki do Usuário (VitePress) + commit/push na wiki
|
||||
# Documentar domínio na Wiki do Usuário (VitePress) + sugestão de commit
|
||||
/documentacao wiki-usuario <modulo>
|
||||
|
||||
# Documentar regras de negócio na Wiki Dev (VitePress) + commit/push na wiki
|
||||
# Documentar regras de negócio na Wiki Dev (VitePress) + sugestão de commit
|
||||
/documentacao regras <caminho/servico.ts>
|
||||
|
||||
# Criar um ADR na Wiki Dev + commit/push na wiki
|
||||
# Criar um ADR na Wiki Dev + sugestão de commit
|
||||
/documentacao adr "<Título da Decisão>"
|
||||
|
||||
# Upload de arquivo/mídia (PDF, imagem, vídeo) para o MinIO Paiol com link pronto para a Wiki
|
||||
/documentacao upload <caminho/arquivo.ext> <slug-funcionalidade>
|
||||
```
|
||||
|
||||
*Nota:* Qualquer comando que crie ou modifique arquivos na Wiki (`<base_projeto>/../wiki`) deve finalizar executando `git add`, `git commit`, `git pull --rebase` (resolvendo conflitos na master se houver) e `git push` diretamente na branch `master` dentro de `../wiki`.
|
||||
*Nota:* Qualquer comando que crie ou modifique arquivos na aplicação ou na Wiki (`<base_projeto>/../wiki`) **não deve executar `git commit` nem `git push`**, apresentando ao final apenas a sugestão de mensagem de commit para o operador humano.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -80,5 +76,5 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
|
|||
2. **Linguagem acessível no usuário:** Sem termos técnicos de TI na Wiki do Usuário ou em `.ajuda.md`.
|
||||
3. **JSDoc de Aplicação:** Explicar a utilidade prática no sistema, não apenas repetir tipos.
|
||||
4. **Polimorfismo:** O `.agent` é genérico; personalizações ficam em `./memorias-ia/` e `<base_projeto>/../wiki/`.
|
||||
5. **Fronteira Git e Gestão em Master na Wiki:** Toda atualização em `<base_projeto>/../wiki` DEVE ser commitada, sincronizada com resolução de conflitos e enviada via `git push` diretamente na branch `master` de `../wiki`. Na aplicação principal (`<base_projeto>`), a IA pode comitar apenas em branches de trabalho, sendo proibido comitar na `master` (ver `rules/proibido-commit-ia.md`).
|
||||
5. **Fronteira Git (Commit Exclusivo por Humano):** É proibido à IA executar `git commit` ou `git push` na aplicação principal (`<base_projeto>`) e na Wiki (`<modulo-wiki>`). A IA deve apenas sugerir o texto do commit (`docs(<modulo-id>): ...`) para o operador humano. Apenas o submódulo `.agent` pode receber commit/push automático (ver `rules/proibido-commit-ia.md`).
|
||||
6. **Mídias e Binários no MinIO Paiol:** Arquivos pesados (PDFs, vídeos, imagens e anexos) NUNCA devem ser commitados no Git da Wiki; envie sempre para o MinIO Paiol via `./.agent/scripts/upload-paiol-wiki.sh` e versione apenas a URL pública nos arquivos Markdown.
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ name: documentar-decisao-tecnica
|
|||
scope: global
|
||||
updatedAt: "2026-09-01"
|
||||
description: >
|
||||
Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records) na Wiki de Desenvolvimento (<base_projeto>/../wiki/dev/<modulo-id>/adrs/).
|
||||
Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records) na Wiki de Desenvolvimento (<modulo-wiki>/dev/<modulo-id>/adrs/).
|
||||
---
|
||||
|
||||
# Skill: Documentar Decisão Técnica (ADR)
|
||||
|
|
@ -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
|
||||
|
|
@ -43,7 +44,7 @@ Nomenclatura: `NNN-titulo-em-kebab-case.md`
|
|||
|
||||
```bash
|
||||
# Encontrar o próximo número
|
||||
NEXT=$(ls .docs/adrs/*.md 2>/dev/null | wc -l | xargs -I{} expr {} + 1)
|
||||
NEXT=$(ls <modulo-wiki>/dev/<modulo-id>/adrs/*.md 2>/dev/null | wc -l | xargs -I{} expr {} + 1)
|
||||
NEXT=$(printf "%03d" $NEXT)
|
||||
echo "Próximo ADR: $NEXT"
|
||||
```
|
||||
|
|
@ -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/`
|
||||
|
||||
|
|
|
|||
|
|
@ -1,37 +1,38 @@
|
|||
---
|
||||
name: documentar-dominio-modulo
|
||||
scope: global
|
||||
updatedAt: "2026-09-01"
|
||||
updatedAt: "2026-10-14"
|
||||
description: >
|
||||
Guia para documentar o domínio científico/técnico de cada módulo nas wikis
|
||||
de usuário (<base_projeto>/../wiki/<modulo-id>/) e de desenvolvimento (<base_projeto>/../wiki/dev/<modulo-id>/).
|
||||
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 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 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 do módulo (ex: `e-licencie.sigma`)
|
||||
- `modulo-caminho`: rota base na URL (ex: `/sigma/`)
|
||||
- `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 (`<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:
|
||||
|
||||
|
|
@ -48,8 +49,8 @@ Breve descrição do propósito do módulo para o gestor e operador.
|
|||
| Parâmetro Ambiental | Variável físico-química monitorada (ex: DBO, DQO) | — |
|
||||
|
||||
## Fluxos Operacionais do Usuário
|
||||
1. Cadastro de pontos de monitoramento.
|
||||
2. Lançamento e importação de medições.
|
||||
1. Cadastro de entidades base.
|
||||
2. Lançamento e acompanhamento de registros.
|
||||
3. Emissão de relatórios e acompanhamento de conformidade.
|
||||
```
|
||||
|
||||
|
|
@ -62,7 +63,7 @@ Utilize exclusivamente a URL pública gerada (`https://paiol.idz.one/wiki/...`)
|
|||
|
||||
---
|
||||
|
||||
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo>/`)
|
||||
## 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:
|
||||
|
||||
|
|
@ -70,11 +71,11 @@ 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:** `sigma_pontos`, `sigma_medicoes`, `sigma_parametros`
|
||||
- **Schemas Zod canônicos:** `zPontoCriar`, `zMedicaoRegistrar` em `*-comuns`
|
||||
- **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 `calcular_agenda`:** Recalcula status e prazos de monitoramento.
|
||||
- **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.
|
||||
|
|
@ -85,18 +86,18 @@ Estruturar a especificação técnica, modelos de banco e arquitetura:
|
|||
## 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 Vue possuem `modalX.ajuda.md` co-localizado (skill `adicionar-ajuda`).
|
||||
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` co-localizado (rule `regras-negocio-md`).
|
||||
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>/`?
|
||||
- [ ] Documentação técnica criada/atualizada em `<modulo-wiki>/dev/<modulo>/`?
|
||||
- [ ] 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 `*-comuns`?
|
||||
- [ ] 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)?
|
||||
|
||||
|
|
@ -105,7 +106,7 @@ Estruturar a especificação técnica, modelos de banco e arquitetura:
|
|||
## 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`
|
||||
|
||||
|
|
|
|||
|
|
@ -1,19 +1,19 @@
|
|||
---
|
||||
name: documentar-regras-negocio
|
||||
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (<base_projeto>/../wiki/dev/<modulo-id>/) e garantir consistência com o código TypeScript.
|
||||
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (<modulo-wiki>/dev/<modulo-id>/) e garantir consistência com o código TypeScript.
|
||||
scope: global
|
||||
updatedAt: "2026-09-02"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# 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.
|
||||
- **Sugestão de Commit (Sem Executar Commit):** Nunca executar `git commit` ou `git push` na aplicação (`<base_projeto>`) nem na Wiki (`<modulo-wiki>`), pois o commit é exclusivo de humano (ver `rules/proibido-commit-ia.md`). Apresentar ao operador a sugestão de mensagem: `docs(<modulo-id>): regras de negócio`.
|
||||
|
||||
|
|
|
|||
|
|
@ -42,18 +42,23 @@ git submodule update --init --recursive --remote
|
|||
|
||||
## PASSO 2 — Configurar a Identidade do Módulo (`memorias-ia/modulo.yml`)
|
||||
|
||||
1. Criar a pasta de memórias e copiar o template oficial:
|
||||
1. Criar a pasta de memórias e copiar os templates oficiais:
|
||||
```bash
|
||||
mkdir -p memorias-ia
|
||||
cp .agent/DOCUMENTACAO/templates/modulo.yml.template memorias-ia/modulo.yml
|
||||
cp .agent/DOCUMENTACAO/templates/historico-acoes.md.template memorias-ia/historico-acoes.md
|
||||
```
|
||||
|
||||
2. Editar `memorias-ia/modulo.yml` preenchendo os 4 campos obrigatórios:
|
||||
2. Editar `memorias-ia/modulo.yml` preenchendo os campos canônicos:
|
||||
```yaml
|
||||
modulo-id: nome-do-modulo.submodulo # ex: e-licencie.qualifica
|
||||
modulo-caminho: /qualifica/ # rota base na URL
|
||||
modulo-descricao: Módulo para gestão de conformidade de fornecedores
|
||||
modulo-id: nome-do-modulo
|
||||
modulo-caminho: /modulo/
|
||||
modulo-descricao: Descrição funcional e escopo de negócio do módulo
|
||||
modulo-tipo: aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres
|
||||
modulo-acesso:
|
||||
usuario: usuario@exemplo.com.br
|
||||
senha: "123"
|
||||
modulo-wiki: ../wiki
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -76,11 +81,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
|
||||
|
|
|
|||
|
|
@ -57,7 +57,7 @@ O Orquestrador Líder decompõe a especificação técnica do plano e distribui
|
|||
| **`@ux`** *(UX Specialist)* | `*-front` (Interface & Heurísticas) | Aplicação das Heurísticas de Nielsen: visibilidade do estado (spinners, loading, feedback imediato), clareza cognitiva, prevenção de erros e mensagens amigáveis ao usuário. |
|
||||
| **`@refatorar`** *(Clean Code Specialist)* | Todo o código alterado | Governança estrita das 12 regras de Código Limpo: garantia do **limite de 250 linhas por arquivo**, eliminação de code smells, modularidade e Dispatch Tables. |
|
||||
| **`@testes`** *(QA & Automation)* | Checagens e Validação E2E | Tipagem (`bun run typecheck` / `tsc --noEmit`), linter (`biome check --write`), governança (`sh .agent/verificar-linhas.sh`) e testes de interface visual via `agent-browser --session <modulo>_<contexto?> --headed`. |
|
||||
| **`@documentacao`** *(Memory & Docs)* | `memorias-ia/`, `wiki/` | Registro de sessão no Pilar 6 (`memorias-ia/sessao-*.md`), indexação no `historico-acoes.md`, atualização de regras técnicas na Wiki de Dev (`wiki/dev/<modulo>/`). |
|
||||
| **`@documentacao`** *(Memory & Docs)* | `memorias-ia/`, `<modulo-wiki>/` | Registro de sessão no Pilar 6 (`memorias-ia/sessao-*.md`), indexação no `historico-acoes.md`, atualização de regras técnicas na Wiki de Dev (`<modulo-wiki>/dev/<modulo-id>/`). |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -157,10 +157,11 @@ Ao atingir 100% de conformidade com todos os critérios do plano:
|
|||
4. **Memória do Projeto (Pilar 6 - @documentacao):**
|
||||
- Criar `memorias-ia/sessao-AAAA-MM-DD-<slug>.md`.
|
||||
- Indexar no `memorias-ia/historico-acoes.md`.
|
||||
5. **Staging e Commit Semântico:**
|
||||
- Executar `git add <arquivos>` e `git status`.
|
||||
- Inspecionar a branch atual com `git branch --show-current`: se estiver em `master` (ou `main`), criar e alternar para uma nova branch semântica (`git checkout -b <tipo>/<slug-plano>`) — **NUNCA comitar diretamente em `master`** (ver `rules/proibido-commit-ia.md`).
|
||||
- Executar o `git commit` semântico na branch de trabalho (`git commit -m "<tipo>(<escopo>): <descrição>"`).
|
||||
5. **Sugestão de Mensagem de Commit (Sem Executar Commit):**
|
||||
- Inspecionar os arquivos modificados com `git status --short`.
|
||||
- **NUNCA executar `git commit` ou `git push`** no projeto ou na Wiki — o commit é exclusivo do operador humano (ver `rules/proibido-commit-ia.md`).
|
||||
- Apresentar ao operador humano a sugestão de mensagem de commit no padrão Conventional Commits pronta para copiar:
|
||||
`💬 Sugestão de Commit: <tipo>(<escopo>): <descrição>`
|
||||
6. **Notificação no Sistema Operacional (Linux & macOS):**
|
||||
- Disparar notificação sonora e visual no SO via script `.agent/notificar.sh`:
|
||||
`sh .agent/notificar.sh "Plano Concluído" "<Nome ou Título do Plano>" sucesso`
|
||||
|
|
|
|||
|
|
@ -104,10 +104,10 @@ Para cada item do plano, em ordem:
|
|||
**Agente:** `@refatorar` → `@documentacao`
|
||||
|
||||
- Atualizar JSDoc se interfaces mudaram
|
||||
- Registrar decisão em `.regras-negocio.md` se refatoração foi significativa
|
||||
- Registrar decisão e regras na Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`) se a refatoração foi significativa
|
||||
- Informar `@documentacao` sobre mudanças estruturais
|
||||
|
||||
**Formato do commit:**
|
||||
**Sugestão de texto do commit (para o operador humano):**
|
||||
```
|
||||
refactor(<módulo>): <técnica aplicada>
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue