otimização do agent para docuemntação
This commit is contained in:
parent
1a25edc274
commit
890eddc464
60 changed files with 1807 additions and 1435 deletions
|
|
@ -1,96 +1,104 @@
|
|||
---
|
||||
name: diagnosticar-lacunas-documentacao
|
||||
description: >
|
||||
Diagnóstico de lacunas de documentação: funções sem JSDoc, módulos sem
|
||||
regras de negócio documentadas, documentação desatualizada.
|
||||
scope: local
|
||||
Diagnóstico de lacunas de documentação cobrindo os 6 pilares: comentários de aplicação no código,
|
||||
ajuda na tela (.ajuda.md), wiki de usuário, wiki dev, rota /llm.md e memórias da IA.
|
||||
scope: global
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Skill: Diagnosticar Lacunas de Documentação
|
||||
# Skill: Diagnosticar Lacunas de Documentação e Memória
|
||||
|
||||
## Objetivo
|
||||
|
||||
Identificar proativamente onde a documentação está ausente, incompleta ou desatualizada antes de criar ou corrigir documentação.
|
||||
Identificar proativamente onde a documentação e memórias estão ausentes, incompletas ou desatualizadas antes de criar ou corrigir código.
|
||||
|
||||
## Etapas
|
||||
---
|
||||
|
||||
### 1. Verificar JSDoc em Funções Compartilhadas
|
||||
## Etapas de Diagnóstico nos 6 Pilares
|
||||
|
||||
### 1. Pilar 1 — Comentários e JSDoc no Código-Fonte
|
||||
|
||||
```sh
|
||||
# Listar funções exportadas sem JSDoc
|
||||
rg "^export (const|function|async function)" --include='*.ts' <modulo>-comuns/src/ -n | while read line; do
|
||||
rg "^export (const|function|async function)" --include='*.ts' <modulo>-comuns/src/ <modulo>-back/src/ -n | while read line; do
|
||||
file=$(echo "$line" | cut -d: -f1)
|
||||
lineno=$(echo "$line" | cut -d: -f2)
|
||||
prev=$((lineno - 1))
|
||||
if ! sed -n "${prev}p" "$file" | grep -q "*/"; then
|
||||
echo "SEM JSDOC: $line"
|
||||
echo "SEM JSDOC DE APLICAÇÃO: $line"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### 2. Verificar Regras de Negócio Documentadas
|
||||
### 2. Pilar 2 — Ajuda na Tela (UI) em `.ajuda.md`
|
||||
|
||||
```sh
|
||||
# Listar módulos com lógica complexa
|
||||
rg "if.*&&|switch|\.length\s*>" --include='*.ts' <modulo>-back/src/servicos/ -c | awk -F: '$2>5' | sort -t: -k2 -rn
|
||||
|
||||
# Verificar quais têm .regras-negocio.md
|
||||
fd ".regras-negocio.md" <modulo>/ -l
|
||||
|
||||
# Detectar lógica complexa sem documentação de regras
|
||||
# (comparar os dois resultados acima)
|
||||
# Listar modais/telas Vue que não possuem arquivo .ajuda.md correspondente
|
||||
find <modulo>-front/src -name "modal*.vue" -o -name "Modal*.vue" | while read vueFile; do
|
||||
dir=$(dirname "$vueFile")
|
||||
base=$(basename "$vueFile" .vue)
|
||||
ajudaFile="$dir/$base.ajuda.md"
|
||||
if [ ! -f "$ajudaFile" ]; then
|
||||
echo "MODAL SEM AJUDA: $vueFile → falta $base.ajuda.md"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### 3. Verificar Documentação de API
|
||||
### 3. Pilar 3 — Wiki do Usuário (`../../wiki/<modulo>/`)
|
||||
|
||||
```sh
|
||||
# Listar rotas sem comentário explicativo
|
||||
rg "router\.(get|post|put|patch|delete)" --include='*.ts' <modulo>-back/src/rotas/ -n
|
||||
|
||||
# Verificar quais rotas têm JSDoc
|
||||
rg "/\*\*" --include='*.ts' <modulo>-back/src/rotas/ -c
|
||||
# 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>/"
|
||||
```
|
||||
|
||||
### 4. Detectar Dessincronia Código ↔ Docs
|
||||
### 4. Pilar 4 — Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`)
|
||||
|
||||
```sh
|
||||
# Buscar campos mencionados em .regras-negocio.md que não existem no código
|
||||
# (verificação manual por arquivo)
|
||||
|
||||
# Buscar decisões técnicas que deveriam estar na Memória
|
||||
rg "DECISÃO|ADR|NOTA|IMPORTANTE" --include='*.ts' --include='*.md' <modulo>/ -n
|
||||
# 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>/"
|
||||
```
|
||||
|
||||
### 5. Gerar Relatório
|
||||
### 5. Pilar 5 — Rota de Integração de IA (`/llm.md`)
|
||||
|
||||
```sh
|
||||
# Verificar se o backend possui a rota /llm.md registrada
|
||||
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/`)
|
||||
|
||||
```sh
|
||||
# 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"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Relatório Consolidado de Diagnóstico
|
||||
|
||||
```markdown
|
||||
# Diagnóstico de Documentação — [nome do módulo]
|
||||
# Diagnóstico de Documentação e Memória — [Módulo]
|
||||
|
||||
## Resumo
|
||||
- **Funções compartilhadas sem JSDoc:** N
|
||||
- **Módulos complexos sem .regras-negocio.md:** N
|
||||
- **Rotas sem documentação:** N
|
||||
## 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
|
||||
- **Rota /llm.md no backend:** Configurada / Ausente
|
||||
- **Registros em memorias-ia/:** N registros
|
||||
|
||||
## Lacunas Encontradas
|
||||
|
||||
### 🔴 Crítico — Lógica Complexa Não Documentada
|
||||
| Arquivo | Complexidade | O que documentar |
|
||||
|---------|-------------|-----------------|
|
||||
|
||||
### 🟡 Moderado — JSDoc Ausente
|
||||
| Arquivo | Função | Tipo |
|
||||
|---------|--------|------|
|
||||
|
||||
### 🟢 Baixo — Melhorias
|
||||
| Arquivo | O que melhorar |
|
||||
|---------|---------------|
|
||||
|
||||
## Plano de Documentação (priorizado)
|
||||
## Ações Recomendadas
|
||||
1. ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `global/rules/diagnostico-antes-correcao`
|
||||
- Rule: `global/rules/jsdoc-padrao`
|
||||
- Rule: `global/rules/regras-negocio-md`
|
||||
- Rule: `rules/ddd-documentacao-primeiro.md`
|
||||
- Rule: `rules/jsdoc-padrao.md`
|
||||
- Rule: `rules/regras-negocio-md.md`
|
||||
- Skill: `skills/adicionar-ajuda/SKILL.md`
|
||||
- Skill: `skills/documentar-dominio-modulo/SKILL.md`
|
||||
- Skill: `skills/documentar-decisao-tecnica/SKILL.md`
|
||||
|
|
|
|||
|
|
@ -1,96 +1,104 @@
|
|||
---
|
||||
name: diagnosticar-lacunas-documentacao
|
||||
description: >
|
||||
Diagnóstico de lacunas de documentação: funções sem JSDoc, módulos sem
|
||||
regras de negócio documentadas, documentação desatualizada.
|
||||
scope: local
|
||||
Diagnóstico de lacunas de documentação cobrindo os 6 pilares: comentários de aplicação no código,
|
||||
ajuda na tela (.ajuda.md), wiki de usuário, wiki dev, rota /llm.md e memórias da IA.
|
||||
scope: global
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Skill: Diagnosticar Lacunas de Documentação
|
||||
# Skill: Diagnosticar Lacunas de Documentação e Memória
|
||||
|
||||
## Objetivo
|
||||
|
||||
Identificar proativamente onde a documentação está ausente, incompleta ou desatualizada antes de criar ou corrigir documentação.
|
||||
Identificar proativamente onde a documentação e memórias estão ausentes, incompletas ou desatualizadas antes de criar ou corrigir código.
|
||||
|
||||
## Etapas
|
||||
---
|
||||
|
||||
### 1. Verificar JSDoc em Funções Compartilhadas
|
||||
## Etapas de Diagnóstico nos 6 Pilares
|
||||
|
||||
### 1. Pilar 1 — Comentários e JSDoc no Código-Fonte
|
||||
|
||||
```sh
|
||||
# Listar funções exportadas sem JSDoc
|
||||
rg "^export (const|function|async function)" --include='*.ts' <modulo>-comuns/src/ -n | while read line; do
|
||||
rg "^export (const|function|async function)" --include='*.ts' <modulo>-comuns/src/ <modulo>-back/src/ -n | while read line; do
|
||||
file=$(echo "$line" | cut -d: -f1)
|
||||
lineno=$(echo "$line" | cut -d: -f2)
|
||||
prev=$((lineno - 1))
|
||||
if ! sed -n "${prev}p" "$file" | grep -q "*/"; then
|
||||
echo "SEM JSDOC: $line"
|
||||
echo "SEM JSDOC DE APLICAÇÃO: $line"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### 2. Verificar Regras de Negócio Documentadas
|
||||
### 2. Pilar 2 — Ajuda na Tela (UI) em `.ajuda.md`
|
||||
|
||||
```sh
|
||||
# Listar módulos com lógica complexa
|
||||
rg "if.*&&|switch|\.length\s*>" --include='*.ts' <modulo>-back/src/servicos/ -c | awk -F: '$2>5' | sort -t: -k2 -rn
|
||||
|
||||
# Verificar quais têm .regras-negocio.md
|
||||
fd ".regras-negocio.md" <modulo>/ -l
|
||||
|
||||
# Detectar lógica complexa sem documentação de regras
|
||||
# (comparar os dois resultados acima)
|
||||
# Listar modais/telas Vue que não possuem arquivo .ajuda.md correspondente
|
||||
find <modulo>-front/src -name "modal*.vue" -o -name "Modal*.vue" | while read vueFile; do
|
||||
dir=$(dirname "$vueFile")
|
||||
base=$(basename "$vueFile" .vue)
|
||||
ajudaFile="$dir/$base.ajuda.md"
|
||||
if [ ! -f "$ajudaFile" ]; then
|
||||
echo "MODAL SEM AJUDA: $vueFile → falta $base.ajuda.md"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### 3. Verificar Documentação de API
|
||||
### 3. Pilar 3 — Wiki do Usuário (`../../wiki/<modulo>/`)
|
||||
|
||||
```sh
|
||||
# Listar rotas sem comentário explicativo
|
||||
rg "router\.(get|post|put|patch|delete)" --include='*.ts' <modulo>-back/src/rotas/ -n
|
||||
|
||||
# Verificar quais rotas têm JSDoc
|
||||
rg "/\*\*" --include='*.ts' <modulo>-back/src/rotas/ -c
|
||||
# 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>/"
|
||||
```
|
||||
|
||||
### 4. Detectar Dessincronia Código ↔ Docs
|
||||
### 4. Pilar 4 — Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`)
|
||||
|
||||
```sh
|
||||
# Buscar campos mencionados em .regras-negocio.md que não existem no código
|
||||
# (verificação manual por arquivo)
|
||||
|
||||
# Buscar decisões técnicas que deveriam estar na Memória
|
||||
rg "DECISÃO|ADR|NOTA|IMPORTANTE" --include='*.ts' --include='*.md' <modulo>/ -n
|
||||
# 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>/"
|
||||
```
|
||||
|
||||
### 5. Gerar Relatório
|
||||
### 5. Pilar 5 — Rota de Integração de IA (`/llm.md`)
|
||||
|
||||
```sh
|
||||
# Verificar se o backend possui a rota /llm.md registrada
|
||||
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/`)
|
||||
|
||||
```sh
|
||||
# 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"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Relatório Consolidado de Diagnóstico
|
||||
|
||||
```markdown
|
||||
# Diagnóstico de Documentação — [nome do módulo]
|
||||
# Diagnóstico de Documentação e Memória — [Módulo]
|
||||
|
||||
## Resumo
|
||||
- **Funções compartilhadas sem JSDoc:** N
|
||||
- **Módulos complexos sem .regras-negocio.md:** N
|
||||
- **Rotas sem documentação:** N
|
||||
## 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
|
||||
- **Rota /llm.md no backend:** Configurada / Ausente
|
||||
- **Registros em memorias-ia/:** N registros
|
||||
|
||||
## Lacunas Encontradas
|
||||
|
||||
### 🔴 Crítico — Lógica Complexa Não Documentada
|
||||
| Arquivo | Complexidade | O que documentar |
|
||||
|---------|-------------|-----------------|
|
||||
|
||||
### 🟡 Moderado — JSDoc Ausente
|
||||
| Arquivo | Função | Tipo |
|
||||
|---------|--------|------|
|
||||
|
||||
### 🟢 Baixo — Melhorias
|
||||
| Arquivo | O que melhorar |
|
||||
|---------|---------------|
|
||||
|
||||
## Plano de Documentação (priorizado)
|
||||
## Ações Recomendadas
|
||||
1. ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `global/rules/diagnostico-antes-correcao`
|
||||
- Rule: `global/rules/jsdoc-padrao`
|
||||
- Rule: `global/rules/regras-negocio-md`
|
||||
- Rule: `rules/ddd-documentacao-primeiro.md`
|
||||
- Rule: `rules/jsdoc-padrao.md`
|
||||
- Rule: `rules/regras-negocio-md.md`
|
||||
- Skill: `skills/adicionar-ajuda/SKILL.md`
|
||||
- Skill: `skills/documentar-dominio-modulo/SKILL.md`
|
||||
- Skill: `skills/documentar-decisao-tecnica/SKILL.md`
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue