publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

otimização do agent para docuemntação

Browse source
This commit is contained in:
Luiz Silva 2026-09-01 16:55:01 -03:00
parent 1a25edc274
commit 890eddc464
60 changed files with 1807 additions and 1435 deletions
Download patch file Download diff file Expand all files Collapse all files

2
global/rules/autonomia-agente.md
View file

@ -21,7 +21,7 @@ O agente pode executar sem perguntar:
- Corrigir erros de tipagem em arquivos que já está modificando
- Aplicar formatação (`biome check --write`)
- Atualizar referências quebradas entre artefatos
- Criar arquivos `.regras-negocio.md` co-localizados
- Criar ou atualizar documentação de regras de negócio em `../../wiki/dev/<modulo>/`
- Gerar JSDoc em funções compartilhadas
- Extrair CSS para arquivo co-localizado
- Aplicar padrões de nomenclatura já definidos em rules

101
global/rules/ddd-documentacao-primeiro.md Normal file
View file

@ -0,0 +1,101 @@
---
type: rule
name: ddd-documentacao-primeiro
description: Regra global de Documentation-Driven Development (DDD) definindo os 6 pilares de documentação e memória no ecossistema.
scope: global
trigger: always_on
priority: alta
updatedAt: "2026-09-01"
---
# Regra: Documentação Obrigatória Antes da Implementação (DDD)
## Contexto
Implementar sem documentar leva ao acúmulo de conhecimento implícito, código inconsistente e perda de governança. Para garantir que as decisões de arquitetura, regras de negócio, interfaces e integrações estejam claras antes de qualquer código ser escrito, adotamos o **Documentation-Driven Development (DDD)**.
A documentação é a **especificação viva e o contrato formal** do que é construído.
---
## Os 6 Pilares Canônicos de Documentação e Memória
Todo desenvolvimento e manutenção no ecossistema deve obrigatoriamente respeitar a estrutura dos 6 pilares:
| Pilar | Destino / Padrão | Público | Conteúdo Obrigatório |
| :--- | :--- | :--- | :--- |
| **1. Código-Fonte** | `.ts`, `.vue`, `.js` | Desenvolvedores / IA | Comentários claros e coerentes quanto à sua aplicação prática, contexto e raciocínio de negócio (JSDoc no topo de funções, serviços e rotas). |
| **2. Ajuda na Tela (UI)** | `*-front/src/.../{componente}.ajuda.md` | Usuários da UI | Ajuda contextual co-localizada: para `modalX.vue`, o arquivo de ajuda **DEVE** ser `modalX.ajuda.md`. Detalha objetivo, botões, campos e instruções de uso. |
| **3. Wiki do Usuário** | `../../wiki/<modulo>/` | Usuários / Operadores | Aplicação VitePress com acesso dos usuários. Manuais de operação completos, tutoriais de uso, conceitos de negócio e fluxos da aplicação. |
| **4. Wiki de Desenvolvimento** | `../../wiki/dev/<modulo>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica detalhada, modelos de banco, regras de negócio (`{modulo}.regras-negocio.md`), fluxos de filas (BullMQ), CRONs e ADRs. |
| **5. Integração de IA** | Rota de Backend `/llm.md` | Agentes de IA / LLMs | Documentação gerada/servida dinamicamente contendo schemas Zod, enums canônicos, endpoints e contratos para consumo por LLMs. |
| **6. Memória das Ações da IA** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | Registros de sessões da IA, otimizações executadas, histórico de decisões arquiteturais e relatórios de aprimoramento contínuo. |
> ℹ️ **Estrutura da Wiki VitePress (`../../wiki`)**:
> - `../../wiki/<modulo>/` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes**.
> - `../../wiki/dev/<modulo>/` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**.
> 🧩 **Polimorfismo do `.agent` e Personalização por Projeto**:
> O repositório `.agent` é **polimórfico e genérico**, sendo compartilhado entre múltiplos projetos do ecossistema. Toda personalização de cada projeto reside em:
> - `./memorias-ia/` (na raiz do projeto pai): Registros de ações, sessões e decisões da IA.
> - `../../wiki/<modulo>/`: Documentação do módulo com acesso dos usuários (VitePress).
> - `../../wiki/dev/<modulo>/`: Documentação técnica do módulo com acesso interno dev (VitePress).
---
## Protocolo DDD
Para toda nova demanda, módulo ou funcionalidade, execute os passos abaixo:
1. **Identificar os Pilares Impactados**:
- É alteração de código? $\rightarrow$ Planejar comentários contextuais claros (Pilar 1).
- É tela/modal com ajuda ao usuário? $\rightarrow$ Criar/atualizar `modalX.ajuda.md` co-localizado (Pilar 2).
- É funcionalidade com impacto no usuário final? $\rightarrow$ Criar/atualizar documentação em `../../wiki/<modulo>/` (Pilar 3).
- É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `../../wiki/dev/<modulo>/` (Pilar 4).
- É endpoint, schema ou contrato de API? $\rightarrow$ Assegurar reflexão na rota `/llm.md` (Pilar 5).
- É ação estruturante ou otimização de IA? $\rightarrow$ Registrar memória em `<base_projeto>/memorias-ia/` (Pilar 6).
2. **Documentar Antes de Codar**:
- Redigir a documentação preliminar nos respectivos destinos e templates antes de iniciar a implementação.
3. **Apresentar ao Operador**:
- Validar as especificações e regras com o operador antes de codificar.
4. **Implementar**:
- Escrever o código de forma que satisfaça estritamente a documentação validada.
5. **Validar e Sincronizar**:
- Se a implementação revelar necessidade de ajustes de design, atualizar a documentação imediatamente para manter 100% de sincronismo.
---
## Exceções
A etapa de documentação prévia pode ser simplificada apenas para:
- Correção de typos pontuais.
- Formatação ou linting sem alteração de lógica.
- Ajustes triviais de imports.
---
## Exemplos
✅ **Correto**:
- Criou um novo modal `ModalParametros.vue` $\rightarrow$ criou `ModalParametros.ajuda.md` na mesma pasta explicando campos e botões para o usuário.
- Criou um serviço de cálculo de efluentes $\rightarrow$ inseriu JSDoc claro quanto à sua aplicação prática, documentou a regra técnica em `../../wiki/dev/e-licencie.sigma/` e o guia de uso em `../../wiki/e-licencie.sigma/`.
- Criou endpoints novos no backend $\rightarrow$ rota `/llm.md` atualizada automaticamente via gerador de contratos.
- Realizou otimização no ecossistema de agentes $\rightarrow$ registrou relatório em `<base_projeto>/memorias-ia/`.
❌ **Incorreto**:
- Criou `modalX.vue` e colocou ajuda em formato desconhecido ou fora da pasta do componente.
- Implementou código sem comentários ou com JSDoc que apenas repete os tipos sem explicar a aplicação real no sistema.
- Criou regras técnicas complexas sem atualizar `../../wiki/dev/<modulo>/`.
- Gravou registros de ações da IA em pastas despadronizadas fora de `<base_projeto>/memorias-ia/`.
---
## Referências
- `DOCUMENTACAO/README` (Manifesto DDD e matriz de documentação)
- Rules: `jsdoc-padrao.md`, `regras-negocio-md.md`, `autonomia-agente.md`
- Skills: `adicionar-ajuda`, `documentar-dominio-modulo`, `documentar-decisao-tecnica`, `diagnosticar-lacunas-documentacao`

106
global/rules/jsdoc-padrao.md
View file

@ -1,59 +1,115 @@
---
type: rule
name: jsdoc-padrao
description: Padrões de documentação em código (JSDoc, casts temporários e TODOs estruturados)
description: Padrões de documentação em código-fonte (comentários claros e coerentes quanto à aplicação, JSDoc, casts e TODOs).
scope: global
trigger: file_match
globs:
- "**/*.ts"
- "**/*.tsx"
- "**/*.vue"
updatedAt: "2026-06-01"
- "**/*.js"
updatedAt: "2026-09-01"
---
# Regra: Documentação em Código
# Regra: Documentação e Comentários no Código-Fonte
## 1. JSDoc — Princípios
## 1. Princípio Fundamental
- **Por que, não o Quê**: documente o raciocínio, não o mecanismo que o TypeScript já expressa.
- **Nomenclatura limpa**: confie em nomes expressivos antes de comentários.
> **O código-fonte deve receber comentários claros e coerentes quanto à sua aplicação.**
## 2. JSDoc obrigatório em funções compartilhadas
Comentários no código-fonte não existem para descrever o óbvio sintático (que a tipagem TypeScript já fornece), mas sim para **explicar o propósito prático, o contexto operacional no sistema e as regras de negócio** que regem aquela função, método, componente ou rota.
Toda função central ou de uso compartilhado deve ter cabeçalho JSDoc:
---
## 2. JSDoc Obrigatório em Funções, Serviços, Rotas e Composables
Toda função central, serviço de negócio (`servicos/`), endpoint/rota (`rotas/`), query de banco (`banco/`), composable (`composables/`) ou método compartilhado deve possuir cabeçalho JSDoc com:
1. **Descrição da Aplicação Prática**: Para que serve no sistema e em quais cenários operacionais é utilizada.
2. **Contexto de Negócio / Regras**: Restrições, validações críticas e impactos em outras partes da aplicação.
3. **Parâmetros (`@param`)**: Significado contextual de cada parâmetro (não apenas repetir o nome).
4. **Retorno (`@returns`)**: Estrutura e significado do valor retornado em sucesso ou falha/nulo.
5. **Efeitos Colaterais / Exceções (`@throws`)**: Filas disparadas, transações, logs ou erros esperados.
### Exemplo Correto ✅
```typescript
/**
* Busca detalhes da entidade e calcula privilégios aplicáveis.
* Não utilizar em processamento em lote para evitar sobrecarga.
* Calcula o balanço volumétrico e a carga de efluentes tratados para o período informado.
* Aplica as diretrizes da Resolução CONAMA nº 430/2011 e regras de tolerância do ponto de descarte.
*
* @param tenantId - Identificador do tenant no sistema
* @param entityId - ID do registro na base de dados
* @returns Objeto consolidado ou `null` se não encontrado
* Aplicação: Utilizado na geração do relatório mensal e no cálculo de conformidade antes do envio de alertas.
*
* @param tenantId - Identificador do empreendimento no sistema
* @param pontoId - ID do ponto de monitoramento cadastrado
* @param periodo - Intervalo de datas para consolidação das leituras
* @returns Balanço consolidado contendo vazão média, picos e índice de conformidade
* @throws {ErroValidacaoParametros} Se o ponto não possuir medições no período
*/
export const obterDetalhes = async (tenantId: string, entityId: string) => { ... }
export const calcularBalancoEfluentes = async (
tenantId: string,
pontoId: string,
periodo: IntervaloDatas
): Promise<BalancoConsolidado> => { ... }
```
## 3. Casts temporários — justificativa obrigatória
Coerções agressivas requerem comentário explicando o porquê:
### Exemplo Incorreto ❌
```typescript
// Necessário: biblioteca externa não provê tipagem genérica na versão atual
const dados = payload.raw as unknown as RespostaFormatada
/**
* Calcula efluentes.
* @param tenantId string
* @param pontoId string
* @param periodo object
*/
export const calcularBalancoEfluentes = async (...) => { ... }
```
## 4. TODOs estruturados
---
Dívida técnica ou dúvida de negócio deve seguir formato padronizado:
## 3. Comentários Inline Contextuais e Expressivos
- **Tipagem**: `// TODO de tipagem: Criar interface para o retorno da API`
- **Negócio**: `// TODO de regra: Validar com Produto se taxa se aplica a clientes antigos`
Use comentários inline (`//`) para esclarecer:
- Decisões de cálculo e fórmulas não-triviais.
- Tratamento de casos de borda e regras de exceção.
- Ordem de execução de passos críticos (ex: pipeline de transformação de dados).
```typescript
// Regra: se o pH estiver fora da faixa 6.0-9.0, o registro é marcado como não-conforme
const estaConforme = leitura.ph >= 6.0 && leitura.ph <= 9.0
```
---
## 4. Casts Temporários — Justificativa Obrigatória
Qualquer coerção de tipo (`as unknown as T`, `as T`) exige comentário explicando o motivo técnico:
```typescript
// Necessário: biblioteca de terceiros não exporta a tipagem dos metadados na v2
const metadados = resposta.raw as unknown as MetadadosConexao
```
---
## 5. TODOs Estruturados
Dívidas técnicas ou dúvidas de negócio devem ser registradas de forma padronizada:
- **Tipagem**: `// TODO de tipagem: Migrar retorno bruto para schema Zod zBalancoRetorno`
- **Negócio**: `// TODO de regra: Confirmar com Operador se tolerância de DBO aplica-se a descarte pluvial`
---
## Impacto
Sem este padrão, funções compartilhadas ficam sem documentação, casts aparecem sem justificativa, e TODOs são inconsistentes e difíceis de buscar.
Código autoexplicativo e devidamente contextualizado acelera a manutenção, evita regressões de regras e permite que desenvolvedores e agentes de IA compreendam instantaneamente o impacto de qualquer alteração.
---
## Referências
- Rule: `global/rules/typescript-sem-any`
- Rule: `rules/ddd-documentacao-primeiro.md`
- Rule: `rules/regras-negocio-md.md`
- Rule: `rules/typescript-sem-any.md`

102
global/rules/regras-negocio-md.md
View file

@ -1,120 +1,120 @@
---
type: rule
name: regras-negocio-md
description: Arquivo {modulo}.regras-negocio.md obrigatório para módulos com lógica complexa
description: O conteúdo de regras de negócio deve ficar em ../../wiki/dev/<modulo>/.
scope: global
trigger: always_on
updatedAt: "2026-06-01"
updatedAt: "2026-09-01"
---
# Regra: Arquivo `{modulo}.regras-negocio.md` Obrigatório para Módulos com Lógica Complexa
# Regra: Conteúdo de Regras de Negócio em `../../wiki/dev/<modulo>/`
> **Escopo global** — aplica-se a todos os projetos do ecossistema Azteca.
## Contexto
Qualquer arquivo TypeScript que contenha lógica de negócio não-trivial — múltiplas regras de decisão, critérios de bloqueio, estratégias de processamento — deve ter suas regras documentadas em linguagem natural em um arquivo Markdown co-localizado.
Toda lógica de negócio não-trivial — regras de decisão, critérios de bloqueio, estratégias de processamento, priorizações e fluxos de dados — deve ter seu conteúdo documentado em linguagem natural na **Wiki de Desenvolvimento** em `../../wiki/dev/<modulo>/`.
Isso garante que produto, suporte e desenvolvimento possam entender as regras sem precisar ler TypeScript, e que o agente de IA encontre rapidamente os critérios corretos antes de alterar qualquer código.
> 💡 **Aplicação VitePress (`../../wiki`)**: O diretório `../../wiki` é uma aplicação VitePress na qual `../../wiki/<modulo>/` é voltado ao acesso dos **usuários**, e `../../wiki/dev/<modulo>/` é reservado ao **acesso interno exclusivo da equipe de desenvolvimento**.
Isso garante centralização, governança técnica e facilidade de consulta por desenvolvedores, arquitetos e agentes de IA.
---
## Regra
**Todo módulo com lógica de negócio não-trivial DEVE ter um arquivo `{modulo}.regras-negocio.md` co-localizado.**
**Todo o conteúdo detalhado de regras de negócio DEVE ficar em `../../wiki/dev/<modulo>/`.**
Considera-se lógica não-trivial qualquer módulo que:
- possui 3 ou mais critérios de decisão distintos
- realiza eleição/priorização entre registros
- aplica diferentes estratégias por tipo de dado
- pode resultar em revisão manual (caminho alternativo ao fluxo automático)
- é consumido por CRON, worker ou importador automático
- Possui 3 ou mais critérios de decisão distintos
- Realiza eleição/priorização entre registros
- Aplica diferentes estratégias por tipo de dado
- Pode resultar em revisão manual (caminho alternativo ao fluxo automático)
- É consumido por CRON, worker ou importador automático
O módulo TypeScript deve conter, na primeira linha do arquivo, a referência:
O módulo TypeScript deve conter, na primeira linha útil do arquivo, a referência:
```typescript
// Regras de negócio: ver {modulo}.regras-negocio.md
// Regras de negócio: ver ../../wiki/dev/<modulo>/{modulo}.regras-negocio.md
```
O arquivo `.md` é a **fonte de verdade**. Os JSDoc do código devem referenciar o `.md`, não duplicá-lo.
A documentação na **Wiki de Desenvolvimento** é a **fonte de verdade da lógica operacional**. Os comentários JSDoc no código explicam a aplicação prática da função e apontam para a wiki para o detalhamento dos critérios.
## Estrutura Obrigatória do Arquivo
---
## Estrutura do Documento de Regras na Wiki de Desenvolvimento
**Localização:** `../../wiki/dev/<modulo>/` (ex.: `../../wiki/dev/e-licencie.sigma/regras-negocio/` ou `../../wiki/dev/e-licencie.sigma/{modulo}.regras-negocio.md`)
```markdown
# Regras de Negócio — [Nome do Módulo]
# Regras de Negócio — [Nome do Módulo / Serviço]
Módulo: `_arquivo.ts`
Localização: `caminho/relativo/ao/arquivo`
Módulo TypeScript: `_arquivo.ts`
Localização no Código: `caminho/relativo/ao/arquivo`
---
## Contexto
Por que este módulo existe, qual problema resolve.
Por que este módulo existe, qual problema operacional resolve.
## Critérios de Entrada / Identificação
O que aciona o módulo, quais dados recebe, filtros aplicados.
## Regras de Processamento
As regras numeradas em ordem de avaliação.
As regras numeradas em ordem estrita de avaliação.
## Casos de Revisão Manual (quando aplicável)
Quando o processamento automático não pode prosseguir.
## Estratégia de Fusão / Resultado (quando aplicável)
O que o módulo produz, como campos são combinados.
## Estratégia de Fusão / Persistência (quando aplicável)
O que o módulo produz, como campos são combinados ou persistidos.
## Dependências Externas
Tabelas, filas, serviços externos tocados pelo módulo.
Tabelas, filas BullMQ, rotas e serviços externos tocados pelo módulo.
```
---
## Exemplos
✅ **Correto** — referência no topo do módulo, regras no `.md`:
✅ **Correto** — referência no topo do módulo apontando para a Wiki de Desenvolvimento:
```typescript
// Regras de negócio: ver juntar_execucoes.regras-negocio.md
// Regras de negócio: ver ../../wiki/dev/e-licencie.sigma/juntar_execucoes.regras-negocio.md
import { ... } from "..."
/**
* Consolida execuções de condicionantes com base nas datas de vencimento.
* Aplicação: Processamento noturno de auditoria e saneamento de agenda.
*/
export const compilarJuntarExecucoes = async (...) => {
// implementação conforme regras-negocio.md
// implementação conforme a Wiki de Desenvolvimento
}
```
❌ **Errado** — regras embutidas no código como comentário de bloco:
❌ **Errado** — regras embutidas no código como comentário gigante ou arquivos soltos fora da wiki:
```typescript
/**
* Regras de negócio:
* [x] Pode ter apenas uma execução por data de vencimento.
* [x] Se tiver apenas uma execução consolidada → ela é a principal.
* ...
*/
```
❌ **Errado** — JSDoc duplicando as regras em vez de referenciar o `.md`:
```typescript
/**
* Retorna false quando:
* - vencimentos divergentes
* - executada com datas distintas
* - vencimento_prorrogado distintos
* ...
*/
```
---
## Impacto
Sem este padrão:
- Regras de negócio ficam implícitas no código ou em JSDoc que envelhece sem controle
- O agente de IA precisa inferir regras do código ao invés de lê-las diretamente
- Produto e suporte não conseguem validar o comportamento sem ajuda técnica
- Mudanças de regra geram JSDoc desatualizado espalhado pelo código
- Centralização de todo o conhecimento técnico e operacional na Wiki de Desenvolvimento.
- Regras de negócio claras para humanos e IAs sem poluir o código-fonte.
- Mudanças de regras são auditáveis e versionadas na documentação do repositório.
## Aplicação
- Módulos de CRON com lógica de auditoria/fusão
- Importadores automáticos (ex: importação de licenças via IA)
- Workers de processamento em lote
- Qualquer utilitário com lógica de decisão multi-critério
---
## Referências
- Skill: `global/skills/documentar-regras-negocio/SKILL`
- Workflow: `global/workflows/documentar-regras-negocio`
- Rule: `rules/ddd-documentacao-primeiro.md`
- Rule: `rules/jsdoc-padrao.md`
- Skill: `skills/documentar-regras-negocio/SKILL.md`
- Workflow: `global/workflows/documentar-regras-negocio.md`
- Wiki de Desenvolvimento: `../../wiki/dev/<modulo>/`