aplimoramento de agent
This commit is contained in:
parent
b361f25955
commit
f597436be3
83 changed files with 1312 additions and 574 deletions
|
|
@ -27,11 +27,12 @@ O conhecimento do agente está organizado em **três tipos de artefatos**, cada
|
|||
| **Skills** | `.agent/skills/` | `.agent/skills/` | Guias operacionais completos e reutilizáveis para tarefas complexas recorrentes |
|
||||
| **Memória das Ações da IA** | — | `<base_projeto>/memorias-ia/` | Registros de sessões, otimizações dos agentes, decisões e relatórios da IA (raiz do pai) |
|
||||
|
||||
> 🧩 **Polimorfismo do `.agent` e Personalização por Projeto**:
|
||||
> O `.agent` é polimórfico e genérico. A personalização de cada projeto específico é mantida fora do `.agent`:
|
||||
> - `./memorias-ia/` (na raiz do projeto pai): Registros de ações, sessões e decisões da IA.
|
||||
> - `../../wiki/<modulo>/`: Documentação funcional com acesso dos usuários na aplicação VitePress.
|
||||
> - `../../wiki/dev/<modulo>/`: Documentação técnica com acesso interno dev na aplicação VitePress.
|
||||
> 🧩 **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/`: 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.
|
||||
|
||||
### Diferenças entre os artefatos
|
||||
|
||||
|
|
|
|||
|
|
@ -16,9 +16,9 @@ Este workflow gera uma descrição comercial de funcionalidades ou do sistema co
|
|||
|
||||
## Passos
|
||||
|
||||
### 1. Identificar as funcionalidades solicitadas
|
||||
### 1. Identificar as funcionalidades e contexto do módulo
|
||||
|
||||
Perguntar ao usuário quais módulos ou funcionalidades devem ser descritos. Se o pedido for genérico ("descreva o sistema"), listar os módulos principais do projeto e confirmar o escopo antes de redigir.
|
||||
Consultar `<base_projeto>/memorias-ia/modulo.yml` para obter `modulo-descricao`, `modulo-tipo` e `modulo-id`. Perguntar ao usuário quais módulos ou funcionalidades devem ser descritos. Se o pedido for genérico ("descreva o sistema"), usar o escopo oficial de `memorias-ia/modulo.yml` e confirmar antes de redigir.
|
||||
|
||||
### 2. Levantar contexto real de cada funcionalidade
|
||||
|
||||
|
|
|
|||
|
|
@ -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 (`../../wiki/<modulo>/`)
|
||||
### 3. Pilar 3 — Wiki do Usuário (`<base_projeto>/../wiki/<modulo-id>/`)
|
||||
|
||||
```sh
|
||||
# Verificar se existe documentação de usuário do módulo
|
||||
ls -la ../../wiki/<modulo>/*.md 2>/dev/null || echo "WIKI DE USUÁRIO AUSENTE EM ../../wiki/<modulo>/"
|
||||
ls -la <base_projeto>/../wiki/<modulo-id>/*.md 2>/dev/null || echo "WIKI DE USUÁRIO AUSENTE EM <base_projeto>/../wiki/<modulo-id>/"
|
||||
```
|
||||
|
||||
### 4. Pilar 4 — Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`)
|
||||
### 4. Pilar 4 — Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo-id>/`)
|
||||
|
||||
```sh
|
||||
# Verificar se existe documentação de desenvolvimento, regras de negócio ({modulo}.regras-negocio.md) e ADRs
|
||||
ls -la ../../wiki/dev/<modulo>/*.md 2>/dev/null || echo "WIKI DEV AUSENTE EM ../../wiki/dev/<modulo>/"
|
||||
ls -la <base_projeto>/../wiki/dev/<modulo-id>/*.md 2>/dev/null || echo "WIKI DEV AUSENTE EM <base_projeto>/../wiki/dev/<modulo-id>/"
|
||||
```
|
||||
|
||||
### 5. Pilar 5 — Rota de Integração de IA (`/llm.md`)
|
||||
|
|
@ -66,10 +66,19 @@ ls -la ../../wiki/dev/<modulo>/*.md 2>/dev/null || echo "WIKI DEV AUSENTE EM ../
|
|||
rg "llm\.md" --include='*.ts' <modulo>-back/src/ -n || echo "ROTA /llm.md NÃO ENCONTRADA NO BACKEND"
|
||||
```
|
||||
|
||||
### 6. Pilar 6 — Memória das Ações da IA (`<base_projeto>/memorias-ia/`)
|
||||
### 6. Pilar 6 — Memória das Ações da IA e Identidade (`<base_projeto>/memorias-ia/`)
|
||||
|
||||
```sh
|
||||
# Verificar memórias registradas para o projeto
|
||||
# 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"
|
||||
done
|
||||
else
|
||||
echo "CRÍTICO: memorias-ia/modulo.yml AUSENTE"
|
||||
fi
|
||||
|
||||
# 2. Verificar memórias registradas para o projeto
|
||||
ls -la memorias-ia/ 2>/dev/null || echo "DIRETÓRIO memorias-ia/ NÃO ENCONTRADO NA RAIZ DO PROJETO"
|
||||
```
|
||||
|
||||
|
|
@ -83,9 +92,10 @@ 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 (../../wiki/<modulo>/):** Presente / Ausente
|
||||
- **Wiki de Desenvolvimento (../../wiki/dev/<modulo>/):** Presente / Ausente
|
||||
- **Wiki de Usuário (<base_projeto>/../wiki/<modulo-id>/):** Presente / Ausente
|
||||
- **Wiki de Desenvolvimento (<base_projeto>/../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
|
||||
|
|
|
|||
|
|
@ -13,8 +13,8 @@ Atalho rápido para o **Agente de Documentação & Memória** cobrindo os 6 pila
|
|||
|
||||
- `1. Código-Fonte` $\rightarrow$ JSDoc de aplicação prática (`rules/jsdoc-padrao.md`)
|
||||
- `2. Ajuda UI` $\rightarrow$ `modalX.ajuda.md` co-localizado com `modalX.vue`
|
||||
- `3. Wiki Usuário` $\rightarrow$ `../../wiki/<modulo>/` (VitePress com acesso dos usuários)
|
||||
- `4. Wiki Dev` $\rightarrow$ `../../wiki/dev/<modulo>/` (VitePress com acesso interno dev e regras `{modulo}.regras-negocio.md`)
|
||||
- `3. Wiki Usuário` $\rightarrow$ `<base_projeto>/../wiki/<modulo>/` (VitePress com acesso dos usuários)
|
||||
- `4. Wiki Dev` $\rightarrow$ `<base_projeto>/../wiki/dev/<modulo>/` (VitePress com acesso interno dev e regras `{modulo}.regras-negocio.md`)
|
||||
- `5. Rota IA` $\rightarrow$ Rota do backend `/llm.md`
|
||||
- `6. Memória IA` $\rightarrow$ `<base_projeto>/memorias-ia/`
|
||||
|
||||
|
|
|
|||
|
|
@ -13,8 +13,8 @@ Atalho rápido para o **Agente de Documentação & Memória** cobrindo os 6 pila
|
|||
|
||||
- `1. Código-Fonte` $\rightarrow$ JSDoc de aplicação prática (`rules/jsdoc-padrao.md`)
|
||||
- `2. Ajuda UI` $\rightarrow$ `modalX.ajuda.md` co-localizado com `modalX.vue`
|
||||
- `3. Wiki Usuário` $\rightarrow$ `../../wiki/<modulo>/` (VitePress com acesso dos usuários)
|
||||
- `4. Wiki Dev` $\rightarrow$ `../../wiki/dev/<modulo>/` (VitePress com acesso interno dev e regras `{modulo}.regras-negocio.md`)
|
||||
- `3. Wiki Usuário` $\rightarrow$ `<base_projeto>/../wiki/<modulo>/` (VitePress com acesso dos usuários)
|
||||
- `4. Wiki Dev` $\rightarrow$ `<base_projeto>/../wiki/dev/<modulo>/` (VitePress com acesso interno dev e regras `{modulo}.regras-negocio.md`)
|
||||
- `5. Rota IA` $\rightarrow$ Rota do backend `/llm.md`
|
||||
- `6. Memória IA` $\rightarrow$ `<base_projeto>/memorias-ia/`
|
||||
|
||||
|
|
|
|||
|
|
@ -17,8 +17,8 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
|
|||
|
||||
1. **Pilar 1 (Código-Fonte):** Insere comentários JSDoc de aplicação prática nos arquivos alterados (`rules/jsdoc-padrao.md`).
|
||||
2. **Pilar 2 (Ajuda UI):** Gera `{componente}.ajuda.md` para modais e telas criados/modificados (`skills/adicionar-ajuda`).
|
||||
3. **Pilar 3 (Wiki do Usuário):** Atualiza tutoriais e manuais em `../../wiki/<modulo>/` (aplicação VitePress com acesso dos usuários).
|
||||
4. **Pilar 4 (Wiki de Desenvolvimento):** Documenta regras de negócio (`{modulo}.regras-negocio.md`), modelos e ADRs em `../../wiki/dev/<modulo>/` (aplicação VitePress com acesso interno dev).
|
||||
3. **Pilar 3 (Wiki do Usuário):** Atualiza tutoriais e manuais em `<base_projeto>/../wiki/<modulo>/` (aplicação VitePress com acesso dos usuários).
|
||||
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 em `<base_projeto>/memorias-ia/`.
|
||||
|
||||
|
|
@ -30,8 +30,8 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
|
|||
| :--- | :--- | :--- | :--- |
|
||||
| **1. Código-Fonte** | `.ts`, `.vue`, `.js` | Desenvolvedores / IA | JSDoc e comentários claros quanto à aplicação prática e contexto de negócio. |
|
||||
| **2. Ajuda na Tela** | `*-front/.../{componente}.ajuda.md` | Usuários da UI | Ajuda contextual co-localizada: para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`. |
|
||||
| **3. Wiki do Usuário** | `../../wiki/<modulo>/` | Usuários / Clientes | Aplicação VitePress com acesso dos usuários (manuais, tutoriais e fluxos). |
|
||||
| **4. Wiki de Desenvolvimento** | `../../wiki/dev/<modulo>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno dev: regras de negócio (`{modulo}.regras-negocio.md`), arquitetura e ADRs (`adrs/`). |
|
||||
| **3. Wiki do Usuário** | `<base_projeto>/../wiki/<modulo>/` | Usuários / Clientes | Aplicação VitePress com acesso dos usuários (manuais, tutoriais e fluxos). |
|
||||
| **4. Wiki de Desenvolvimento** | `<base_projeto>/../wiki/dev/<modulo>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno dev: regras de negócio (`{modulo}.regras-negocio.md`), arquitetura e ADRs (`adrs/`). |
|
||||
| **5. Integração de IA** | Rota Backend `/llm.md` | Agentes de IA / LLMs | Catálogo de schemas Zod, enums e contratos para consumo por LLMs. |
|
||||
| **6. Memória da IA** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | Registros de sessões, otimizações executadas e decisões históricas. |
|
||||
|
||||
|
|
@ -66,4 +66,4 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
|
|||
1. **Nunca inventar regras:** Documentar estritamente o que foi implementado no código ou declarado na conversa.
|
||||
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 `../../wiki/`.
|
||||
4. **Polimorfismo:** O `.agent` é genérico; personalizações ficam em `./memorias-ia/` e `<base_projeto>/../wiki/`.
|
||||
|
|
|
|||
|
|
@ -17,8 +17,8 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
|
|||
|
||||
1. **Pilar 1 (Código-Fonte):** Insere comentários JSDoc de aplicação prática nos arquivos alterados (`rules/jsdoc-padrao.md`).
|
||||
2. **Pilar 2 (Ajuda UI):** Gera `{componente}.ajuda.md` para modais e telas criados/modificados (`skills/adicionar-ajuda`).
|
||||
3. **Pilar 3 (Wiki do Usuário):** Atualiza tutoriais e manuais em `../../wiki/<modulo>/` (aplicação VitePress com acesso dos usuários).
|
||||
4. **Pilar 4 (Wiki de Desenvolvimento):** Documenta regras de negócio (`{modulo}.regras-negocio.md`), modelos e ADRs em `../../wiki/dev/<modulo>/` (aplicação VitePress com acesso interno dev).
|
||||
3. **Pilar 3 (Wiki do Usuário):** Atualiza tutoriais e manuais em `<base_projeto>/../wiki/<modulo>/` (aplicação VitePress com acesso dos usuários).
|
||||
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 em `<base_projeto>/memorias-ia/`.
|
||||
|
||||
|
|
@ -30,8 +30,8 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
|
|||
| :--- | :--- | :--- | :--- |
|
||||
| **1. Código-Fonte** | `.ts`, `.vue`, `.js` | Desenvolvedores / IA | JSDoc e comentários claros quanto à aplicação prática e contexto de negócio. |
|
||||
| **2. Ajuda na Tela** | `*-front/.../{componente}.ajuda.md` | Usuários da UI | Ajuda contextual co-localizada: para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`. |
|
||||
| **3. Wiki do Usuário** | `../../wiki/<modulo>/` | Usuários / Clientes | Aplicação VitePress com acesso dos usuários (manuais, tutoriais e fluxos). |
|
||||
| **4. Wiki de Desenvolvimento** | `../../wiki/dev/<modulo>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno dev: regras de negócio (`{modulo}.regras-negocio.md`), arquitetura e ADRs (`adrs/`). |
|
||||
| **3. Wiki do Usuário** | `<base_projeto>/../wiki/<modulo>/` | Usuários / Clientes | Aplicação VitePress com acesso dos usuários (manuais, tutoriais e fluxos). |
|
||||
| **4. Wiki de Desenvolvimento** | `<base_projeto>/../wiki/dev/<modulo>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno dev: regras de negócio (`{modulo}.regras-negocio.md`), arquitetura e ADRs (`adrs/`). |
|
||||
| **5. Integração de IA** | Rota Backend `/llm.md` | Agentes de IA / LLMs | Catálogo de schemas Zod, enums e contratos para consumo por LLMs. |
|
||||
| **6. Memória da IA** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | Registros de sessões, otimizações executadas e decisões históricas. |
|
||||
|
||||
|
|
@ -66,4 +66,4 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
|
|||
1. **Nunca inventar regras:** Documentar estritamente o que foi implementado no código ou declarado na conversa.
|
||||
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 `../../wiki/`.
|
||||
4. **Polimorfismo:** O `.agent` é genérico; personalizações ficam em `./memorias-ia/` e `<base_projeto>/../wiki/`.
|
||||
|
|
|
|||
|
|
@ -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 (../../wiki/dev/<modulo>/adrs/).
|
||||
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/).
|
||||
---
|
||||
|
||||
# Skill: Documentar Decisão Técnica (ADR)
|
||||
|
|
@ -26,12 +26,13 @@ O objetivo é garantir que **nenhuma decisão fique apenas na cabeça** ou perdi
|
|||
|
||||
---
|
||||
|
||||
## PASSO 1 — Localizar o Diretório de ADRs
|
||||
## PASSO 1 — Obter Identidade do Módulo e Localizar o Diretório de ADRs
|
||||
|
||||
Convenção de diretório: `../../wiki/dev/<modulo>/adrs/` (na Wiki de Desenvolvimento) ou `.agent/DOCUMENTACAO/arquitetura/`.
|
||||
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).
|
||||
|
||||
```bash
|
||||
mkdir -p ../../wiki/dev/<modulo>/adrs
|
||||
mkdir -p <base_projeto>/../wiki/dev/<modulo-id>/adrs
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -152,7 +153,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 `../../wiki/dev/<modulo>/adrs/` ou `.agent/DOCUMENTACAO/arquitetura/`?
|
||||
- [ ] O ADR foi salvo em `<base_projeto>/../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?
|
||||
|
||||
|
|
@ -162,4 +163,4 @@ Antes de considerar completo:
|
|||
|
||||
- Rule: `rules/ddd-documentacao-primeiro.md`
|
||||
- Workflow: `global/workflows/aprimora-ia.md`
|
||||
- Wiki de Desenvolvimento: `../../wiki/dev/<modulo>/adrs/`
|
||||
- Wiki de Desenvolvimento: `<base_projeto>/../wiki/dev/<modulo-id>/adrs/`
|
||||
|
|
|
|||
|
|
@ -4,33 +4,34 @@ scope: global
|
|||
updatedAt: "2026-09-01"
|
||||
description: >
|
||||
Guia para documentar o domínio científico/técnico de cada módulo nas wikis
|
||||
de usuário (../../wiki/<modulo>/) e de desenvolvimento (../../wiki/dev/<modulo>/).
|
||||
de usuário (<base_projeto>/../wiki/<modulo-id>/) e de desenvolvimento (<base_projeto>/../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 `../../wiki` é uma **aplicação VitePress**, onde a base factual do domínio é estruturada em dois níveis de acesso:
|
||||
1. **Wiki do Usuário (`../../wiki/<modulo>/`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
|
||||
2. **Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`):** 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 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).
|
||||
|
||||
---
|
||||
|
||||
## PASSO 1 — Identificar o Domínio do Módulo
|
||||
## PASSO 1 — Identificar a Identidade e Domínio do Módulo via `memorias-ia/modulo.yml`
|
||||
|
||||
Determinar qual área da ciência/gestão o módulo aborda:
|
||||
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-descricao`: escopo funcional e propósito do módulo
|
||||
- `modulo-tipo`: stack tecnológica e arquitetura
|
||||
|
||||
| Exemplo de módulo | Domínio | Destino Usuário | Destino Dev |
|
||||
|---|---|---|---|
|
||||
| SIGMA | Monitoramento ambiental (efluentes, piezometria, bombeamento) | `../../wiki/e-licencie.sigma/` | `../../wiki/dev/e-licencie.sigma/` |
|
||||
| Licenciamento | Gestão de licenças (LP, LI, LO, condicionantes) | `../../wiki/e-licencie/` | `../../wiki/dev/e-licencie/` |
|
||||
| Resíduos | Gestão de resíduos sólidos (PGRS, MTR, MTR-e) | `../../wiki/e-licencie.residuos/` | `../../wiki/dev/e-licencie.residuos/` |
|
||||
| Qualificação | Qualificação e conformidade de fornecedores | `../../wiki/e-licencie.qualifica/` | `../../wiki/dev/e-licencie.qualifica/` |
|
||||
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>/`
|
||||
|
||||
---
|
||||
|
||||
## PASSO 2 — Criar Documentação na Wiki do Usuário (`../../wiki/<modulo>/`)
|
||||
## PASSO 2 — Criar Documentação na Wiki do Usuário (`<base_projeto>/../wiki/<modulo-id>/`)
|
||||
|
||||
Estruturar o guia do usuário e conceitos de negócio em linguagem clara e acessível:
|
||||
|
||||
|
|
@ -54,7 +55,7 @@ Breve descrição do propósito do módulo para o gestor e operador.
|
|||
|
||||
---
|
||||
|
||||
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`)
|
||||
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo>/`)
|
||||
|
||||
Estruturar a especificação técnica, modelos de banco e arquitetura:
|
||||
|
||||
|
|
@ -85,8 +86,8 @@ Estruturar a especificação técnica, modelos de banco e arquitetura:
|
|||
|
||||
## Checklist Final
|
||||
|
||||
- [ ] Documentação de usuário criada/atualizada em `../../wiki/<modulo>/`?
|
||||
- [ ] Documentação técnica criada/atualizada em `../../wiki/dev/<modulo>/`?
|
||||
- [ ] Documentação de usuário criada/atualizada em `<base_projeto>/../wiki/<modulo>/`?
|
||||
- [ ] Documentação técnica criada/atualizada em `<base_projeto>/../wiki/dev/<modulo>/`?
|
||||
- [ ] Glossário com os termos centrais do domínio documentado?
|
||||
- [ ] Regras e entidades técnicas alinhadas com os schemas Zod do `*-comuns`?
|
||||
- [ ] Rota `/llm.md` no backend reflete o módulo?
|
||||
|
|
|
|||
|
|
@ -1,20 +1,20 @@
|
|||
---
|
||||
name: documentar-regras-negocio
|
||||
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (../../wiki/dev/<modulo>/) e garantir consistência com o código TypeScript.
|
||||
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.
|
||||
scope: global
|
||||
updatedAt: "2026-09-01"
|
||||
updatedAt: "2026-09-02"
|
||||
---
|
||||
|
||||
# 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 `../../wiki/dev/<modulo>/`.
|
||||
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>/`.
|
||||
|
||||
---
|
||||
|
||||
[1] Ler o módulo TypeScript completamente
|
||||
|
||||
Identificar e anotar:
|
||||
[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`).
|
||||
2. Identificar e anotar no código:
|
||||
- Nome do arquivo e localização exata no código
|
||||
- Funções exportadas e suas responsabilidades
|
||||
- Todos os `if` que representam critérios de decisão
|
||||
|
|
@ -28,7 +28,7 @@ Identificar e anotar:
|
|||
[2] Verificar se já existe a documentação de regras na Wiki de Desenvolvimento
|
||||
|
||||
```bash
|
||||
ls ../../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
|
||||
ls <base_projeto>/../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 ../../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
|
|||
|
||||
[3] Criar o arquivo de regras na Wiki de Desenvolvimento
|
||||
|
||||
**Localização:** `../../wiki/dev/<modulo>/{nome-do-modulo}.regras-negocio.md` (ou `../../wiki/dev/<modulo>/regras-negocio/`).
|
||||
**Localização:** `<base_projeto>/../wiki/dev/<modulo-id>/{nome-do-modulo}.regras-negocio.md` (ou `<base_projeto>/../wiki/dev/<modulo-id>/regras-negocio/`).
|
||||
|
||||
Preencher com a estrutura padrão:
|
||||
- Contexto operacional
|
||||
|
|
@ -55,7 +55,7 @@ Preencher com a estrutura padrão:
|
|||
Garantir que a primeira linha útil do arquivo TypeScript seja:
|
||||
|
||||
```typescript
|
||||
// Regras de negócio: ver ../../wiki/dev/<modulo>/{modulo}.regras-negocio.md
|
||||
// Regras de negócio: ver <base_projeto>/../wiki/dev/<modulo>/{modulo}.regras-negocio.md
|
||||
```
|
||||
|
||||
Se já existia e está correto → sem mudança necessária.
|
||||
|
|
@ -100,6 +100,6 @@ 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 `../../wiki/dev/<modulo>/`.
|
||||
- Criar ou atualizar ADR em `../../wiki/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
|
||||
- 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`.
|
||||
- Registrar decisões e ações na memória em `<base_projeto>/memorias-ia/`.
|
||||
|
|
|
|||
|
|
@ -12,9 +12,15 @@ Use esta skill ao iniciar trabalho em um monorepo desconhecido, ao onboardar em
|
|||
|
||||
---
|
||||
|
||||
## PASSO 1 — Identificar a Raiz e o Gerenciador de Pacotes
|
||||
## PASSO 1 — Identificar a Identidade do Módulo e o Gerenciador de Pacotes
|
||||
|
||||
Localize os arquivos que definem a estratégia de monorepo:
|
||||
1. Consultar obrigatoriamente `<base_projeto>/memorias-ia/modulo.yml` para obter:
|
||||
- `modulo-id`: identificador canônico do módulo
|
||||
- `modulo-caminho`: rota/prefixo de URL base
|
||||
- `modulo-descricao`: escopo funcional e propósito de negócio
|
||||
- `modulo-tipo`: arquitetura e stack técnica
|
||||
|
||||
2. Localize os arquivos que definem a estratégia de monorepo:
|
||||
|
||||
```bash
|
||||
# Identificar o gerenciador e workspace config
|
||||
|
|
@ -23,6 +29,7 @@ ls -la package.json pnpm-workspace.yaml lerna.json turbo.json nx.json tsconfig.b
|
|||
|
||||
Elementos a extrair:
|
||||
|
||||
- **Identidade do Módulo**: `modulo-id` e `modulo-caminho` em `memorias-ia/modulo.yml`
|
||||
- **Gerenciador**: `pnpm` (workspaces em `pnpm-workspace.yaml`), `npm/yarn` (workspaces em `package.json`), ou `nx`/`turbo`
|
||||
- **Pacotes compartilhados**: diretórios listados em `packages:` ou `workspaces:`
|
||||
- **Apps/serviços**: diretórios de aplicações deployáveis
|
||||
|
|
|
|||
|
|
@ -32,7 +32,8 @@ Antes de gerar peças de marketing, o arquivo comercial do módulo (`./COMERCIAL
|
|||
|
||||
### 1. Identificar o módulo e o canal
|
||||
|
||||
Perguntar ao usuário:
|
||||
1. Consultar `<base_projeto>/memorias-ia/modulo.yml` para obter `modulo-descricao`, `modulo-tipo` e `modulo-id`.
|
||||
2. Perguntar ao usuário:
|
||||
- Qual módulo ou funcionalidade será divulgado?
|
||||
- Quais canais deseja? (LinkedIn, Instagram, WhatsApp, E-mail, ou todos)
|
||||
|
||||
|
|
|
|||
86
skills/onboarding-projeto/SKILL.md
Normal file
86
skills/onboarding-projeto/SKILL.md
Normal file
|
|
@ -0,0 +1,86 @@
|
|||
---
|
||||
name: onboarding-projeto
|
||||
description: Guia operacional para inicializar o framework .agent em qualquer novo repositório ou módulo do ecossistema.
|
||||
scope: global
|
||||
updatedAt: "2026-09-02"
|
||||
---
|
||||
|
||||
# Skill: Onboarding de Novo Projeto com `.agent`
|
||||
|
||||
Use esta skill sempre que for criar um novo projeto, inicializar um módulo SaaS ou integrar o framework `.agent` como submódulo Git em um repositório existente.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Fluxo de Onboarding em 4 Passos
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[1. Adicionar Submódulo] --> B[2. Configurar modulo.yml]
|
||||
B --> C[3. Auditar com validar-setup.sh]
|
||||
C --> D[4. Instanciar os 6 Pilares DDD]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 1 — Adicionar o Submódulo `.agent`
|
||||
|
||||
Na raiz do repositório do novo projeto:
|
||||
|
||||
```bash
|
||||
git submodule add git@github.com:azteca-sistemas/agent-ia.git .agent
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 2 — Configurar a Identidade do Módulo (`memorias-ia/modulo.yml`)
|
||||
|
||||
1. Criar a pasta de memórias e copiar o template oficial:
|
||||
```bash
|
||||
mkdir -p memorias-ia
|
||||
cp .agent/DOCUMENTACAO/templates/modulo.yml.template memorias-ia/modulo.yml
|
||||
```
|
||||
|
||||
2. Editar `memorias-ia/modulo.yml` preenchendo os 4 campos obrigatórios:
|
||||
```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-tipo: aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 3 — Validar a Conformidade com o Script de Setup
|
||||
|
||||
Execute o script de auditoria para certificar que os parâmetros foram preenchidos corretamente:
|
||||
|
||||
```bash
|
||||
bash .agent/validar-setup.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 4 — Instanciar os 6 Pilares de Documentação (Templates)
|
||||
|
||||
Utilize os modelos canônicos disponíveis em `.agent/DOCUMENTACAO/templates/`:
|
||||
|
||||
| Pilar DDD | Destino no Projeto | Template Canônico |
|
||||
| :--- | :--- | :--- |
|
||||
| **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 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
|
||||
|
||||
Se o novo projeto possuir regras de negócio, bibliotecas ou rotinas exclusivas que **não devem** ser enviadas ao submódulo global `.agent`:
|
||||
|
||||
```bash
|
||||
mkdir -p .agent-local/rules .agent-local/skills .agent-local/workflows
|
||||
```
|
||||
|
||||
> ℹ️ **Hierarquia:** Qualquer arquivo em `.agent-local/` sobrescreve automaticamente o arquivo correspondente do submódulo `.agent/` (`.agent-local/ > .agent/`).
|
||||
|
|
@ -32,7 +32,8 @@ Antes de gerar o texto de orçamento, o agente deve ler o código-fonte do módu
|
|||
|
||||
### 1. Identificar o módulo
|
||||
|
||||
Perguntar ao usuário qual módulo ou funcionalidade será orçado.
|
||||
1. Consultar `<base_projeto>/memorias-ia/modulo.yml` para obter `modulo-descricao`, `modulo-tipo` e `modulo-id`.
|
||||
2. Perguntar ao usuário qual módulo ou funcionalidade será orçado.
|
||||
|
||||
### 2. Levantar contexto
|
||||
|
||||
|
|
|
|||
|
|
@ -32,7 +32,8 @@ Antes de gerar roteiros, o agente deve entender as funcionalidades reais do mód
|
|||
|
||||
### 1. Identificar o tema
|
||||
|
||||
Perguntar ao usuário:
|
||||
1. Consultar `<base_projeto>/memorias-ia/modulo.yml` para obter `modulo-descricao`, `modulo-tipo` e `modulo-id`.
|
||||
2. Perguntar ao usuário:
|
||||
- Qual módulo ou funcionalidade será o tema dos reels?
|
||||
- Quantos roteiros deseja na cadeia? (padrão: 6)
|
||||
- Algum tom específico? (provocativo, educativo, humorístico)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue