versão 1

agents/ag-documentacao/rules/escrita-natural.md

@@ -0,0 +1,169 @@
+---
+type: rule
+name: escrita-natural
+trigger: context_match
+description: Garantir escrita natural, fluida e humana em textos comerciais e de comunicação, evitando linguagem robótica ou excessivamente genérica.
+scope: global
+updatedAt: "2026-06-01"
+ativacao: >
+  Aplicar quando o agente estiver produzindo textos comerciais, de marketing,
+  orçamentos, propostas, reels ou qualquer comunicação voltada ao público externo.
+  NÃO aplicar em documentação técnica (ADRs, rules, JSDoc, regras de negócio).
+---
+
+# Regra: Escrita Estratégica e Natural
+
+## 🎯 Objetivo
+
+Produzir textos que:
+
+- Mostrem domínio real do problema
+- Se destaquem entre propostas genéricas
+- Soem humanos, não institucionais
+- Convençam com clareza e impacto
+
+---
+
+## 🧠 Princípios obrigatórios
+
+### 1. Começar pelo problema real
+
+Evitar introduções genéricas.
+
+❌
+"O presente projeto tem como objetivo..."
+
+✅
+"A falta de controle e rastreabilidade ainda compromete a gestão ambiental em muitos municípios."
+
+---
+
+### 2. Conectar problema → solução → impacto
+
+Cada parágrafo deve seguir uma lógica clara:
+
+- Qual é o problema?
+- Como a solução resolve?
+- O que muda na prática?
+
+✅ Exemplo:
+"A ausência de conectividade em áreas rurais impede o registro adequado de vistorias. A solução permite coleta offline diretamente no celular. Como resultado, elimina perda de informação e reduz retrabalho."
+
+---
+
+### 3. Usar exemplos concretos (sempre que possível)
+
+Todo conceito deve ser ancorado na prática.
+
+❌
+"A solução permite coleta de dados estruturados."
+
+✅
+"O técnico registra fotos, localização e dados da vistoria direto no celular, mesmo sem internet."
+
+---
+
+### 4. Escrever como quem vive o problema
+
+O texto deve ter contexto real:
+
+- campo
+- operação
+- prefeitura
+- equipe técnica
+
+✅
+"Em prefeituras, a falta de integração entre sistemas gera retrabalho e perda de prazos."
+
+---
+
+### 5. Persuasão baseada em impacto real
+
+Evitar adjetivos vazios.
+
+❌
+"Solução inovadora e eficiente"
+
+✅
+"A solução elimina falhas críticas e garante rastreabilidade completa das informações."
+
+---
+
+### 6. Linguagem natural (sem burocracia)
+
+Preferir:
+
+- "Com a solução..."
+- "Na prática..."
+- "Isso permite..."
+- "Como resultado..."
+
+Evitar:
+
+- "Dessa forma"
+- "Destarte"
+- "O presente projeto"
+
+---
+
+### 7. Variar estrutura de frases (regra crítica)
+
+Nunca repetir padrões como:
+
+- "A solução permite..."
+- "O sistema permite..."
+
+Alternar com:
+
+- "Na prática, o técnico..."
+- "Com isso..."
+- "Isso reduz..."
+- "Como resultado..."
+
+---
+
+### 8. Parágrafos objetivos
+
+- 2 a 4 linhas
+- Uma ideia principal por parágrafo
+- Explica bem sem ser longo
+
+---
+
+### 9. Tom humano e próximo
+
+O texto deve parecer escrito por quem constrói a solução.
+
+✅
+"A solução resolve um problema real que impacta o dia a dia das equipes."
+
+---
+
+## 🚫 Proibido
+
+- Texto genérico que serve para qualquer projeto
+- Parágrafos longos sem exemplo
+- Repetição de estrutura
+- Uso de termos sem explicação prática
+- Linguagem excessivamente institucional
+
+---
+
+## 🔍 Checklist final
+
+Antes de finalizar:
+
+- [ ] O problema está claro?
+- [ ] Existe exemplo prático?
+- [ ] O impacto está explícito?
+- [ ] O texto soa humano?
+- [ ] Há repetição de estrutura?
+- [ ] Parece algo real ou genérico?
+
+---
+
+## 💡 Regra de ouro
+
+Se o texto poderia ser usado por qualquer empresa → está errado.
+
+Se parece que vem de quem vive o problema → está certo.

agents/ag-documentacao/rules/jsdoc-padrao.md

@@ -0,0 +1,59 @@
+---
+type: rule
+name: jsdoc-padrao
+description: Padrões de documentação em código (JSDoc, casts temporários e TODOs estruturados)
+scope: global
+trigger: file_match
+globs:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.vue"
+updatedAt: "2026-06-01"
+---
+
+# Regra: Documentação em Código
+
+## 1. JSDoc — Princípios
+
+- **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.
+
+## 2. JSDoc obrigatório em funções compartilhadas
+
+Toda função central ou de uso compartilhado deve ter cabeçalho JSDoc:
+
+```typescript
+/**
+ * Busca detalhes da entidade e calcula privilégios aplicáveis.
+ * Não utilizar em processamento em lote para evitar sobrecarga.
+ *
+ * @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
+ */
+export const obterDetalhes = async (tenantId: string, entityId: string) => { ... }
+```
+
+## 3. Casts temporários — justificativa obrigatória
+
+Coerções agressivas requerem comentário explicando o porquê:
+
+```typescript
+// Necessário: biblioteca externa não provê tipagem genérica na versão atual
+const dados = payload.raw as unknown as RespostaFormatada
+```
+
+## 4. TODOs estruturados
+
+Dívida técnica ou dúvida de negócio deve seguir formato padronizado:
+
+- **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`
+
+## 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.
+
+## Referências
+
+- Rule: `.agent/rules/typescript-sem-any.global.md`