@maestro-ai/cli 1.0.0

package/content/prompts/escalabilidade/analise-performance.md

@@ -0,0 +1,240 @@
+# Prompt: Análise de Performance e Escalabilidade
+
+> **Quando usar**: Após implementação inicial, antes de ir para produção, ou ao identificar gargalos
+> **Especialista**: [Performance e Escalabilidade](../../02-especialistas/Especialista%20em%20Performance%20e%20Escalabilidade.md)
+> **Nível**: Médio a Complexo
+
+---
+
+## Fluxo de Contexto
+
+Antes de usar este prompt, tenha em mãos:
+- `docs/CONTEXTO.md` - Entendimento atual do projeto
+- `docs/05-arquitetura/arquitetura.md` - Arquitetura do sistema
+- Métricas atuais (se existirem)
+
+Após gerar, salve o resultado em:
+- `docs/07-performance/analise-performance.md`
+
+---
+
+## Prompt Completo
+
+```text
+Atue como engenheiro de performance sênior.
+
+## Contexto do Projeto
+
+[COLE O CONTEÚDO DE docs/CONTEXTO.md]
+
+## Arquitetura Atual
+
+Arquitetura: [DESCREVA COMPONENTES - API, Frontend, Banco, Cache, etc]
+Stack: [TECNOLOGIAS USADAS]
+Banco de dados: [TIPO, TAMANHO ESTIMADO DOS DADOS]
+Infraestrutura: [Cloud provider, containers, serverless, etc]
+
+## Requisitos de Performance
+
+Usuários esperados: [NÚMERO DE USUÁRIOS SIMULTÂNEOS]
+Requests/segundo esperados: [NÚMERO]
+SLA desejado: [LATÊNCIA p95, UPTIME %]
+
+## Endpoints Críticos
+
+[LISTE OS 3-5 ENDPOINTS MAIS IMPORTANTES]
+- [Endpoint 1]: [Descrição e frequência de uso]
+- [Endpoint 2]: [Descrição e frequência de uso]
+
+---
+
+## Sua Missão
+
+Analise e proponha otimizações de performance e escalabilidade:
+
+### 1. Análise de Gargalos
+
+#### 1.1 Database
+- Queries potencialmente problemáticas
+- Necessidade de índices
+- N+1 queries
+- Connection pool sizing
+- Locks e deadlocks potenciais
+
+#### 1.2 Application
+- CPU-bound vs I/O-bound operations
+- Memory leaks potenciais
+- Concurrency issues
+- Bloqueios síncronos desnecessários
+- Cold starts (se serverless)
+
+#### 1.3 Network
+- Latência entre serviços
+- Payload sizes (compressão)
+- Número de roundtrips
+- DNS lookups
+
+#### 1.4 Frontend (se aplicável)
+- Bundle size
+- Imagens e assets
+- Render blocking resources
+
+### 2. Estratégia de Caching
+
+#### 2.1 O que cachear
+- Dados que mudam raramente
+- Queries frequentes e custosas
+- Sessões e autenticação
+- Respostas de APIs externas
+
+#### 2.2 Onde cachear
+| Camada | Tecnologia | Casos de Uso |
+|--------|------------|--------------|
+| Application | In-memory | Hot data |
+| Distributed | Redis/Memcached | Sessões, queries |
+| CDN | CloudFlare/CloudFront | Assets, páginas |
+| Browser | Cache headers | Assets estáticos |
+
+#### 2.3 Cache Policies
+- TTL por tipo de dado
+- Estratégia de invalidação (write-through, write-behind, cache-aside)
+- Handling de cache miss thundering herd
+
+### 3. Escalabilidade
+
+#### 3.1 Horizontal Scaling (Scale Out)
+- Quais componentes escalam horizontalmente
+- Como manter estado (stateless vs stateful)
+- Session affinity considerations
+- Load balancing strategy
+
+#### 3.2 Database Scaling
+- Read replicas
+- Sharding (se necessário)
+- Connection pooling (PgBouncer, ProxySQL)
+- Particionamento de tabelas
+
+#### 3.3 Auto-scaling
+| Métrica | Threshold | Ação |
+|---------|-----------|------|
+| CPU | > X% | Scale up |
+| Memory | > Y% | Scale up |
+| Queue depth | > Z | Add workers |
+| Response time | > Wms | Scale out |
+
+- Cooldown periods
+- Minimum/Maximum instances
+
+### 4. Performance Targets (SLOs)
+
+| Endpoint/Fluxo | Latência p50 | Latência p95 | Throughput |
+|----------------|--------------|--------------|------------|
+| [Endpoint 1] | < Xms | < Yms | Z req/s |
+| [Endpoint 2] | < Xms | < Yms | Z req/s |
+
+### 5. Query Optimization
+
+Para as queries mais críticas, sugira:
+- Índices necessários
+- Query rewrites
+- Explain analyze interpretation
+
+### 6. Plano de Load Test
+
+- Cenários a testar (ramp-up, spike, soak)
+- Ferramentas sugeridas (k6, Locust, Artillery)
+- Métricas a monitorar durante teste
+- Baseline vs target
+
+### 7. Quick Wins vs Long Term
+
+| Otimização | Esforço | Impacto | Prioridade |
+|------------|---------|---------|------------|
+| [Otimização 1] | Baixo | Alto | ⭐⭐⭐ |
+| [Otimização 2] | Médio | Alto | ⭐⭐⭐ |
+| [Otimização 3] | Alto | Médio | ⭐⭐ |
+```
+
+---
+
+## Exemplo de Uso
+
+```text
+Atue como engenheiro de performance sênior.
+
+## Contexto do Projeto
+
+Marketplace de serviços locais com agendamento online.
+
+## Arquitetura Atual
+
+Arquitetura: 
+- Frontend: Next.js na Vercel
+- API: NestJS em containers no ECS
+- Banco: PostgreSQL RDS (db.t3.medium)
+- Cache: Nenhum atualmente
+
+Stack: Node.js 18, TypeScript, Prisma ORM
+Banco de dados: PostgreSQL 15, ~50GB de dados esperados
+Infraestrutura: AWS (ECS, RDS, ALB)
+
+## Requisitos de Performance
+
+Usuários esperados: 1000 simultâneos no pico
+Requests/segundo esperados: 200
+SLA desejado: p95 < 300ms, 99.9% uptime
+
+## Endpoints Críticos
+
+- GET /api/profissionais?cidade=X: Listagem de prestadores (~40% do tráfego)
+- POST /api/agendamentos: Criação de agendamento (~15% do tráfego)
+- GET /api/agenda/:id/disponibilidade: Horários livres (~30% do tráfego)
+```
+
+---
+
+## Resposta Esperada
+
+### Gargalos Identificados
+
+1. **Query de listagem** - Falta índice em `cidade` + `ativo`
+2. **Disponibilidade** - Consulta completa para calcular, deveria ser pré-computada
+3. **Sessões** - Stored in DB, should be Redis
+4. **Sem cache** - Queries repetidas a cada request
+
+### Cache Strategy
+
+| Dado | Onde | TTL | Invalidação |
+|------|------|-----|-------------|
+| Lista de profissionais | Redis | 5min | On update |
+| Disponibilidade | Redis | 1min | On agendamento |
+| Sessão | Redis | 1h | On logout |
+| Assets | CDN | 1 semana | Deploy hash |
+
+### Scaling
+
+- **API**: 2-10 pods, HPA on CPU > 70%
+- **Database**: 1 primary + 2 read replicas
+- **Redis**: ElastiCache cluster mode
+
+### Quick Wins
+
+| Otimização | Esforço | Impacto |
+|------------|---------|---------|
+| Adicionar Redis para sessões | 2h | Alto |
+| Índice em cidade+ativo | 30min | Alto |
+| Cache de listagem | 4h | Alto |
+| Read replica para queries | 2h | Médio |
+
+---
+
+## Checklist Pós-Geração
+
+- [ ] Gargalos identificados por camada (DB, App, Network)
+- [ ] Estratégia de cache definida (o quê, onde, TTL)
+- [ ] Índices sugeridos para queries críticas
+- [ ] Thresholds de auto-scaling definidos
+- [ ] SLOs documentados por endpoint
+- [ ] Quick wins priorizados
+- [ ] Plano de load test sugerido
+- [ ] Salvar em `docs/07-performance/analise-performance.md`

package/content/prompts/escalabilidade/analise-performance.txt

@@ -0,0 +1,94 @@
+Atue como engenheiro de performance sênior.
+
+Sistema:
+- Arquitetura: [DESCREVA]
+- Stack: [TECNOLOGIAS]
+- Banco: [TIPO E TAMANHO]
+- Usuários esperados: [NÚMERO]
+- Requests/segundo esperados: [NÚMERO]
+
+Analise e proponha otimizações de performance e escalabilidade:
+
+## 1. Análise de Gargalos
+
+### 1.1 Database
+- Queries potencialmente problemáticas
+- Necessidade de índices
+- N+1 queries
+- Connection pool sizing
+
+### 1.2 Application
+- CPU-bound vs I/O-bound
+- Memory leaks potenciais
+- Concurrency issues
+
+### 1.3 Network
+- Latência entre serviços
+- Payload sizes
+- Número de roundtrips
+
+## 2. Estratégia de Caching
+
+### 2.1 O que cachear
+- Dados que mudam raramente
+- Queries frequentes
+- Sessões/auth
+
+### 2.2 Onde cachear
+- Application level
+- Redis/Memcached
+- CDN (assets estáticos)
+
+### 2.3 TTL e Invalidação
+- Tempo de expiração por tipo
+- Estratégia de invalidação
+
+## 3. Escalabilidade
+
+### 3.1 Horizontal Scaling
+- Quais componentes escalam
+- Como manter estado (stateless)
+- Load balancing
+
+### 3.2 Database Scaling
+- Read replicas
+- Sharding (se necessário)
+- Connection pooling
+
+### 3.3 Auto-scaling
+- Métricas de trigger
+- Thresholds
+- Cooldown periods
+
+## 4. Performance Targets (SLOs)
+
+| Endpoint/Fluxo | Latência p95 | Throughput |
+|---|---|---|
+| [Endpoint 1] | < Xms | Y req/s |
+
+## 5. Plano de Load Test
+
+- Cenários a testar
+- Ferramentas sugeridas
+- Métricas a monitorar
+
+---
+
+## Resposta Esperada (Resumo)
+
+### Gargalos Identificados
+1. **Query de listagem** - Falta índice em `created_at`
+2. **Uploads** - Bloqueiam thread principal
+3. **Sessões** - Stored in DB, should be Redis
+
+### Cache Strategy
+| Dado | Onde | TTL | Invalidação |
+|---|---|---|---|
+| Lista de produtos | Redis | 5min | On update |
+| Sessão | Redis | 1h | On logout |
+| Assets | CDN | 1d | Deploy |
+
+### Scaling
+- API: 2-10 pods, HPA on CPU > 70%
+- Database: 1 primary + 2 read replicas
+- Redis: Cluster mode for high availability

package/content/prompts/escalabilidade/caching.md

@@ -0,0 +1,255 @@
+# Prompt: Estratégias de Cache
+
+> **Prioridade**: 🟡 MÉDIA  
+> **Aplicável a**: APIs com alta carga, dados lidos frequentemente
+
+---
+
+## Prompt Base: Projetar Cache
+
+```text
+Atue como engenheiro de performance.
+
+Tenho um sistema com:
+- Stack: [ex. Node.js + PostgreSQL + Redis]
+- Tráfego: [ex. 1000 req/s, 80% leitura, 20% escrita]
+- Dados: [ex. catálogo de 50k produtos, users sessions, configurações]
+- Latência atual: [ex. p95 = 500ms]
+- Meta: [ex. p95 < 100ms]
+
+Para cada tipo de dado, recomende:
+
+1. **Padrão de Cache**
+   - Cache-aside, write-through, read-through, ou combinação
+   - Justificativa
+
+2. **TTL e Invalidação**
+   - Tempo de vida sugerido
+   - Estratégia de invalidação (explícita, event-driven, TTL puro)
+
+3. **Estrutura no Redis**
+   - Tipo de dado Redis (string, hash, set, sorted set)
+   - Naming convention para keys
+   - Exemplos de comandos
+
+4. **Código de Implementação**
+   - Cache layer reutilizável
+   - Decorators ou helpers
+   - Tratamento de cache miss e falha do Redis
+
+5. **Métricas**
+   - O que monitorar
+   - Alertas recomendados
+```
+
+---
+
+## Prompt: Cache para Endpoint Específico
+
+```text
+Tenho este endpoint que é lento:
+[COLE CÓDIGO DO ENDPOINT]
+
+Métricas atuais:
+- Latência: [ex. p95 = 800ms]
+- Chamadas/dia: [ex. 100k]
+- Taxa de mudança dos dados: [ex. atualizam 1x por hora]
+
+Gere:
+1. Análise do que pode ser cacheado
+2. Implementação com cache-aside
+3. Estratégia de invalidação
+4. Código refatorado
+5. Testes para validar cache hit/miss
+```
+
+---
+
+## Prompt: Invalidação de Cache
+
+```text
+Tenho o seguinte cenário de cache:
+- Entidades: [ex. User, Order, Product]
+- Relacionamentos: [ex. User tem Orders, Order tem Products]
+- Caches atuais: [ex. user:123, user:123:orders, product:456]
+
+Quando um User é atualizado, preciso invalidar: [DESCREVA]
+
+Projete uma estratégia de invalidação que:
+1. Garanta consistência
+2. Minimize invalidações desnecessárias
+3. Use eventos/pub-sub se benéfico
+4. Documente quais eventos afetam quais caches
+```
+
+---
+
+## Prompt: Cache Multi-Layer
+
+```text
+Quero implementar cache em múltiplas camadas:
+1. Browser/CDN (edge)
+2. Application (in-memory)
+3. Distributed (Redis)
+4. Database (query cache)
+
+Para estes endpoints:
+[LISTE ENDPOINTS E CARACTERÍSTICAS]
+
+Gere:
+1. Estratégia por camada
+2. Headers HTTP para cache de browser/CDN
+3. Código para cache in-memory + Redis
+4. Quando usar cada camada
+5. Como invalidar coordenadamente
+```
+
+---
+
+## Prompt: Resolver Cache Stampede
+
+```text
+Estou tendo problemas de cache stampede:
+- Cenário: [ex. muitos requests simultâneos no cache miss]
+- Impacto: [ex. banco sobrecarrega, timeout em cascata]
+
+Stack: [DESCREVA]
+
+Implemente:
+1. Lock de requisição única (singleflight)
+2. Probabilistic early expiration
+3. Fallback para stale data durante refresh
+4. Código completo com testes
+```
+
+---
+
+## Exemplo: Cache Layer Genérico
+
+```typescript
+// src/cache/cacheLayer.ts
+import Redis from 'ioredis';
+
+interface CacheOptions {
+  ttl?: number;           // segundos
+  staleWhileRevalidate?: boolean;
+  lockTimeout?: number;   // ms
+}
+
+class CacheLayer {
+  private redis: Redis;
+  private locks = new Map<string, Promise<any>>();
+  
+  constructor(redis: Redis) {
+    this.redis = redis;
+  }
+
+  async get<T>(
+    key: string, 
+    fetcher: () => Promise<T>, 
+    options: CacheOptions = {}
+  ): Promise<T> {
+    const { ttl = 3600, staleWhileRevalidate = false, lockTimeout = 5000 } = options;
+
+    // 1. Tentar cache
+    const cached = await this.redis.get(key);
+    if (cached) {
+      const data = JSON.parse(cached);
+      
+      // SWR: retornar stale e atualizar em background
+      if (staleWhileRevalidate && this.isNearExpiry(key)) {
+        this.refreshInBackground(key, fetcher, ttl);
+      }
+      
+      return data;
+    }
+
+    // 2. Prevenir stampede com lock
+    if (this.locks.has(key)) {
+      return this.locks.get(key);
+    }
+
+    // 3. Buscar com timeout
+    const promise = this.fetchWithLock(key, fetcher, ttl, lockTimeout);
+    this.locks.set(key, promise);
+    
+    try {
+      return await promise;
+    } finally {
+      this.locks.delete(key);
+    }
+  }
+
+  async invalidate(key: string): Promise<void> {
+    await this.redis.del(key);
+  }
+
+  async invalidatePattern(pattern: string): Promise<void> {
+    const keys = await this.redis.keys(pattern);
+    if (keys.length > 0) {
+      await this.redis.del(...keys);
+    }
+  }
+
+  private async fetchWithLock<T>(
+    key: string, 
+    fetcher: () => Promise<T>, 
+    ttl: number,
+    timeout: number
+  ): Promise<T> {
+    const lockKey = `lock:${key}`;
+    const lockAcquired = await this.redis.set(lockKey, '1', 'PX', timeout, 'NX');
+    
+    try {
+      const data = await fetcher();
+      await this.redis.setex(key, ttl, JSON.stringify(data));
+      return data;
+    } finally {
+      await this.redis.del(lockKey);
+    }
+  }
+
+  private async isNearExpiry(key: string): Promise<boolean> {
+    const ttl = await this.redis.ttl(key);
+    return ttl < 60; // último minuto
+  }
+
+  private async refreshInBackground<T>(
+    key: string, 
+    fetcher: () => Promise<T>, 
+    ttl: number
+  ): Promise<void> {
+    // Fire and forget
+    fetcher()
+      .then(data => this.redis.setex(key, ttl, JSON.stringify(data)))
+      .catch(err => console.error(`Background refresh failed for ${key}:`, err));
+  }
+}
+
+// Uso
+const cache = new CacheLayer(redis);
+
+const user = await cache.get(
+  `user:${userId}`,
+  () => db.users.findById(userId),
+  { ttl: 300, staleWhileRevalidate: true }
+);
+```
+
+---
+
+## Checklist
+
+- [ ] Padrão de cache escolhido para cada tipo de dado
+- [ ] TTLs definidos e documentados
+- [ ] Invalidação implementada para operações de escrita
+- [ ] Proteção contra stampede
+- [ ] Monitoramento de hit rate
+- [ ] Fallback se Redis indisponível
+- [ ] Testes de cache hit, miss, e invalidação
+
+---
+
+## Referências
+
+Consulte: [Guia de Estratégias de Cache](../03-guias/Guia%20de%20Estratégias%20de%20Cache.md)