86 lines
5.3 KiB
Markdown
86 lines
5.3 KiB
Markdown
---
|
|
type: workflow
|
|
name: documentacao
|
|
description: Acionar o Agente de Documentação para documentar o contexto do chat ou executar comandos específicos nos 6 pilares com versionamento automático na Wiki
|
|
scope: global
|
|
updatedAt: "2026-09-05"
|
|
---
|
|
|
|
# Workflow: /documentacao (Agente de Documentação & Memória)
|
|
|
|
Este workflow aciona o **Agente de Documentação** para gerar, atualizar ou auditar a documentação nos **6 pilares canônicos** do Documentation-Driven Development (DDD).
|
|
|
|
---
|
|
|
|
## ⚡ Comportamento Padrão (Sem Instruções Adicionais)
|
|
|
|
> **Quando invocado como `/documentacao` (ou `/doc`) sem nenhum parâmetro**, o agente executa automaticamente a **Documentação Contextual Baseada no Chat**:
|
|
|
|
1. **Varredura Integral do Contexto:**
|
|
- Analisa todo o histórico da conversa, arquivos editados (`git status`), decisões tomadas e regras implementadas.
|
|
2. **Distribuição e Geração nos 6 Pilares:**
|
|
- **Pilar 1 (Código-Fonte):** Insere JSDoc de aplicação prática nos arquivos alterados na sessão (`rules/jsdoc-padrao.md`).
|
|
- **Pilar 2 (Ajuda UI):** Gera `{componente}.ajuda.md` para modais e telas criados/modificados (`skills/adicionar-ajuda`).
|
|
- **Pilar 3 (Wiki Usuário):** Atualiza manuais em `<base_projeto>/../wiki/<modulo>/` se houver mudanças com impacto no usuário final.
|
|
- **Pilar 4 (Wiki Dev):** Documenta regras técnicas (`{modulo}.regras-negocio.md`) e ADRs em `<base_projeto>/../wiki/dev/<modulo>/`.
|
|
- **Pilar 5 (Rota IA):** Assegura que novos schemas e rotas estejam refletidos na rota `/llm.md`.
|
|
- **Pilar 6 (Memória IA):** Registra o relatório completo da sessão no arquivo dedicado `<base_projeto>/memorias-ia/sessao-AAAA-MM-DD-slug.md` e indexa a alteração no arquivo central `<base_projeto>/memorias-ia/historico-acoes.md` inserindo linha na tabela com as colunas: `Data | Memória / Ação | Arquivo Memoria | Citações no Código-Fonte`.
|
|
3. **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
|
|
```
|
|
- **Fronteira Inegociável da Aplicação:** Na aplicação principal (`<base_projeto>`), o agente **NÃO pode mexer no git** (o versionamento do código-fonte da aplicação permanece sob controle humano exclusivo).
|
|
4. **Entrega de Relatório:**
|
|
- Apresenta um resumo claro ao operador de tudo o que foi documentado com links diretos para os arquivos gerados e confirmação do push na Wiki.
|
|
|
|
---
|
|
|
|
## 🏛️ Os 6 Pilares Canônicos
|
|
|
|
| Pilar | Escopo / Destino | O que é gerado/auditado |
|
|
| :--- | :--- | :--- |
|
|
| **1. Código-Fonte** | `.ts`, `.vue`, `.js` | JSDoc e comentários claros quanto à aplicação prática (ver `rules/jsdoc-padrao.md`). |
|
|
| **2. Ajuda na Tela** | `*-front/.../{componente}.ajuda.md` | Ajuda contextual co-localizada: para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`. |
|
|
| **3. Wiki do Usuário** | `<base_projeto>/../wiki/<modulo>/` | Aplicação VitePress com acesso dos usuários (manuais, tutoriais e fluxos). |
|
|
| **4. Wiki de Desenvolvimento** | `<base_projeto>/../wiki/dev/<modulo>/` | Aplicação VitePress com acesso interno dev: regras de negócio (`{modulo}.regras-negocio.md`), modelos de banco, arquitetura e ADRs (`adrs/`). |
|
|
| **5. Integração de IA** | Rota Backend `/llm.md` | Catálogo de schemas Zod, enums e contratos para consumo por LLMs. |
|
|
| **6. Memória da IA** | `<base_projeto>/memorias-ia/` | `modulo.yml` (identidade), índice `historico-acoes.md` (`Data \| Memória / Ação \| Arquivo Memoria \| Citações no Código-Fonte`) e memórias de sessão `sessao-AAAA-MM-DD-slug.md`. |
|
|
|
|
---
|
|
|
|
## 🚀 Comandos Específicos (Com Argumentos)
|
|
|
|
```bash
|
|
# Diagnosticar lacunas no módulo
|
|
/documentacao diagnosticar
|
|
|
|
# Documentar JSDoc de aplicação prática em arquivo específico
|
|
/documentacao jsdoc <caminho/arquivo.ts>
|
|
|
|
# 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
|
|
/documentacao wiki-usuario <modulo>
|
|
|
|
# Documentar regras de negócio na Wiki Dev (VitePress) + commit/push na wiki
|
|
/documentacao regras <caminho/servico.ts>
|
|
|
|
# Criar um ADR na Wiki Dev + commit/push na wiki
|
|
/documentacao adr "<Título da Decisão>"
|
|
```
|
|
|
|
*Nota:* Qualquer comando que crie ou modifique arquivos na Wiki (`<base_projeto>/../wiki`) deve finalizar executando `git add`, `git commit` e `git push` dentro de `../wiki`.
|
|
|
|
---
|
|
|
|
## 🔒 Regras Inegociáveis
|
|
|
|
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 `<base_projeto>/../wiki/`.
|
|
5. **Fronteira Git e Push Obrigatório na Wiki:** Toda atualização em `<base_projeto>/../wiki` DEVE ser commitada e enviada via `git push` exclusivamente dentro do diretório `../wiki`. Na aplicação principal (`<base_projeto>`), a IA nunca mexe no Git (ver `rules/proibido-commit-ia.md`).
|