# Sprint Context Generator > Generates comprehensive sprint documentation (spec.md, plan.md, tasks.md, research.md, features.xml) following Spec-Driven Development methodology with multi-persona analysis (Architect, Dev, QA, Designer, PM, BA). Use when planning new features or refactoring existing ones. Compatible with long-running-agent. Automatically researches documentation (WebSearch/WebFetch), creates 50-100 granular tasks with E2E (Playwright) and TDD coverage, generates sequential feature IDs (FEAT-XXX), and creates git branch/commit. Always asks interactive questions to gather requirements before generating complete, production-ready context. - Skill: `madeinlowcode/sprint-context-generator` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add madeinlowcode/sprint-context-generator` - Raw SKILL.md: https://api.skillmd.com/api/skills/madeinlowcode/sprint-context-generator/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: madeinlowcode (https://skillmd.com/u/madeinlowcode) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/madeinlowcode/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//` **Extras:** - Branch Git criada automaticamente: `feature/FEAT-XXX-` - 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: ```bash 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//. Você poderá inicializar .claude/ mais tarde executando: python skills/long-running-agent/scripts/init_project.py ``` - Criar apenas `docs/context-log-running//` - 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//` **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: `/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:** ```markdown ### 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:** ```typescript // 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**: ```[linguagem] [código de exemplo extraído da documentação] ``` - **Configurações importantes**: - [Config 1]: [descrição] - [Config 2]: [descrição] - **Links úteis**: - [Seção da doc]: [URL] --- ### 1.2. [Nome da Tecnologia 2] [Mesmo formato] --- ## 2. Melhores Práticas Pesquisadas ### 2.1. Clean Architecture **Fontes:** - [Título do artigo/repo](URL) - [Título do artigo/repo](URL) **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](URL) - [Título](URL) **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:** ```typescript [Exemplo extraído da pesquisa] ``` --- ### 2.3. TDD (Test-Driven Development) **Fontes:** - [Título](URL) **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:** ```[linguagem] // 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](URL) **Configuração recomendada:** **`.eslintrc.js`:** ```javascript [Configuração extraída da pesquisa] ``` **`.prettierrc`:** ```json [Configuração extraída da pesquisa] ``` **Scripts package.json:** ```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](URL) **Setup completo:** 1. **Instalação:** ```bash npm install --save-dev husky lint-staged npx husky init ``` 2. **Configurar pre-commit** (`.husky/pre-commit`): ```bash #!/usr/bin/env sh . "$(dirname -- "$0")/_/husky.sh" npx lint-staged ``` 3. **Configurar lint-staged** (`package.json`): ```json { "lint-staged": { "*.{ts,tsx}": [ "eslint --fix", "prettier --write" ], "*.{json,md}": [ "prettier --write" ] } } ``` 4. **Configurar pre-push** (`.husky/pre-push`): ```bash #!/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](URL) - Resumo de 1 linha sobre o conteúdo - [Título do artigo 2](URL) - Resumo de 1 linha - [Título do artigo 3](URL) - 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:** ```json { "[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` - `logout(userId): Promise` 2. **UserRepository** (`src/repositories/user.repository.ts`) - Responsabilidade: Acesso a dados de usuários - Métodos principais: - `findByEmail(email): Promise` - `create(userData): Promise` - `updateLastLogin(userId): Promise` [...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 `