GalRogozinski/sdd

Skill de Desenvolvimento Orientado por Especificações (SDD)

Guie os usuários pelo Spec-Kit do GitHub para Desenvolvimento Orientado por Especificações - uma metodologia que inverte o desenvolvimento de software tradicional ao tornar as especificações executáveis e gerar implementações funcionais diretamente.

Filosofia Central

O Desenvolvimento Orientado por Especificações enfatiza:

• Desenvolvimento orientado por intenção: Defina o "o quê" antes do "como"
• Criação de especificações ricas: Use diretrizes e princípios organizacionais
• Refinamento em várias etapas: Não é geração de código única
• Nativo de IA: Dependência pesada de capacidades avançadas de IA

Lembre-se: Isto é desenvolvimento nativo de IA. As especificações não são apenas documentação - são artefatos executáveis que impulsionam diretamente a implementação. O agente de IA as usa para gerar código funcional que corresponde à intenção definida nas especificações.

Critérios de Aceitação: Formato Gherkin (Obrigatório)

Toda história de usuário em cada spec.md (ou specify.md) DEVE incluir critérios de aceitação no estilo Gherkin, além de sua descrição em prosa. Isso se aplica tanto a greenfield quanto a brownfield, a cada história de usuário, e independentemente de o artefato ter sido produzido por /speckit.specify ou escrito manualmente para um repositório que não usa o modelo gerado pela CLI. A prosa diz sobre o que é a história; os cenários Gherkin dizem exatamente como verificá-la — é isso que torna uma especificação executável em vez de descritiva.

Formato — um bloco gherkin formatado (com cercas) diretamente abaixo de cada história de usuário, com 1 a 4 cenários: o caminho feliz primeiro, depois os casos de borda/negativos que importam para aquela história (não todos os casos de borda da especificação — estes pertencem à seção de Casos de Borda da própria especificação; apenas os específicos desta história).

Cenário: <nome curto e específico — não "caminho feliz">
  Dado <a pré-condição / estado inicial>
  Quando <a única ação que o ator realiza>
  Então <o resultado observável e testável>
  E <resultado adicional, se necessário>

Cenário: <o caso de borda/negativo para esta história>
  Dado <pré-condição>
  Quando <ação>
  Então <resultado — o que NÃO deve acontecer é um Então válido>

Regras de escrita:

• Um Quando por cenário. Múltiplas ações significam múltiplos cenários — isso mantém cada cenário mapeado para um teste.
• Então deve ser observável, não interno: "o usuário vê um toast de confirmação," não "o estado é atualizado corretamente." Se você não consegue dizer como alguém verificaria, não está pronto.
• Reutilize o vocabulário da própria especificação. As etapas Dado/Quando/Então devem usar os mesmos substantivos da história de usuário e dos requisitos funcionais (nomes de ativos, tipos de negócio, nomes de campos) — não parafraseados.
• Não reformule os requisitos funcionais como Gherkin. Critérios de aceitação verificam a história; os RFs são rastreados separadamente. Sobreposição é aceitável, duplicação de cada RF como um cenário não é.
• Numerar cenários para rastreabilidade quando uma história tem mais de um: Cenário: CA-1 — ..., Cenário: CA-2 — ... (opcional para histórias de um único cenário).

Ao resumir (o modelo de 10 pontos, "O Que Foi Gerado"), reporte a contagem de cenários juntamente com as contagens de história de usuário/critérios de sucesso, por exemplo, "5 histórias de usuário (11 cenários Gherkin), 8 critérios de sucesso." Se uma história de usuário estiver sem critérios de aceitação, sinalize-a em "🔍 Itens Importantes para Revisar" antes de prosseguir para /speckit.plan — planos construídos sobre histórias sem critérios de aceitação tendem a subespecificar testes.

ACs Comportamentais: apenas para histórias com LLM no circuito

Gherkin assume que uma execução decide aprovação/reprovação. Isso falha quando a saída de um modelo decide o resultado: uma execução verde de uma história não determinística prova quase nada. Para essas histórias, adicione um bloco ACs Comportamentais abaixo do bloco Gherkin.

Gere-o apenas quando o resultado observável da história depende da saída de um modelo. Exemplos: um prompt, prompt de sistema, missão, arquivo de skill ou descrição de ferramenta muda; um modelo escolhe a ação, julga ou resolve algo, ou escreve o texto voltado ao usuário; o modelo ou seus parâmetros mudam. Não o gere para código determinístico, renderização de UI de dados armazenados, encanamento, ou uma história onde uma chamada de modelo está presente mas sua saída não é assertada. Em caso de dúvida, faça uma pergunta; não adicione o bloco especulativamente. Uma especificação sem histórias com LLM no circuito não tem ACs Comportamentais, e nenhum espaço reservado vazio.

Formato: um bloco por história qualificativa, diretamente após seu Gherkin.

**ACs Comportamentais** (LLM no circuito: <o que o modelo decide>)
- **Casos:** <N> casos em `<caminho para o conjunto de casos>`, de <falhas reais / rastros / transcrições>; entradas sintéticas apenas para preencher lacunas, nunca saídas esperadas sintéticas
- **Execuções:** k = <k> por caso (≈ 3 / taxa de falha esperada; 20–30 se desconhecida)
- **Barra de aprovação:** <métrica> ≥ <limiar> sobre k, supera a linha de base por mais que o ruído (comparação pareada com a versão atual)
- **Avaliador:** verificação de código | juiz LLM (binário, um por modo de falha) | humano; um juiz também nomeia sua validação: TPR/TNR ≥ 0,9 (piso 0,8) em rótulos humanos retidos, ou "NÃO VALIDADO" dito claramente
- **Comando:** `<um comando que executa e imprime taxa de aprovação, custo e latência>`

Regras:

• Apenas uma execução real do modelo conta. Um mock, uma simulação de palavra-chave ou uma pontuação prevista não é um resultado. Se não puder ser executado (custo, chaves), diga que a história é NÃO AVALIADA. Não invente um número.
• Prefira um avaliador de código. Use um juiz apenas para o que o código não pode verificar.
• Gherkin ainda se aplica. Os cenários Gherkin cobrem a parte determinística (artefatos escritos, garantias mantidas). Os ACs Comportamentais cobrem o comportamento do modelo.
• plan.md carrega a avaliação: a localização do conjunto de casos, o comando de execução, o custo por execução e quando executa (por PR, ou somente pré-merge se for caro).

Ao resumir, conte-os separadamente, por exemplo, "5 histórias de usuário (11 cenários Gherkin, 2 com ACs Comportamentais)". Sinalize em "Itens Importantes para Revisar" qualquer história com LLM no circuito que esteja sem o bloco, e qualquer juiz marcado como NÃO VALIDADO.

Árvore de Decisão Rápida

Este é um novo projeto (greenfield)?

→ Veja Fluxo Greenfield para o processo completo de 6 etapas

Esta é uma base de código existente (brownfield)?

→ Veja Fluxo Brownfield para orientação de engenharia reversa e integração

Precisa de ajuda com instalação?

→ Veja Guia de Instalação para configuração e solução de problemas

Instalação Rápida

Recomendado (Persistente):

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Uso Único:

uvx --from git+https://github.com/github/spec-kit.git specify init <NOME_DO_PROJETO>

Verificar:

specify check

Para opções detalhadas de instalação, solução de problemas e variáveis de ambiente, veja Guia de Instalação.

Agentes de IA Suportados

Funciona com:

• ✅ Claude Code
• ✅ GitHub Copilot
• ✅ Gemini CLI
• ✅ Cursor
• ✅ Qwen Code
• ✅ opencode
• ✅ Windsurf
• ✅ Kilo Code
• ✅ Auggie CLI
• ✅ CodeBuddy CLI
• ✅ Roo Code
• ✅ Codex CLI
• ✅ Amp
• ⚠️ Amazon Q Developer CLI (não suporta argumentos personalizados para comandos de barra)

Sumarização de Artefatos e Ciclo de Feedback

FLUXO DE TRABALHO CRÍTICO: Após qualquer comando SDD gerar ou modificar artefatos, siga automaticamente este ciclo de feedback para manter o usuário engajado:

Após Cada Comando Concluído

1. Detectar Mudanças em Artefatos

   • Identifique quais artefatos foram criados ou modificados:
     • constitution.md (princípios do projeto)
     • spec.md (especificação de requisitos)
     • plan.md (plano de implementação técnica)
     • tasks.md (decomposição de tarefas acionáveis)
     • Relatórios de análise de fluxos brownfield

2. Ler e Sumarizar

   • Leia o(s) artefato(s) relevante(s)
   • Extraia informações-chave:
     • Para constitution.md: Princípios centrais, padrões de codificação, restrições
     • Para spec.md: Requisitos principais, histórias de usuário (com seus critérios de aceitação Gherkin), critérios de sucesso
     • Para plan.md: Escolhas de stack tecnológico, decisões de arquitetura, marcos
     • Para tasks.md: Número de tarefas, categorias principais de tarefas, dependências
     • Para relatórios de análise: Padrões atuais, dívida técnica, pontos de integração

3. Apresentar Resumo Estruturado (Use o Modelo de 10 Pontos Abaixo)

   • Mostre o que foi gerado e por quê
   • Destaque as decisões mais importantes com fundamentação
   • Inclua indicadores de qualidade e pontos de atenção
   • Mantenha o resumo focado e acionável
   • Use títulos claros para cada seção

4. Incluir Status do Recurso (Abordagem Híbrida)

   • Breve linha de status em cada resumo
   • Status detalhado sob demanda com /speckit.status
   • Veja a seção "Rastreamento de Status do Recurso" abaixo

5. Oferecer Opções de Feedback

   • Opção A: "Parece bom, prossiga para o próximo passo"
   • Opção B: "Gostaria de modificar [seção específica]"
   • Opção C: "Regenerar com estas alterações: [entrada do usuário]"
   • Opção D: "Explique por que [decisão específica] foi tomada"

Modelo de Resumo de 10 Pontos

Use este formato estruturado APÓS qualquer comando SDD ser concluído:

## ✅ [Nome do Comando] Concluído - Aqui Está o Que Aconteceu

### 🎯 Decisões-Chave Tomadas (Top 3)
1. [Decisão] - **Fundamentação:** [Por que isso foi escolhido]
2. [Decisão] - **Fundamentação:** [Por que isso foi escolhido]
3. [Decisão] - **Fundamentação:** [Por que isso foi escolhido]

### 📋 O Que Foi Gerado
- [Artefato 1]: [Breve descrição do conteúdo]
- [Artefato 2]: [Breve descrição do conteúdo]

### 🔍 Itens Importantes para Revisar (Top 3)
1. [Item crítico para verificar e por que é importante]
2. [Detalhe importante para verificar e impacto potencial]
3. [Caso de borda a considerar e como afeta o design]

### ⚠️ Cuidado Com (Top 2)
- [Problema potencial ou pegadinha] - **Como evitar:** [Orientação]
- [Erro comum] - **Como evitar:** [Orientação]

### 🔄 O Que Isso Permite em Seguida (2 Opções)
- **Opção 1:** [Próximo passo] - Melhor se: [Condição]
- **Opção 2:** [Passo alternativo] - Melhor se: [Condição]

📊 **Status do Recurso:** [Nome do Recurso Atual] ([Estágio]) → Próximo: [Próximo Recurso]
   Progresso: [●●●○○] [X]% | Concluídos: [N] de [Total] recursos | Dependências: [Status]

**Suas opções:** [A] Prosseguir [B] Modificar [C] Explicar mais [D] Mostrar status completo

Exemplo: Sumarização Aprimorada Após /speckit.specify

## ✅ Specify Concluído - Aqui Está o Que Aconteceu

### 🎯 Decisões-Chave Tomadas
1. **Autenticação: Tokens JWT** - Fundamentação: Arquitetura sem estado, escalável horizontalmente, padrão da indústria
2. **Requisitos de senha: 12+ caracteres com complexidade** - Fundamentação: Equilibra segurança (diretrizes NIST) com usabilidade
3. **Tempo limite de sessão: 24 horas** - Fundamentação: Padrão para aplicações web, equilibra segurança vs conveniência do usuário

### 📋 O Que Foi Gerado
- `.speckit/features/user-auth/specify.md`: Requisitos completos com 5 histórias de usuário (12 cenários de critérios de aceitação Gherkin), 8 critérios de sucesso, 3 casos de borda

### 🔍 Itens Importantes para Revisar
1. **Fluxo de redefinição de senha** - Verifique se os requisitos de e-mail correspondem à sua infraestrutura (servidor SMTP, modelos)
2. **Autenticação multifator** - Atualmente marcada como "melhoria futura"; pode ser necessária no MVP
3. **Limitação de taxa** - Definida em 5 tentativas de login a cada 15 min; considere se isso se adequa à sua política de segurança

### ⚠️ Cuidado Com
- **Dependência de serviço de e-mail não especificada** - Como evitar: Adicione serviço de e-mail às dependências do plan.md
- **Conformidade com GDPR para dados do usuário** - Como evitar: Revise os requisitos de retenção de dados e exclusão de usuário

### 🔄 O Que Isso Permite em Seguida
- **Opção 1:** Executar `/speckit.plan` para projetar a implementação técnica - Melhor se: Os requisitos parecem bons
- **Opção 2:** Modificar specify.md - Melhor se: Você precisa ajustar requisitos ou adicionar recursos

📊 **Status do Recurso:** user-authentication (Especificado) → Próximo: profile-management
   Progresso: [●●○○○] 40% | Concluídos: 1 de 5 recursos | Dependências: database-setup ✅

**Suas opções:** [A] Prosseguir para o planejamento [B] Modificar requisitos [C] Explicar escolha do JWT [D] Mostrar status completo

Quando Pular a Sumarização

Pule a etapa de sumarização apenas quando:

• O usuário solicitar explicitamente "pular resumos" ou "executar todas as etapas automaticamente"
• Reexecutar um comando sem alterações nos artefatos
• O comando falhar ou produzir erros (solucione o problema em vez disso)

Benefícios Deste Fluxo de Trabalho

• Elimina a sensação de "caixa preta": Explicações claras sobre o que foi gerado e por quê
• Permite feedback precoce: Detecte mal-entendidos antes da implementação
• Mantém a agilidade: Revisão rápida com formato estruturado, não processos de aprovação longos
• Constrói confiança: O usuário vê o raciocínio e as decisões da IA com fundamentação
• Fornece contexto: O status do recurso mantém os usuários orientados no projeto geral

Rastreamento de Status do Recurso

Abordagem Híbrida

Após cada comando SDD, inclua uma breve linha de status do recurso no resumo. Forneça status detalhado sob demanda com /speckit.status.

Formato da Linha de Status Breve

Inclua isto ao final de cada resumo:

📊 **Status do Recurso:** [Nome do Recurso Atual] ([Estágio]) → Próximo: [Nome do Próximo Recurso]
   Progresso: [●●●○○] [X]% | Concluídos: [N] de [Total] recursos | Dependências: [Dep] ✅/⏸️

Valores de Estágio:

• Especificando (20% completo)
• Planejando (40% completo)
• Definindo Tarefas (60% completo)
• Em Andamento (80% completo)
• Concluído (100% completo)

Indicador de Progresso:

• Use círculos preenchidos (●) para estágios concluídos
• Use círculos vazios (○) para estágios pendentes
• Calcule a porcentagem com base no estágio

Painel de Status Detalhado

Quando o usuário solicitar status completo (opção D) ou executar /speckit.status, mostre:

📊 Painel de Status dos Recursos do Projeto

🎯 RECURSO ATUAL
├─ [nome-do-recurso] ([Estágio] - [X]% completo)
│  ├─ ✅ Requisitos especificados
│  ├─ 🔄 Plano de implementação em andamento
│  ├─ ⏸️  Tarefas não iniciadas
│  └─ ⏸️  Implementação não iniciada
│  Bloqueios: [Nenhum | Descrição]
│  Dependências: [nome-do-recurso] ✅

✅ RECURSOS CONCLUÍDOS ([N])
├─ [recurso-1] (100% completo)
└─ [recurso-2] (100% completo)

📋 PRÓXIMOS RECURSOS ([N])
├─ [recurso-3] (depende de: [recurso-atual])
└─ [recurso-4] (depende de: [recurso-3])

⚠️  RECURSOS BLOQUEADOS

...

Formato do Comando /speckit.status

Exemplo de saída:

📊 **Status do Recurso:** user-authentication (Planejando - 40% completo) → Próximo: profile-management
   Progresso: [●●○○○] 40% | Concluídos: 1 de 5 recursos | Dependências: database-setup ✅

Guia do Fluxo Greenfield

Etapa 1: Estabelecer os Princípios do Projeto

Comando: /speckit.constitute <PROJECT_NAME>

Gera constitution.md definindo:

• Pilares de qualidade (performance, segurança, manutenibilidade, observabilidade, confiabilidade, escalabilidade, custo-efetividade, acessibilidade)
• Padrões de codificação e princípios de design
• Restrições do projeto (linguagens, stacks, serviços, práticas proibidas)
• Processo de desenvolvimento

Após o comando, forneça o resumo de 10 pontos.

Etapa 2: Especificar Requisitos

Comando: /speckit.specify

Gera spec.md com:

• Nome do projeto e visão geral
• Funcionalidades principais com histórias de usuário, critérios de aceitação Gherkin, casos de borda e critérios de sucesso
• Cenários de uso detalhados
• Questões abertas e premissas

Após o comando, forneça o resumo de 10 pontos.

Etapa 3: Projetar a Implementação

Comando: /speckit.plan

Gera plan.md com:

• Stack tecnológico e justificativa
• Decisões de arquitetura (diagramas C4, lógica de roteamento, modelo de dados, design de API, etc.)
• Dependências e riscos
• Marcos e cronograma de entrega

Após o comando, forneça o resumo de 10 pontos.

Etapa 4: Decomposição em Tarefas

Comando: /speckit.task

Gera tasks.md com:

• Tarefas acionáveis específicas para desenvolvedores
• Estruturas de dependência
• Custos estimados (tempo, tokens de LLM, serviços externos)

Após o comando, forneça o resumo de 10 pontos.

Etapa 5: Implementar

Ação: Comece a implementar com base em tasks.md. O desenvolvedor pode começar com qualquer tarefa.

Orientação para o desenvolvedor: Assistência na implementação das tarefas, começando pelas tarefas-folha (sem dependências), e avançando para níveis superiores.

Etapa 6: Verificar

Comando: /speckit.verify

Execute plan.md e spec.md em relação ao código implementado para:

• Validar se a implementação corresponde à especificação
• Verificar marcos do plano
• Gerar relatório de verificação

Após o comando, forneça o resumo de 10 pontos.

Guia do Fluxo Brownfield

Etapa 1: Escolher uma Estratégia de Análise de Código

Comando: /speckit.analyze

Escolha uma das seguintes estratégias:

1. Análise de Estrutura de Diretórios: Mapeamento rápido da estrutura de diretórios
2. Análise de Stack Tecnológico: Detecta frameworks, linguagens e dependências
3. Análise de Padrões de Código: Identifica padrões arquiteturais, dívida técnica e qualidade do código
4. Análise de Fluxo de Dados: Mapeia entradas, saídas e transformações de dados
5. Análise de Configuração e Infraestrutura: Examina arquivos de configuração, scripts de CI/CD, configuração de infraestrutura
6. Análise de Documentação e Feedback: Analisa documentação existente, relatórios de bugs, feedback de usuários
7. Mapeamento de Funcionalidades (Completo): Mapeia funcionalidades e comportamentos do sistema
8. Análise de Código Personalizada: Forneça um prompt de análise específico

Após cada análise, forneça o resumo de 10 pontos.

Etapa 2: Especificar (Talvez com Integração de Código Existente)

Comando: /speckit.specify

Igual ao fluxo greenfield, mas a especificação deve incluir:

• Integração com código existente
• Refatoração e modernização
• Compatibilidade reversa

Etapa 3-6: Planejar, Definir Tarefas, Implementar, Verificar

Siga as etapas 3 a 6 do fluxo greenfield.

Referências

• Fluxo Greenfield
• Fluxo Brownfield
• Guia de Instalação