@maestro-ai/cli 1.0.0

package/content/guides/Guia de Adi/303/247/303/243o de Novas Funcionalidades.md"

@@ -0,0 +1,355 @@
+# Guia de Adição de Novas Funcionalidades
+
+## Visão Geral
+Este guia fornece um framework estruturado para adicionar novas funcionalidades aos projetos, seguindo as melhores práticas de desenvolvimento com IA.
+
+A ideia é combinar **processo de engenharia de software** com **uso disciplinado de IA** (ex.: GPT 5.1) em cada etapa.
+
+---
+
+## 1. Análise Inicial
+
+### 1.1 Entendimento do Contexto
+- [ ] Revisar o PRD (Product Requirements Document) existente
+- [ ] Analisar o Design System e padrões de UI/UX
+- [ ] Verificar a arquitetura atual do sistema
+- [ ] Identificar dependências e impactos potenciais
+
+#### Sugestão de uso de IA
+
+```text
+Atue como product/tech lead.
+Vou colar abaixo:
+- trecho do PRD
+- contexto do sistema
+- anotações de stakeholders
+
+Organize em:
+- resumo da funcionalidade
+- objetivos de negócio
+- áreas do sistema impactadas
+- riscos e dependências que devo observar.
+
+Contexto:
+[COLE AQUI]
+```
+
+### 1.2 Definição de Escopo
+- [ ] Descrever a funcionalidade em formato de User Story
+- [ ] Definir critérios de aceitação
+- [ ] Mapear endpoints e modelos de dados necessários
+- [ ] Identificar necessidades de migração de banco de dados
+
+#### Sugestão de uso de IA
+
+```text
+Quero adicionar a seguinte funcionalidade ao sistema:
+[DESCREVA EM LINGUAGEM NATURAL]
+
+Transforme em:
+- 1 a 3 histórias de usuário (Como [persona], quero [ação], para [benefício])
+- critérios de aceitação
+- lista inicial de endpoints/serviços e entidades que podem ser impactadas.
+```
+
+---
+
+## 2. Planejamento Técnico
+
+### 2.1 Especificação Técnica
+- [ ] Atualizar documentação da API (OpenAPI/Swagger)
+- [ ] Atualizar modelo de dados (Prisma/SQL)
+- [ ] Definir contratos de interface
+- [ ] Planejar testes necessários
+
+#### Sugestão de uso de IA
+
+```text
+Aqui está a descrição da nova funcionalidade e a API atual (OpenAPI):
+[COLE TRECHOS RELEVANTES]
+
+Atue como arquiteto de software.
+Proponha:
+- novos endpoints ou ajustes em endpoints existentes
+- exemplos de payloads de requisição/resposta
+- impactos esperados no modelo de dados
+
+Gere também um esboço de alterações em OpenAPI (YAML/JSON), sem inventar campos irreais.
+```
+
+### 2.2 Tarefas Técnicas
+- [ ] Criar branch a partir da main (feature/nome-da-funcionalidade)
+- [ ] Configurar ambiente de desenvolvimento
+- [ ] Implementar camada de dados
+- [ ] Desenvolver endpoints da API
+- [ ] Implementar lógica de negócios
+- [ ] Desenvolver componentes de UI
+- [ ] Escrever testes automatizados
+
+#### Sugestão de uso de IA
+
+```text
+História de usuário e descrição técnica da funcionalidade:
+[COLE]
+
+Gere um plano de implementação em tarefas técnicas, incluindo:
+- passos para backend (dados, serviços, API)
+- passos para frontend (componentes, estados, navegação)
+- passos de testes (unitário, integração, E2E)
+
+Organize em uma lista de tarefas que possa virar backlog de sprint.
+```
+
+---
+
+## 3. Implementação com IA
+
+### 3.1 Geração de Código
+- [ ] Usar prompts específicos para geração de código
+- [ ] Implementar seguindo padrões do projeto
+- [ ] Revisar e refatorar código gerado
+- [ ] Garantir aderência ao style guide
+
+#### Sugestão de uso de IA
+
+```text
+Contexto do projeto:
+- stack: [ex. Node + Nest + Postgres]
+- padrão de arquitetura: [ex. camadas controller/service/repository]
+- entidade(s) envolvida(s): [DESCREVA]
+
+Funcionalidade a implementar:
+[COLE HISTÓRIA + ESPECIFICAÇÃO]
+
+Gere apenas o código do serviço/método de caso de uso responsável pela regra de negócio,
+seguindo o estilo do projeto. Inclua tratamento de erros e tipos adequados.
+Não gere controller/rotas ainda.
+```
+
+### 3.2 Testes Automatizados
+- [ ] Gerar testes unitários com IA
+- [ ] Implementar testes de integração
+- [ ] Validar cobertura de testes (>80%)
+- [ ] Executar testes de regressão
+
+#### Sugestão de uso de IA
+
+```text
+Aqui está o serviço/método que acabei de implementar em [LINGUAGEM]:
+[COLE CÓDIGO]
+
+Gere testes unitários em [FRAMEWORK DE TESTES] cobrindo:
+- caso de sucesso
+- entradas inválidas
+- casos de borda
+
+Explique em 1 linha o que cada teste garante.
+```
+
+```text
+Com base nos requisitos e fluxo da funcionalidade:
+[COLE]
+
+Sugira testes de integração e E2E mais importantes,
+indicando quais ferramentas poderiam ser usadas (ex.: Postman, Playwright, Cypress).
+```
+
+---
+
+## 4. Revisão e Qualidade
+
+### 4.1 Code Review
+- [ ] Revisar mudanças em pares
+- [ ] Validar padrões de código
+- [ ] Verificar vulnerabilidades de segurança
+- [ ] Validar performance
+
+#### Sugestão de uso de IA
+
+```text
+Atue como revisor de código sênior.
+
+Aqui está o diff/arquivo da funcionalidade que implementei:
+[COLE]
+
+Avalie:
+- legibilidade e organização
+- possíveis bugs ou casos de erro não tratados
+- conformidade com padrões de código e arquitetura
+
+Sugira melhorias e, se fizer sentido, apresente uma versão refatorada de trechos críticos.
+```
+
+### 4.2 Testes Manuais
+- [ ] Testar fluxos principais
+- [ ] Validar responsividade
+- [ ] Verificar acessibilidade
+- [ ] Testar em diferentes navegadores
+
+#### Sugestão de uso de IA
+
+```text
+Fluxo principal da funcionalidade:
+[DESCREVA]
+
+Gere um roteiro de testes manuais com passos claros,
+considerando:
+- caso de uso feliz
+- erros comuns de usuário
+- aspectos de acessibilidade e responsividade.
+```
+
+---
+
+## 5. Implantação
+
+### 5.1 Preparação para Produção
+- [ ] Atualizar documentação
+- [ ] Preparar scripts de migração
+- [ ] Atualizar changelog
+- [ ] Preparar rollback se necessário
+
+#### Sugestão de uso de IA
+
+```text
+Mudanças feitas nesta funcionalidade:
+[RESUMA]
+
+Gere:
+- um trecho de changelog
+- uma lista de checagens para migração (se houver mudança de schema)
+- um plano simples de rollback.
+```
+
+### 5.2 Deploy
+- [ ] Merge para branch principal
+- [ ] Executar pipeline de CI/CD
+- [ ] Monitorar métricas pós-deploy
+- [ ] Validar em ambiente de produção
+
+#### Sugestão de uso de IA
+
+```text
+Descreva o ambiente de produção e as métricas críticas do sistema:
+[COLE]
+
+Sugira quais métricas devo monitorar especificamente
+para esta nova funcionalidade nos primeiros dias pós-deploy.
+```
+
+---
+
+## 6. Pós-Implantação
+
+### 6.1 Monitoramento
+- [ ] Configurar alertas
+- [ ] Monitorar erros em produção
+- [ ] Acompanhar métricas de desempenho
+- [ ] Coletar feedback dos usuários
+
+#### Sugestão de uso de IA
+
+```text
+Vou colar alguns erros/logs e feedbacks de usuários
+após o deploy desta funcionalidade:
+[COLE]
+
+Agrupe em:
+- bugs
+- problemas de usabilidade
+- pedidos de melhoria
+
+Sugira ações de curto prazo e melhorias estruturais.
+```
+
+### 6.2 Melhorias Contínuas
+- [ ] Analisar métricas de uso
+- [ ] Identificar oportunidades de otimização
+- [ ] Planejar próximas iterações
+- [ ] Documentar lições aprendidas
+
+#### Sugestão de uso de IA
+
+```text
+Aqui estão métricas de uso desta funcionalidade e observações da equipe:
+[COLE]
+
+Gere um pequeno relatório de lições aprendidas,
+com recomendações para a próxima iteração.
+```
+
+---
+
+## Ferramentas Recomendadas
+
+### Desenvolvimento
+- **Versionamento**: Git
+- **CI/CD**: GitHub Actions, GitLab CI
+- **Documentação**: Swagger/OpenAPI, Storybook ou equivalente
+- **Testes**: Jest, Playwright, Cypress, ou ferramentas equivalentes da stack
+
+### IA
+- **Geração de Código**: GitHub Copilot, Codeium, modelos GPT
+- **Revisão de Código**: CodeRabbit, SonarQube, modelos GPT
+- **Documentação**: Mintlify, Docusaurus, modelos GPT
+
+---
+
+## Templates
+
+### Pull Request
+```markdown
+## Descrição
+[Breve descrição das mudanças]
+
+## Tipo de Mudança
+- [ ] Nova funcionalidade
+- [ ] Correção de bug
+- [ ] Melhoria de performance
+- [ ] Atualização de documentação
+
+## Checklist
+- [ ] Meu código segue as diretrizes de estilo do projeto
+- [ ] Adicionei testes que comprovam minha correção
+- [ ] Testes unitários passam localmente
+- [ ] Atualizei a documentação conforme necessário
+
+## Screenshots/Vídeos
+[Adicione capturas de tela ou vídeos se aplicável]
+```
+
+### User Story
+```text
+Como um [tipo de usuário],
+Quero [ação],
+Para que [benefício/valor].
+
+Critérios de Aceitação:
+- [ ] Critério 1
+- [ ] Critério 2
+- [ ] Critério 3
+```
+
+---
+
+## Boas Práticas
+
+### Desenvolvimento
+- Sempre comece pelos testes (ao menos pensando nos cenários).
+- Mantenha as mudanças pequenas e focadas.
+- Documente decisões arquiteturais relevantes.
+- Siga o princípio da responsabilidade única.
+
+### IA
+- Revise sempre o código gerado.
+- Mantenha prompts específicos e claros.
+- Documente os prompts utilizados que funcionaram bem.
+- Não confie cegamente nas saídas da IA; use como assistente, não como verdade absoluta.
+
+---
+
+## Recursos Adicionais
+- [Documentação do Projeto](#)
+- [Guia de Estilo](#)
+- [Playbook de DevOps](#)
+- [Política de Branches](#)

package/content/guides/Guia de Chaos Engineering.md

@@ -0,0 +1,267 @@
+# Guia de Chaos Engineering
+
+> **Prioridade**: 🟢 BAIXA  
+> **Aplicável a**: Projetos Nível 3 (Complexo) com alta disponibilidade obrigatória  
+> **Pré-requisito**: SLOs definidos para medir impacto
+
+---
+
+## O que é Chaos Engineering?
+
+> "Chaos Engineering é a disciplina de experimentar em um sistema para construir confiança na capacidade do sistema de suportar condições turbulentas em produção."
+> — [Principles of Chaos Engineering](https://principlesofchaos.org/)
+
+**NÃO é**: Quebrar coisas aleatoriamente
+**É**: Experimentos controlados para descobrir fraquezas
+
+---
+
+## Quando Usar?
+
+| Contexto | Chaos Engineering? |
+|----------|-------------------|
+| MVP / Startup inicial | ❌ Não prioritário |
+| SaaS com SLA 99.9% | ✅ Sim |
+| Fintech / Healthcare | ✅ Obrigatório |
+| Microserviços distribuídos | ✅ Altamente recomendado |
+| Monolito simples | ⚠️ Pode ser overkill |
+
+---
+
+## Processo
+
+```mermaid
+graph LR
+    A[1. Definir Estado Estável] --> B[2. Formular Hipótese]
+    B --> C[3. Planejar Experimento]
+    C --> D[4. Executar em Ambiente Controlado]
+    D --> E[5. Analisar Resultados]
+    E --> F[6. Melhorar Sistema]
+    F --> A
+```
+
+### 1. Definir Estado Estável
+
+Use SLOs como baseline:
+- Disponibilidade: 99.9%
+- Latência p95: < 200ms
+- Taxa de erros: < 0.1%
+
+### 2. Formular Hipótese
+
+```
+"Quando [FALHA INJETADA], o sistema deve [COMPORTAMENTO ESPERADO]
+ e os SLOs devem [IMPACTO ACEITÁVEL]."
+```
+
+Exemplo:
+> "Quando o banco de dados primário falhar, o sistema deve fazer failover para réplica em < 30 segundos, com queda temporária de disponibilidade < 0.01%."
+
+### 3. Planejar Experimento
+
+| Aspecto | Definição |
+|---------|-----------|
+| **Escopo** | Quais componentes? |
+| **Blast Radius** | % de tráfego afetado |
+| **Duração** | Quanto tempo? |
+| **Métricas** | O que observar? |
+| **Kill Switch** | Como parar imediatamente? |
+| **Rollback** | Como reverter? |
+
+### 4. Executar
+
+- Começar em staging
+- Depois em produção com % pequeno
+- Ter equipe pronta para intervir
+- Monitorar métricas em tempo real
+
+### 5. Analisar
+
+- Hipótese confirmada ou refutada?
+- Descobertas inesperadas?
+- SLOs impactados quanto?
+
+### 6. Melhorar
+
+- Criar tickets para corrigir fraquezas
+- Adicionar alarmes faltantes
+- Melhorar runbooks
+- Repetir experimento após fix
+
+---
+
+## Tipos de Experimentos
+
+### Infraestrutura
+
+| Experimento | Descrição | Ferramenta |
+|-------------|-----------|------------|
+| **Kill Instance** | Terminar VM/container | Chaos Monkey |
+| **CPU Stress** | 100% CPU | stress-ng |
+| **Memory Pressure** | Esgotar memória | stress-ng |
+| **Disk Fill** | Encher disco | dd |
+| **Network Latency** | Adicionar latência | tc netem |
+| **Network Partition** | Isolar serviços | iptables |
+| **DNS Failure** | DNS não resolve | Gremlin |
+
+### Aplicação
+
+| Experimento | Descrição |
+|-------------|-----------|
+| **Dependency Failure** | Mock falha de serviço externo |
+| **Database Slowdown** | Queries lentas artificialmente |
+| **Circuit Breaker Test** | Abrir circuit breaker |
+| **Cache Invalidation** | Limpar todo o cache |
+| **Message Queue Backup** | Enfileirar muitas mensagens |
+
+### Processo
+
+| Experimento | Objetivo |
+|-------------|----------|
+| **On-Call Response** | Tempo de resposta do time |
+| **Runbook Validity** | Runbooks funcionam? |
+| **Rollback Speed** | Tempo para reverter deploy |
+
+---
+
+## Ferramentas
+
+| Ferramenta | Tipo | Melhor Para |
+|------------|------|-------------|
+| **Chaos Monkey** | Open Source | Kill instances (EC2) |
+| **Gremlin** | SaaS | Experimentos variados |
+| **Litmus** | Open Source | Kubernetes |
+| **Chaos Mesh** | Open Source | Kubernetes |
+| **AWS FIS** | AWS | Experimentos na AWS |
+| **Toxiproxy** | Open Source | Network failures |
+
+---
+
+## Exemplo: Experimento Simples
+
+### Plano
+
+```yaml
+Experiment:
+  Name: Database Failover Test
+  Hypothesis: >
+    Quando o RDS primário ficar indisponível por 5 minutos,
+    o sistema deve fazer failover para a réplica em < 30 segundos
+    com < 3 requests falhando.
+    
+  Scope:
+    Environment: staging
+    BlastRadius: 100% (staging é isolado)
+    Duration: 5 minutes
+    
+  Execution:
+    Tool: AWS FIS
+    Action: aws:rds:failover-db-cluster
+    Target: staging-db-cluster
+    
+  Metrics:
+    - SLI: Availability (requests bem-sucedidos)
+    - SLI: Error count durante failover
+    - Custom: Tempo para recuperação
+    
+  KillSwitch:
+    - Manual: Cancelar experimento no FIS console
+    - Auto: Se error rate > 5% por 1 min
+    
+  Team:
+    - Lead: @engineer-1
+    - Observer: @engineer-2
+    - Communicator: @manager (se escalar)
+```
+
+### Execução
+
+```bash
+# AWS FIS
+aws fis start-experiment \
+  --experiment-template-id EXT123456 \
+  --tags Environment=staging
+
+# Monitorar
+watch -n 5 'curl -s https://staging.app.com/health | jq .'
+```
+
+### Resultado
+
+```markdown
+## Resultado: Database Failover Test
+
+**Data**: 2024-01-15 14:00 UTC
+**Hipótese**: CONFIRMADA ✅
+
+### Métricas Observadas
+- Tempo de failover: 22 segundos
+- Requests falhados durante failover: 2
+- Availability durante experimento: 99.97%
+
+### Descobertas
+- Circuit breaker levou 10s para abrir (configurar para 5s)
+- Alertas dispararam corretamente
+- Runbook estava desatualizado (atualizar)
+
+### Ações
+- [ ] Ajustar circuit breaker timeout
+- [ ] Atualizar runbook de failover
+- [ ] Adicionar métrica de tempo de failover
+```
+
+---
+
+## Começando
+
+### Semana 1: Preparação
+- [ ] Definir SLOs de baseline
+- [ ] Mapear dependências críticas
+- [ ] Configurar observabilidade
+
+### Semana 2: Primeiro Experimento
+- [ ] Escolher experimento simples (ex: kill instance)
+- [ ] Executar em staging
+- [ ] Documentar resultados
+
+### Semana 3+: Evolução
+- [ ] Experimentos mais complexos
+- [ ] Game days (simulação de incidente)
+- [ ] Eventualmente em produção
+
+---
+
+## Checklist de Prontidão
+
+Antes de chaos engineering em produção:
+
+- [ ] SLOs definidos e monitorados
+- [ ] Alertas funcionando
+- [ ] Runbooks para cenários comuns
+- [ ] Rollback testado e rápido
+- [ ] Time treinado em resposta a incidentes
+- [ ] Comunicação definida (quem avisar, quando)
+- [ ] Janela de experimentos acordada
+- [ ] Kill switch configurado e testado
+
+---
+
+## Anti-Patterns
+
+| ❌ Não Faça | ✅ Faça |
+|-------------|--------|
+| Chaos sem hipótese | Sempre defina hipótese clara |
+| Começar em produção | Staging primeiro |
+| Grande blast radius inicial | Comece com 1% do tráfego |
+| Sem monitoramento | Dashboards abertos durante |
+| Sem kill switch | Sempre tenha forma de parar |
+| Culpar pessoas | Foque em melhorar sistemas |
+
+---
+
+## Referências
+
+- [Principles of Chaos Engineering](https://principlesofchaos.org/)
+- [Chaos Engineering (O'Reilly Book)](https://www.oreilly.com/library/view/chaos-engineering/9781491988459/)
+- [Netflix Chaos Monkey](https://github.com/Netflix/chaosmonkey)
+- [AWS Fault Injection Simulator](https://aws.amazon.com/fis/)