Sprint Context Generator

Sprint Context Generator

Visão Geral

Gera documentação completa e estruturada para alimentar a skill long-running-agent. Segue metodologia Spec-Driven Development inspirada no spec-kit do GitHub, incorporando análises de múltiplas personas e garantindo cobertura completa de testes E2E e TDD.

Esta skill transforma uma ideia de feature em documentação executável através de:

• Coleta interativa de requisitos com confirmação
• Pesquisa automatizada de documentação e melhores práticas (WebSearch/WebFetch)
• Análise multi-perspectiva (6 personas: Arquiteto, Dev, QA, Designer, PM, BA)
• Geração de 50-100 tasks granulares e específicas
• Validação automática de qualidade e compatibilidade

Quando Usar Esta Skill

Use esta skill quando você precisa:

• ✅ Planejar novas features para um projeto
• ✅ Refatorar features existentes com documentação adequada
• ✅ Criar contexto estruturado para desenvolvimento prolongado
• ✅ Preparar trabalho para delegação a SubAgents
• ✅ Garantir que todos os stakeholders (Arquiteto, QA, PM, etc.) tenham input
• ✅ Gerar documentação compatível com long-running-agent

NÃO use para:

• ❌ Implementação direta de código (use long-running-agent após gerar docs)
• ❌ Tarefas triviais que não requerem planejamento
• ❌ Apenas consultar informações (use general-purpose ou Explore)

O Que Esta Skill Gera

5 Arquivos de Documentação Completa:

1. spec.md (~800-1200 linhas)

   • Especificação detalhada com análises das 6 personas
   • User stories e casos de uso
   • Critérios de aceitação
   • Requisitos de performance/segurança
   • Dependências e bloqueadores

2. plan.md (~600-900 linhas)

   • Plano técnico de arquitetura
   • Stack tecnológica recomendada
   • Estrutura de diretórios
   • Componentes e módulos
   • APIs e contratos
   • Variáveis de ambiente
   • Decisões técnicas e riscos

3. tasks.md (~400-800 linhas)

   • 50-100 tasks granulares organizadas por tipo:
     • 🏗️ Setup/Arquitetura (5-10 tasks)
     • 💻 Backend (15-25 tasks)
     • 🎨 Frontend/UI (20-30 tasks)
     • ✅ Testes Unitários (10-15 tasks)
     • ✅ Testes E2E (10-15 tasks)
     • 📝 Documentação (3-5 tasks)

4. research.md (~300-600 linhas)

   • Documentação de tecnologias externas pesquisadas
   • Melhores práticas (Clean Arch, TDD, E2E, Linting, Husky)
   • Artigos e recursos relevantes
   • Exemplos de implementação

5. features.xml

   • Formato XML compatível com long-running-agent
   • Feature com ID sequencial (FEAT-XXX)
   • Status, prioridade, categoria
   • Critérios de aceitação
   • Referência aos docs gerados

Localização de saída: docs/context-log-running/<feature-name>/

Extras:

• Branch Git criada automaticamente: feature/FEAT-XXX-<feature-name>
• Commit com mensagem padronizada
• Validação automática de qualidade e compatibilidade
• Resumo com estimativa de complexidade e próximos passos

Workflow Principal

Esta skill executa 5 fases sequenciais para garantir documentação completa e de alta qualidade.

FASE 1: Coleta de Informações (Interactive Discovery)

Objetivo: Entender completamente o contexto do projeto e os requisitos da feature através de perguntas interativas.

1.1. Verificar Estrutura Existente (CRÍTICO)

1.1.1. Verificar se .claude/ existe:

Execute:

ls -la .claude/

Cenário A: .claude/ NÃO EXISTE (projeto novo/legado)

Pergunte ao usuário:

⚠️ Este projeto ainda não tem estrutura de long-running-agent (.claude/).

A skill long-running-agent precisa dessa estrutura para executar as tasks automaticamente.

Deseja inicializá-la agora?
1. Sim, inicializar estrutura completa (recomendado)
2. Não, criar apenas documentação da feature (sem integração com long-running-agent)

Se opção 1 (SIM):

• Informar: "Vou inicializar a estrutura .claude/ para você."
• Executar: python "C:\Users\Script7\Desktop\Skills Claude Code\skills\long-running-agent\scripts\init_project.py"
• Aguardar conclusão
• Continuar normalmente com geração de ID sequencial

Se opção 2 (NÃO):

• ⚠️ AVISO:

  IMPORTANTE: Sem `.claude/`, a skill long-running-agent NÃO funcionará.
  Você terá apenas a documentação em docs/context-log-running/<feature-name>/.
  
  Você poderá inicializar .claude/ mais tarde executando:
  python skills/long-running-agent/scripts/init_project.py
  

• Criar apenas docs/context-log-running/<feature-name>/
• Usar FEAT-001 como ID padrão
• Pular integração com .claude/features.xml global
• Gerar apenas o features.xml local em docs/context-log-running/<feature-name>/

Cenário B: .claude/ EXISTE mas features.xml está vazio/ausente

• Criar features.xml inicial em .claude/
• Usar FEAT-001 como primeiro ID

Cenário C: .claude/features.xml TEM features (cenário normal)

• Ler arquivo: cat .claude/features.xml
• Extrair último ID (ex: <feature id="FEAT-015"...)
• Incrementar sequencialmente: FEAT-016
• Fallback: Se XML corrompido:
  • Avisar usuário: "features.xml parece corrompido. Usando FEAT-001 como ID padrão."
  • Usar FEAT-001

1.1.2. Verificar tech stack do projeto:

Detectar framework/linguagem através de arquivos de configuração:

# Tentar package.json (Node.js/JavaScript)
cat package.json 2>/dev/null

# Se não existir, tentar requirements.txt (Python)
cat requirements.txt 2>/dev/null

# Se não existir, tentar pom.xml (Java/Maven)
cat pom.xml 2>/dev/null

# Se não existir, tentar Cargo.toml (Rust)
cat Cargo.toml 2>/dev/null

Extrair informações:

• Framework principal (Next.js, React, Express, Django, Spring Boot, etc.)
• Linguagem (TypeScript, JavaScript, Python, Java, Rust, etc.)
• Dependências principais
• Framework de testes atual (se houver)

Se nenhum arquivo encontrado:

• Perguntar ao usuário: "Não detectei o stack tecnológico automaticamente. Qual framework/linguagem você está usando?"

1.2. Perguntas Interativas (Sequenciais, Uma por Vez, com Confirmação)

IMPORTANTE: Fazer perguntas uma por vez, aguardar resposta e confirmar compreensão antes de continuar.

Q1: Nome da Feature

Pergunte:

Qual o nome/título da feature que você quer planejar?

Exemplos:
- "Sistema de Autenticação JWT"
- "Dashboard de Analytics em Tempo Real"
- "Integração com API de Pagamento Stripe"

Nome da feature:

[Aguardar resposta do usuário]

Confirmação Q1:

Entendi! Nome da feature: "[resposta do usuário]"

Isso está correto? (Sim/Não)

[Aguardar confirmação. Se "Não", perguntar novamente]

Q2: Descrição da Feature

Pergunte:

Descreva detalhadamente a feature:
- O que ela faz?
- Qual problema resolve?
- Como o usuário vai interagir com ela?

Seja específico e detalhado.

Descrição:

[Aguardar resposta do usuário]

Confirmação Q2:

Resumindo sua feature:
"[Resumo conciso da resposta em 2-3 frases]"

Isso captura corretamente o que você quer? (Sim/Não)

[Aguardar confirmação. Se "Não", pedir esclarecimentos]

Q3: User Stories

Pergunte:

Quais são as user stories principais para esta feature?

Use o formato: "Como [tipo de usuário], quero [ação], para [benefício]"

Exemplos:
- Como usuário, quero fazer login com email e senha, para acessar minha conta de forma segura
- Como admin, quero resetar senhas de usuários, para ajudá-los quando esquecerem
- Como visitante, quero criar uma conta, para começar a usar o sistema

Liste de 2 a 5 user stories:

[Aguardar resposta do usuário]

Validação: Se usuário não usar formato adequado, reformatar e confirmar:

Reformatei suas user stories no formato padrão:

1. Como [tipo], quero [ação], para [benefício]
2. Como [tipo], quero [ação], para [benefício]
...

Está correto? (Sim/Não)

Q4: Tecnologias Externas

Pergunte:

Esta feature usa tecnologias externas? (APIs, bibliotecas, serviços de terceiros)

Se SIM, forneça:
- Nome da tecnologia
- Link da documentação oficial
- Versão (se souber)

Exemplos:
- Stripe API: https://stripe.com/docs/api
- NextAuth.js: https://next-auth.js.org/getting-started/introduction
- Prisma ORM: https://www.prisma.io/docs

Se NÃO usa tecnologias externas, digite "Nenhuma".

Tecnologias externas:

[Aguardar resposta do usuário]

Se forneceu links:

• Confirmar: "Vou pesquisar a documentação de [tecnologia 1], [tecnologia 2]... durante a Fase 2."

Se respondeu "Nenhuma":

• Confirmar: "Entendido. Feature não depende de tecnologias externas."

Q5: Requisitos de Performance/Segurança

Pergunte:

Há requisitos específicos de performance ou segurança para esta feature?

Exemplos de requisitos:
- SEGURANÇA: "Autenticação deve usar JWT com algoritmo RS256"
- SEGURANÇA: "Senhas devem ser hash com bcrypt (custo 12)"
- SEGURANÇA: "Dados sensíveis devem ser criptografados em repouso (AES-256)"
- PERFORMANCE: "Tempo de resposta < 200ms para todas as APIs"
- PERFORMANCE: "Suportar 1000 requisições simultâneas"
- PERFORMANCE: "Rate limiting: max 100 requests/min por IP"

Se NÃO há requisitos específicos, digite "Padrões normais".

Requisitos:

[Aguardar resposta do usuário]

Confirmação:

Requisitos de performance/segurança anotados:
[Listar requisitos fornecidos ou "Aplicar padrões normais de segurança e performance"]

Correto? (Sim/Não)

Q6: Dependências e Bloqueadores

Pergunte:

Esta feature depende de outras features ou infraestrutura ainda não implementada?

Exemplos de dependências:
- "Depende de FEAT-003 (Sistema de Autenticação)" ← feature existente
- "Requer banco de dados PostgreSQL configurado" ← infraestrutura
- "Precisa de Redis para cache" ← serviço externo
- "Depende de FEAT-010 (API de Usuários)" ← outra feature

Se NÃO há dependências, digite "Nenhuma".

Dependências:

[Aguardar resposta do usuário]

Se houver dependências:

• Perguntar:

  Qual o status dessa dependência?
  
  Se for uma feature: forneça o ID (ex: FEAT-003)
  Se for infraestrutura: ela já está implementada? (Sim/Não)
  

• Se dependência NÃO está pronta:

  • Marcar feature como status="blocked" em features.xml
  • Adicionar nota: Blocked: Requires [FEAT-XXX] ou [descrição da infraestrutura]
  • ⚠️ AVISO ao usuário:

    ATENÇÃO: Esta feature está BLOQUEADA.
    
    Bloqueador: [descrição]
    
    Você deve implementar/configurar o bloqueador ANTES de usar long-running-agent para esta feature.
    A documentação será gerada normalmente, mas a implementação só poderá começar após resolver o bloqueador.
    

Q7: Categoria da Feature

Pergunte:

Esta feature pertence a qual categoria?

Categorias comuns:
- Authentication (login, registro, sessões)
- Dashboard (visualizações, gráficos, métricas)
- API (endpoints REST/GraphQL)
- Database (modelos, migrações, queries)
- UI Components (componentes reutilizáveis)
- Payment (integrações de pagamento)
- Admin (painéis administrativos)
- Notifications (emails, push, in-app)

Baseado na descrição da feature, sugiro: "[categoria sugerida baseada em Q2]"

Qual categoria deseja usar? (Pode usar a sugerida ou outra)

[Aguardar resposta do usuário]

1.3. Resumo da Coleta

Após todas as perguntas, exibir resumo:

✅ Coleta de informações completa!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 RESUMO DA FEATURE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Feature: [Nome]
ID: FEAT-XXX
Categoria: [Categoria]
Status: [Pending/Blocked]

Descrição: [Resumo de 1-2 linhas]

User Stories: [N] stories coletadas
Tecnologias externas: [N] tecnologias identificadas
Requisitos especiais: [Lista]
Dependências: [Nenhuma/Bloqueada por X]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Agora vou pesquisar documentação e melhores práticas... (Fase 2)

FASE 2: Pesquisa e Contextualização (Detalhada)

Objetivo: Pesquisar documentação oficial, melhores práticas e exemplos de implementação para enriquecer o contexto.

2.1. Pesquisar Documentação de Tecnologias Externas

Para cada link fornecido pelo usuário em Q4:

1. Usar WebFetch para extrair conteúdo:

   WebFetch(url=link_fornecido, prompt="Extraia as seguintes informações:
   - Seção 'Getting Started' ou 'Quick Start'
   - Principais métodos/funções da API
   - Exemplos de código básicos
   - Requisitos de instalação
   - Versão mais recente recomendada
   
   Retorne em formato markdown organizado.")
   

2. Focar em:

   • Seções "Getting Started", "Quick Start", "Introduction"
   • Métodos/APIs principais (top 5-10 mais usados)
   • Exemplos de código práticos (preferir código a teoria)
   • Requisitos de instalação/configuração
   • Versões recomendadas/compatibilidade

3. Limites (evitar sobrecarga de contexto):

   • Máximo 3 páginas por tecnologia
   • Extrair apenas seções relevantes (não página inteira)
   • Priorizar exemplos de código sobre explicações teóricas longas
   • Se documentação > 10.000 palavras, fazer 2-3 WebFetch focados em seções diferentes

4. Fallback se link inacessível (404, timeout, erro):

   • Usar WebSearch: "[Nome da Tecnologia] official documentation 2026"
   • Buscar 2-3 resultados mais relevantes
   • Priorizar:
     • Domínio oficial (.org, site oficial, GitHub oficial)
     • Documentação atualizada (2024-2026)
     • Fontes confiáveis (npm, PyPI, Maven Central)

Exemplo de extração estruturada:

### NextAuth.js
- **Link**: https://next-auth.js.org/getting-started/introduction
- **Versão**: 4.24.0 (latest stable)
- **Instalação**:
  ```bash
  npm install next-auth

• Principais métodos:

  • signIn(provider, options): Iniciar autenticação com provedor (Google, GitHub, etc.)
  • signOut(options): Encerrar sessão do usuário
  • useSession(): Hook React para acessar dados da sessão atual
  • getServerSession(req, res, authOptions): Obter sessão no server-side

• Exemplo básico de configuração:

  // pages/api/auth/[...nextauth].ts
  import NextAuth from "next-auth"
  import GoogleProvider from "next-auth/providers/google"
  
  export default NextAuth({
    providers: [
      GoogleProvider({
        clientId: process.env.GOOGLE_ID,
        clientSecret: process.env.GOOGLE_SECRET,
      }),
    ],
    callbacks: {
      async session({ session, token }) {
        session.user.id = token.sub
        return session
      },
    },
  })
  

• Configurações importantes:

  • Variáveis de ambiente: NEXTAUTH_SECRET, NEXTAUTH_URL
  • Providers suportados: 50+ (Google, GitHub, Facebook, Email, etc.)
  • Suporte a JWT e Database sessions

• Links úteis:

  • Configuração avançada: https://next-auth.js.org/configuration/options
  • Provedores: https://next-auth.js.org/providers

**Informar progresso ao usuário:**

🔍 Pesquisando documentação de [Tecnologia 1]... ✅ NextAuth.js: Documentação extraída (principais métodos, exemplos, config)

🔍 Pesquisando documentação de [Tecnologia 2]... ✅ Stripe API: Documentação extraída (payment intents, webhooks, exemplos)

---

#### 2.2. Pesquisar Melhores Práticas (WebSearch Focado)

**Executar 5 buscas estratégicas baseadas no tech stack detectado:**

**Busca 1: Clean Architecture**

Query:

"Clean Architecture [tech-stack detectado] best practices 2026"

Exemplo real:

"Clean Architecture Next.js TypeScript best practices 2026"

**Coletar:**
- 2-3 resultados top (priorizar: dev.to, medium engineering blogs, GitHub repos populares)

**Extrair:**
- Padrões de estrutura de diretórios
- Separação de camadas (presentation, business, data)
- Dependency injection patterns
- Exemplos de código de estrutura

---

**Busca 2: Testes E2E com Playwright**

Query:

"Playwright E2E testing patterns examples [framework detectado] 2026"

Exemplo real:

"Playwright E2E testing patterns examples Next.js 2026"

**Coletar:**
- 2-3 artigos/repositórios

**Extrair:**
- Estrutura de testes recomendada (Page Object Model, etc.)
- Fixtures e helpers comuns
- Exemplos de testes E2E completos
- Configuração do Playwright

---

**Busca 3: TDD (Test-Driven Development)**

Query:

"TDD [tech-stack] practical guide examples 2026"

Exemplo real:

"TDD TypeScript Jest practical guide examples 2026"

**Coletar:**
- 2 guias práticos

**Extrair:**
- Workflow Red-Green-Refactor com exemplos
- Estrutura de testes unitários
- Mocking e test doubles
- Coverage tools e targets

---

**Busca 4: Linting e Formatação**

Query:

"ESLint Prettier setup [framework] best config 2026"

Exemplo real:

"ESLint Prettier setup Next.js TypeScript best config 2026"

**Coletar:**
- 2 configurações recomendadas

**Extrair:**
- Arquivos `.eslintrc.js` ou `eslint.config.js`
- Arquivo `.prettierrc`
- Regras essenciais recomendadas
- Plugins úteis (typescript-eslint, etc.)

---

**Busca 5: Husky Git Hooks**

Query:

"Husky git hooks pre-commit pre-push configuration tutorial 2026"

**Coletar:**
- 1-2 tutoriais atualizados

**Extrair:**
- Setup completo do Husky
- Scripts de hooks (pre-commit, pre-push, commit-msg)
- Integração com lint-staged
- Exemplos de configuração

---

**Para cada busca:**
- Coletar **máximo 3 resultados** mais relevantes
- Extrair padrões e **exemplos de código**
- **Priorizar fontes oficiais e reconhecidas:**
  - Documentação oficial
  - GitHub oficial da ferramenta
  - Blogs técnicos reconhecidos (dev.to, Medium engineering, LogRocket, etc.)
  - Repositórios GitHub com muitas stars (>1k stars)
- **Evitar:**
  - Tutoriais desatualizados (>2 anos, antes de 2024)
  - Fontes não confiáveis ou blogs pessoais obscuros
  - Conteúdo muito genérico que não traz valor

**Informar progresso ao usuário:**

🔍 Pesquisando melhores práticas... ✅ Clean Architecture para [stack] ✅ Testes E2E com Playwright ✅ TDD patterns ✅ ESLint/Prettier configs ✅ Husky hooks setup

Pesquisa concluída! Consolidando em research.md...

---

#### 2.3. Consolidação em research.md

**Organizar em 4 seções principais:**

```markdown
# Pesquisa e Documentação: FEAT-XXX - [Nome da Feature]

**Data da pesquisa:** [YYYY-MM-DD]
**Tecnologias pesquisadas:** [N] tecnologias
**Melhores práticas:** 5 áreas (Clean Arch, E2E, TDD, Linting, Hooks)

---

## Índice

1. [Tecnologias Utilizadas](#tecnologias-utilizadas)
2. [Melhores Práticas Pesquisadas](#melhores-práticas-pesquisadas)
3. [Artigos Relevantes](#artigos-relevantes)
4. [Exemplos de Implementação](#exemplos-de-implementação)

---

## 1. Tecnologias Utilizadas

[Uma subseção por tecnologia pesquisada]

### 1.1. [Nome da Tecnologia 1]
- **Link oficial**: [URL]
- **Versão**: [version]
- **Descrição**: [1-2 frases sobre o que é]
- **Instalação**:
  ```bash
  [comando de instalação]

• Principais métodos/APIs:

  • método1(): [descrição sucinta]
  • método2(): [descrição sucinta]
  • método3(): [descrição sucinta]

• Exemplo básico:

  [código de exemplo extraído da documentação]
  

• Configurações importantes:

• Links úteis:

1.2. [Nome da Tecnologia 2]

[Mesmo formato]

2. Melhores Práticas Pesquisadas

2.1. Clean Architecture

Fontes:

• Título do artigo/repo
• Título do artigo/repo

Resumo dos principais pontos:

• Estrutura de diretórios recomendada:

  src/
  ├── presentation/    # Controllers, rotas, UI
  ├── application/     # Use cases, serviços de aplicação
  ├── domain/          # Entidades, regras de negócio
  └── infrastructure/  # DB, APIs externas, frameworks
  

• Princípios chave:

  • Dependências apontam para dentro (domain não depende de nada)
  • Use cases orquestram o fluxo
  • Inversão de dependência para acesso a dados

• Exemplo de estrutura aplicada ao [stack detectado]:

  [Estrutura específica para o projeto]
  

2.2. Testes E2E com Playwright

Fontes:

• Título
• Título

Estrutura recomendada:

tests/
├── e2e/
│   ├── fixtures/           # Dados de teste, helpers
│   ├── pages/              # Page Object Model
│   │   ├── login.page.ts
│   │   └── dashboard.page.ts
│   └── specs/
│       ├── auth.spec.ts
│       └── dashboard.spec.ts
└── playwright.config.ts

Patterns úteis:

• Page Object Model: Encapsular lógica de página
• Fixtures customizados: Compartilhar setup entre testes
• Auto-waiting: Playwright espera automaticamente por elementos

Exemplo de teste E2E:

[Exemplo extraído da pesquisa]

2.3. TDD (Test-Driven Development)

Fontes:

• Título

Workflow Red-Green-Refactor:

1. 🔴 Red: Escrever teste que falha
2. 🟢 Green: Implementar código mínimo para passar
3. 🔵 Refactor: Melhorar código mantendo testes passando

Exemplo prático:

// Red: Teste falha
test('should authenticate user with valid credentials', () => {
  const result = authService.login('user@example.com', 'password123')
  expect(result.success).toBe(true)
  expect(result.token).toBeDefined()
})

// Green: Implementação mínima
class AuthService {
  login(email, password) {
    return { success: true, token: 'fake-jwt-token' }
  }
}

// Refactor: Implementação real
class AuthService {
  login(email, password) {
    const user = db.findByEmail(email)
    if (!user || !bcrypt.compare(password, user.passwordHash)) {
      return { success: false, error: 'Invalid credentials' }
    }
    const token = jwt.sign({ userId: user.id }, SECRET)
    return { success: true, token }
  }
}

Metas de cobertura:

• Unitários: >80%
• Integração: >70%
• E2E: Fluxos principais 100%

2.4. Linting (ESLint/Prettier)

Fontes:

• Título

Configuração recomendada:

.eslintrc.js:

[Configuração extraída da pesquisa]

.prettierrc:

[Configuração extraída da pesquisa]

Scripts package.json:

{
  "scripts": {
    "lint": "eslint . --ext .ts,.tsx",
    "lint:fix": "eslint . --ext .ts,.tsx --fix",
    "format": "prettier --write \"**/*.{ts,tsx,json,md}\""
  }
}

2.5. Husky Git Hooks

Fontes:

• Título

Setup completo:

1. Instalação:

   npm install --save-dev husky lint-staged
   npx husky init
   

2. Configurar pre-commit (.husky/pre-commit):

   #!/usr/bin/env sh
   . "$(dirname -- "$0")/_/husky.sh"
   
   npx lint-staged
   

3. Configurar lint-staged (package.json):

   {
     "lint-staged": {
       "*.{ts,tsx}": [
         "eslint --fix",
         "prettier --write"
       ],
       "*.{json,md}": [
         "prettier --write"
       ]
     }
   }
   

4. Configurar pre-push (.husky/pre-push):

   #!/usr/bin/env sh
   . "$(dirname -- "$0")/_/husky.sh"
   
   npm run test
   

3. Artigos Relevantes

Lista de artigos, tutoriais e recursos para leitura futura:

• Título do artigo 1 - Resumo de 1 linha sobre o conteúdo
• Título do artigo 2 - Resumo de 1 linha
• Título do artigo 3 - Resumo de 1 linha [... até 10 artigos]

4. Exemplos de Implementação

Repositórios GitHub de referência que implementam padrões similares:

4.1. [Nome do Repositório 1]

• Link: [URL do GitHub]
• Stars: [N] ⭐
• Stack: [Tecnologias usadas]
• O que aproveitar:
  • [Insight 1: ex: "Estrutura de diretórios muito clara"]
  • [Insight 2: ex: "Excelente cobertura de testes E2E"]
  • [Insight 3: ex: "Padrão de error handling robusto"]

4.2. [Nome do Repositório 2]

[Mesmo formato]

Fim do research.md

**Objetivo:** research.md deve ser consultável rapidamente (índice no topo), bem estruturado e conter exemplos práticos, não apenas links.

**Informar usuário:**

✅ research.md gerado com sucesso!

• [N] tecnologias documentadas
• 5 áreas de melhores práticas pesquisadas
• [N] artigos relevantes coletados
• [N] repositórios de exemplo identificados

Agora vou fazer análise multi-persona... (Fase 3)

---

### FASE 3: Análise Multi-Persona

Objetivo: Analisar a feature sob 6 perspectivas diferentes para garantir cobertura holística de todos os aspectos (técnicos, negócio, UX, qualidade).

**Para cada persona, gerar análise específica que será incluída no spec.md:**

---

#### 3.1. 🏗️ Arquiteto de Soluções

**Foco:** Estrutura técnica, arquitetura, dependências, escalabilidade

**Perguntas que o Arquiteto responde:**
- Como organizar o código? (estrutura de diretórios)
- Quais packages/dependências instalar?
- Há necessidade de refatoração de código existente?
- Qual padrão de arquitetura aplicar? (MVC, Clean, Hexagonal, etc.)
- Como garantir escalabilidade e manutenibilidade?

**Análise a gerar:**

```markdown
## 🏗️ Análise do Arquiteto de Soluções

### Estrutura de Diretórios Proposta

Baseado em Clean Architecture e melhores práticas de [framework detectado]:

[Estrutura específica para o projeto]

**Justificativa:**
- [Explicar escolha da estrutura]
- [Separação de responsabilidades]
- [Facilita testes e manutenção]

### Dependências Necessárias

**Produção:**
```json
{
  "[package1]": "^[version]",  // [Justificativa]
  "[package2]": "^[version]",  // [Justificativa]
}

Desenvolvimento:

{
  "[dev-package1]": "^[version]",  // [Justificativa]
  "[dev-package2]": "^[version]",  // [Justificativa]
}

Refatorações Necessárias

[Se aplicável, listar código existente que precisa ser refatorado]

Exemplo:

• Módulo X: Atualmente monolítico, deve ser separado em serviços menores
• Componente Y: Deve ser extraído para reutilização

Padrões de Arquitetura

Padrão escolhido: [Clean Architecture / MVC / Hexagonal / etc.]

Camadas:

1. Presentation Layer: [Responsabilidades]
2. Application Layer: [Responsabilidades]
3. Domain Layer: [Responsabilidades]
4. Infrastructure Layer: [Responsabilidades]

Fluxo de dados:

[Diagrama em ASCII ou descrição textual]
User Request → Controller → Use Case → Repository → Database
            ← DTO        ← Entity   ← Model      ←

Decisões de Escalabilidade

• [Decisão 1]: [ex: "Usar cache Redis para sessões"]
• [Decisão 2]: [ex: "Implementar rate limiting no Nginx"]
• [Decisão 3]: [ex: "Preparar para horizontal scaling com stateless design"]

---

#### 3.2. 💻 Requisitos do Desenvolvedor

**Foco:** Implementação prática, padrões de código, APIs, variáveis de ambiente

**Perguntas que o Desenvolvedor responde:**
- Que componentes/módulos/classes criar?
- Quais APIs implementar (endpoints REST/GraphQL)?
- Que padrões de código seguir? (DRY, SOLID, etc.)
- Quais variáveis de ambiente são necessárias?
- Como estruturar o código para ser testável?

**Análise a gerar:**

```markdown
## 💻 Requisitos do Desenvolvedor

### Componentes/Módulos a Criar

**Backend:**
1. **AuthService** (`src/services/auth.service.ts`)
   - Responsabilidade: Lógica de autenticação (login, logout, validação de token)
   - Métodos principais:
     - `login(email, password): Promise<{token, user}>`
     - `validateToken(token): Promise<User | null>`
     - `logout(userId): Promise<void>`

2. **UserRepository** (`src/repositories/user.repository.ts`)
   - Responsabilidade: Acesso a dados de usuários
   - Métodos principais:
     - `findByEmail(email): Promise<User | null>`
     - `create(userData): Promise<User>`
     - `updateLastLogin(userId): Promise<void>`

[...continuar para todos os módulos backend]

**Frontend:**
1. **LoginForm** (`components/auth/LoginForm.tsx`)
   - Responsabilidade: Formulário de login com validação
   - Props: `onSuccess, onError`
   - State: `email, password, loading, errors`

2. **AuthContext** (`contexts/AuthContext.tsx`)
   - Responsabilidade: Gerenciar estado global de autenticação
   - Funções exportadas: `useAuth(), login(), logout(), isAuthenticated()`

[...continuar para todos os componentes frontend]

### APIs a Implementar

**REST Endpoints:**

1. **POST /api/auth/login**
   - Descrição: Autenticar usuário com email e senha
   - Request body:
     ```json
     {
       "email": "string",
       "password": "string"
     }
     ```
   - Response (200):
     ```json
     {
       "success": true,
       "token": "jwt-token",
       "user": {
         "id": "uuid",
         "email": "string",
         "name": "string"
       }
     }
     ```
   - Response (401):
     ```json
     {
       "success": false,
       "error": "Invalid credentials"
     }
     ```

2. **POST /api/auth/logout**
   [Formato similar]

[...continuar para todas as APIs]

### Padrões de Código (DRY, SOLID, etc.)

**DRY (Don't Repeat Yourself):**
- Extrair validação de email para helper: `utils/validators.ts`
- Criar hook customizado `useFormValidation()` para reutilizar lógica de formulários

**SOLID:**
- **Single Responsibility**: Cada serviço tem uma responsabilidade única
- **Dependency Inversion**: Usar interfaces para repositories

**Padrões específicos:**
- Usar DTOs para transferência de dados entre camadas
- Implementar error handling centralizado
- Usar constants para mensagens de erro

### Variáveis de Ambiente

**Arquivo `.env.example`:**
```env
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# JWT
JWT_SECRET=your-secret-key-minimum-32-characters
JWT_EXPIRATION=7d

# External APIs
[Nome da API]_API_KEY=your-api-key
[Nome da API]_API_URL=https://api.example.com

# Environment
NODE_ENV=development
PORT=3000

Documentar no README:

• Como obter cada chave de API
• Valores padrão para desenvolvimento
• Valores de produção (onde configurar)

---

#### 3.3. 🎨 Especificações de Design/UX

**Foco:** Interface do usuário, acessibilidade, responsividade, experiência

**Perguntas que o Designer responde:**
- Como a UI deve se parecer?
- Quais componentes UI reutilizáveis criar?
- Como garantir acessibilidade (WCAG)?
- Como garantir responsividade (mobile, tablet, desktop)?
- Qual a jornada do usuário?

**Análise a gerar:**

```markdown
## 🎨 Especificações de Design/UX

### Wireframes/Mockups

[Se houver, descrever ou referenciar. Caso contrário, descrever textualmente]

**Tela de Login:**
- Layout centralizado verticalmente
- Card com sombra sutil
- Campos: Email (input), Senha (input type=password)
- Botão primário: "Entrar"
- Link secundário: "Esqueci minha senha"
- Logo da aplicação no topo

### Componentes UI Reutilizáveis

**1. Button** (`components/ui/Button.tsx`)
- Variantes: primary, secondary, danger, ghost
- Tamanhos: small, medium, large
- Estados: normal, hover, focus, disabled, loading

**2. Input** (`components/ui/Input.tsx`)
- Tipos: text, email, password, number
- Estados: normal, error, disabled
- Features: label, helper text, error message, icon

**3. Card** (`components/ui/Card.tsx`)
- Variantes: elevated, outlined, flat
- Slots: header, body, footer

[...continuar para todos os componentes UI]

### Acessibilidade (WCAG 2.1 Level AA)

**Requisitos obrigatórios:**
- ✅ Todos os inputs têm `<label>` associados
- ✅ Formulários têm `aria-label` ou `aria-labelledby`
- ✅ Botões têm texto descritivo (não apenas ícones)
- ✅ Contraste de cores mínimo 4.5:1 para texto normal
- ✅ Contraste de cores mínimo 3:1 para texto grande
- ✅ Navegação completa por teclado (Tab, Enter, Escape)
- ✅ Focus indicators visíveis
- ✅ Mensagens de erro anunciadas por screen readers (`role="alert"`)

**Implementação:**
```tsx
// Exemplo de input acessível
<div>
  <label htmlFor="email" className="sr-only">Email</label>
  <input
    id="email"
    type="email"
    placeholder="Digite seu email"
    aria-required="true"
    aria-invalid={errors.email ? "true" : "false"}
    aria-describedby={errors.email ? "email-error" : undefined}
  />
  {errors.email && (
    <p id="email-error" role="alert" className="text-red-600">
      {errors.email}
    </p>
  )}
</div>

Responsividade

Breakpoints:

• Mobile: 0-640px
• Tablet: 641px-1024px
• Desktop: 1025px+

Adaptações por device:

Mobile:

• Layout em coluna única
• Botões full-width
• Navegação em hamburger menu
• Font-size base: 16px (evitar zoom no iOS)

Tablet:

• Layout em 2 colunas onde apropriado
• Sidebar colapsável
• Font-size base: 16px

Desktop:

• Layout em grid (até 3-4 colunas)
• Sidebar fixa
• Font-size base: 16px
• Max-width do conteúdo: 1280px

Implementação (Tailwind CSS):

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  {/* Cards responsivos */}
</div>

Jornada do Usuário (User Flow)

Fluxo de Login:

1. Usuário acessa /login
2. Vê formulário de login
3. Preenche email e senha
4. Clica "Entrar"
5. Se sucesso: Redirecionado para /dashboard
6. Se erro: Vê mensagem de erro inline, foco retorna ao primeiro campo com erro

Estados de carregamento:

• Botão "Entrar" mostra spinner durante request
• Botão fica disabled durante loading
• Cursor muda para wait

Estados de erro:

• Mensagens de erro aparecem abaixo dos campos
• Cor vermelha (#DC2626)
• Ícone de alerta ao lado da mensagem
• Screen reader anuncia erro

---

#### 3.4. ✅ Requisitos de QA (Quality Assurance)

**Foco:** Estratégia de testes, cobertura, casos extremos, performance

**Perguntas que o QA responde:**
- Que casos de teste são necessários? (unitários, integração, E2E)
- Qual cobertura de testes atingir?
- Quais edge cases testar?
- Como testar performance?
- Que cenários de erro cobrir?

**Análise a gerar:**

```markdown
## ✅ Requisitos de QA (Quality Assurance)

### Estratégia de Testes

**Pirâmide de testes:**

    /\
   /E2E\        ← 10-15 testes (fluxos principais)
  /______\
 /  INT   \     ← 20-30 testes (integração de módulos)
/__________\

/ UNIT \ ← 50-70 testes (lógica de negócio) /______________\

**Frameworks:**
- **Unitários**: [Jest / Vitest / Mocha] (detectado do projeto)
- **Integração**: [Jest com supertest / etc.]
- **E2E**: Playwright

### Casos de Teste (Unitários)

**AuthService:**
1. `login()`
   - ✅ Deve retornar token JWT válido com credenciais corretas
   - ✅ Deve retornar erro com credenciais inválidas
   - ✅ Deve retornar erro se usuário não existe
   - ✅ Deve retornar erro se senha incorreta
   - ✅ Deve atualizar lastLoginAt do usuário
   - ✅ Deve hash a senha antes de comparar

2. `validateToken()`
   - ✅ Deve validar token JWT correto
   - ✅ Deve rejeitar token expirado
   - ✅ Deve rejeitar token malformado
   - ✅ Deve rejeitar token com assinatura inválida

[...continuar para todos os serviços/componentes]

**Exemplo de teste unitário:**
```typescript
describe('AuthService', () => {
  describe('login', () => {
    it('should return JWT token with valid credentials', async () => {
      const mockUser = { id: '1', email: 'test@example.com', passwordHash: 'hashed' }
      userRepository.findByEmail = jest.fn().mockResolvedValue(mockUser)
      bcrypt.compare = jest.fn().mockResolvedValue(true)

      const result = await authService.login('test@example.com', 'password123')

      expect(result.success).toBe(true)
      expect(result.token).toBeDefined()
      expect(jwt.verify(result.token, SECRET)).toBeTruthy()
    })

    it('should return error with invalid credentials', async () => {
      userRepository.findByEmail = jest.fn().mockResolvedValue(null)

      const result = await authService.login('invalid@example.com', 'wrong')

      expect(result.success).toBe(false)
      expect(result.error).toBe('Invalid credentials')
    })
  })
})

Casos de Teste (Integração)

API /api/auth/login:

1. ✅ POST com credenciais válidas retorna 200 e token
2. ✅ POST com credenciais inválidas retorna 401
3. ✅ POST sem email retorna 400
4. ✅ POST sem senha retorna 400
5. ✅ POST com email malformado retorna 400
6. ✅ POST com Content-Type errado retorna 415

[...continuar para todas as APIs]

Casos de Teste (E2E com Playwright)

Fluxo de Autenticação:

1. E2E: Usuário faz login com credenciais válidas

   • Navegar para /login
   • Preencher email: testuser@example.com
   • Preencher senha: ValidPassword123!
   • Clicar botão "Entrar"
   • Verificar: Redireciona para /dashboard
   • Verificar: Token salvo no localStorage
   • Verificar: Header mostra nome do usuário

2. E2E: Usuário tenta login com credenciais inválidas

   • Navegar para /login
   • Preencher email: testuser@example.com
   • Preencher senha: WrongPassword
   • Clicar botão "Entrar"
   • Verificar: Permanece em /login
   • Verificar: Mensagem de erro aparece: "Credenciais inválidas"
   • Verificar: Campo de senha é limpo
   • Verificar: Foco retorna ao campo de email

3. E2E: Validação de email inválido (client-side)

   • Navegar para /login
   • Preencher email: invalid-email
   • Preencher senha: password123
   • Clicar botão "Entrar"
   • Verificar: Mensagem de erro: "Email inválido"
   • Verificar: Request não é enviado ao servidor

4. E2E: Tratamento de erro de servidor (500)

   • [Mock do servidor para retornar 500]
   • Navegar para /login
   • Preencher credenciais válidas
   • Clicar botão "Entrar"
   • Verificar: Mensagem de erro: "Erro no servidor. Tente novamente."
   • Verificar: Botão volta ao estado normal

5. E2E: Fluxo completo (criar conta → login → acessar dashboard)

   • Navegar para /register
   • Preencher formulário de registro
   • Submeter e criar conta
   • Verificar: Redirecionado para /login
   • Fazer login com credenciais recém-criadas
   • Verificar: Redirecionado para /dashboard
   • Verificar: Dashboard mostra dados do usuário

[...continuar para todos os fluxos principais]

Exemplo de teste E2E:

// tests/e2e/auth.spec.ts
import { test, expect } from '@playwright/test'

test.describe('Authentication', () => {
  test('should allow user to login with valid credentials', async ({ page }) => {
    await page.goto('/login')

    await page.fill('input[name="email"]', 'testuser@example.com')
    await page.fill('input[name="password"]', 'ValidPassword123!')
    await page.click('button[type="submit"]')

    await expect(page).toHaveURL('/dashboard')

    const token = await page.evaluate(() => localStorage.getItem('authToken'))
    expect(token).toBeTruthy()

    await expect(page.locator('[data-testid="user-name"]')).toContainText('Test User')
  })
})

Cobertura de Testes

Metas:

• Unitários: >90% de cobertura de código
• Integração: 100% das APIs testadas
• E2E: 100% dos fluxos principais (happy paths + principais error paths)

Ferramentas:

• Coverage: jest --coverage ou vitest --coverage
• Reports: HTML coverage report em coverage/index.html

Edge Cases e Cenários de Erro

Lista de edge cases a testar:

1. ✅ Email com caracteres especiais válidos (ex: test+tag@example.com)
2. ✅ Senha com todos os tipos de caracteres especiais permitidos
3. ✅ Email com domínio internacional (IDN)
4. ✅ Múltiplas tentativas de login falhadas (rate limiting)
5. ✅ Login simultâneo de múltiplos dispositivos
6. ✅ Token expira durante navegação (refresh automático)
7. ✅ Conexão de rede perdida durante login
8. ✅ Request timeout (servidor lento)
9. ✅ Browser sem suporte a localStorage
10. ✅ JavaScript desabilitado (graceful degradation)

Lista de cenários de erro a testar:

1. ✅ Servidor retorna 500 (Internal Server Error)
2. ✅ Servidor retorna 503 (Service Unavailable)
3. ✅ Request timeout (>30s)
4. ✅ Network error (sem conexão)
5. ✅ CORS error (configuração incorreta)
6. ✅ JSON malformado na resposta
7. ✅ Token expirado no meio da sessão
8. ✅ Banco de dados indisponível

Testes de Performance

Requisitos:

• Tempo de resposta API /api/auth/login: <200ms (95th percentile)
• Tempo de carregamento inicial página /login: <1s
• Time to Interactive (TTI): <2s

Ferramentas:

• Lighthouse CI para métricas de performance
• Artillery ou k6 para load testing de API

Cenários de load testing:

1. 100 requests/segundo durante 1 minuto
2. 1000

…(truncated)