| name | spec-driven-workflow |
| description | Use quando o usuário pede para escrever specs antes do código, definir critérios de aceitação, planejar funcionalidades antes da implementação, gerar testes a partir de especificações, ou seguir práticas de desenvolvimento spec-first. |
| agents | ["claude-code"] |
Spec-Driven Workflow — PODEROSO
Visão Geral
O fluxo de trabalho orientado por spec impõe uma única regra inegociável: escreva a especificação ANTES de escrever qualquer código. Não junto. Não depois. Antes.
Isso não é documentação. Isso é um contrato. Uma spec define o que o sistema DEVE fazer, o que DEVERIA fazer e o que explicitamente NÃO FARÁ. Cada linha de código que você escreve remonta a um requisito na spec. Cada teste remonta a um critério de aceitação. Se não estiver na spec, não será construído.
Por Que Spec-First Importa
- Elimina retrabalho. 60-80% dos defeitos se originam dos requisitos, não da implementação. Detectar ambiguidade em uma spec custa minutos; detectá-la em produção custa dias.
- Força clareza. Se você não consegue escrever o que o sistema deve fazer em linguagem simples, você não entende o problema bem o suficiente para escrever código.
- Habilita paralelismo. Uma vez que a spec é aprovada, frontend, backend, QA e documentação podem todos começar simultaneamente.
- Cria responsabilidade. A spec é a definição de pronto. Sem discussões sobre se um recurso está "completo" — ou satisfaz os critérios de aceitação ou não satisfaz.
- Alimenta o TDD diretamente. Critérios de aceitação no formato Dado/Quando/Então se traduzem 1:1 em casos de teste. A spec É o plano de testes.
A Lei de Ferro
SEM CÓDIGO SEM UMA SPEC APROVADA.
SEM EXCEÇÕES. SEM "PROTÓTIPOS RÁPIDOS". SEM "VOU DOCUMENTAR DEPOIS."
Se a spec não foi escrita, revisada e aprovada, a implementação não começa. Ponto final.
O Formato da Spec
Toda spec segue esta estrutura. Nenhuma seção é opcional — se uma seção não se aplica, escreva "N/A — [motivo]" para que os revisores saibam que foi considerada, não esquecida.
Seções Obrigatórias
| # | Seção | Regras Principais |
|---|
| 1 | Título e Metadados | Autor, data, status (Rascunho/Em Revisão/Aprovado/Substituído), revisores |
| 2 | Contexto | Por que este recurso existe. 2-4 parágrafos com evidências (métricas, tickets). |
| 3 | Requisitos Funcionais | Palavras-chave RFC 2119 (DEVE/DEVERIA/PODE). Numerados como RF-N. Cada um é atômico e testável. |
| 4 | Requisitos Não-Funcionais | Desempenho, segurança, acessibilidade, escalabilidade, confiabilidade — todos com limites mensuráveis. |
| 5 | Critérios de Aceitação | Formato Dado/Quando/Então. Cada CA referencia pelo menos um RF-* ou RNF-*. |
| 6 | Casos Extremos | Numerados como CE-N. Cobrir modos de falha para cada dependência externa. |
| 7 | Contratos de API | Interfaces no estilo TypeScript. Cobrir respostas de sucesso e erro. |
| 8 | Modelos de Dados | Formato de tabela com campo, tipo, restrições. Toda entidade dos requisitos deve ter um modelo. |
| 9 | Fora do Escopo | Exclusões explícitas com motivos. Previne expansão de escopo durante a implementação. |
Palavras-Chave RFC 2119
| Palavra-Chave | Significado |
|---|
| DEVE | Requisito absoluto. Não conformante sem ele. |
| NÃO DEVE | Proibição absoluta. |
| DEVERIA | Recomendado. Omitir apenas com justificativa documentada. |
| PODE | Opcional. Discrição do implementador. |
Consulte spec_format_guide.md para o template completo com exemplos seção a seção, padrões bons/ruins de requisitos e templates por tipo de recurso (CRUD, Integração, Migração).
Consulte acceptance_criteria_patterns.md para uma biblioteca completa de padrões de critérios Dado/Quando/Então para autenticação, CRUD, busca, upload de arquivo, pagamento, notificação e cenários de acessibilidade.
Regras de Autonomia Limitada
Estas regras definem quando um agente (humano ou IA) DEVE parar e pedir orientação versus quando pode prosseguir independentemente.
PARAR e Perguntar Quando:
-
Expansão de escopo detectada. A implementação requer algo não presente na spec. Mesmo que pareça obviamente necessário, PARE. A spec pode ter excluído deliberadamente.
-
Ambiguidade excede 30%. Se você não consegue determinar o comportamento correto a partir da spec para mais de 30% de um dado requisito, a spec está incompleta. Não adivinhe.
-
Mudanças disruptivas necessárias. A implementação mudaria um contrato de API existente, esquema de banco de dados ou interface pública. Sempre escale.
-
Implicações de segurança. Qualquer mudança que toque autenticação, autorização, criptografia ou tratamento de PII requer aprovação explícita.
-
Características de desempenho desconhecidas. Se um requisito diz "DEVE concluir em < 500ms" mas você não tem como medir ou garantir isso, escale antes de implementar um palpite.
-
Dependências entre equipes. Se a spec requer coordenação com outra equipe ou serviço, confirme a dependência antes de construir contra ela.
Continuar Autonomamente Quando:
- Spec é clara e inequívoca para a tarefa atual.
- Todos os critérios de aceitação têm testes passando e você está refatorando internos.
- Mudanças são não-disruptivas — sem mudanças de API pública, esquema ou comportamento.
- Implementação é uma tradução direta de um critério de aceitação bem definido.
- Tratamento de erros segue padrões estabelecidos já documentados na base de código.
Protocolo de Escalonamento
Quando você deve parar, forneça:
## Escalonamento: [Título Breve]
**Bloqueado em:** [ID do requisito, ex.: RF-3]
**Questão:** [Pergunta específica e respondível — não "o que devo fazer?"]
**Opções consideradas:**
A. [Opção] — Prós: [...] Contras: [...]
B. [Opção] — Prós: [...] Contras: [...]
**Minha recomendação:** [A ou B, com raciocínio]
**Impacto de esperar:** [O que está bloqueado até isso ser resolvido?]
Nunca escale sem uma recomendação. Nunca apresente uma pergunta aberta. Sempre dê opções.
Consulte references/bounded_autonomy_rules.md para a matriz completa de decisão.
Fluxo de Trabalho — 6 Fases
Fase 1: Coletar Requisitos
Objetivo: Entender o que precisa ser construído e por quê.
- Entrevistar o usuário. Perguntar:
- Que problema isso resolve?
- Quem são os usuários?
- Como é o sucesso?
- O que explicitamente NÃO deve ser construído?
- Ler o código existente. Entender o sistema atual antes de propor mudanças.
- Identificar restrições. Orçamentos de desempenho, requisitos de segurança, compatibilidade retroativa.
- Listar desconhecidos. Cada desconhecido é um risco. Exponha-os agora, não durante a implementação.
Critério de saída: Você pode explicar o recurso para alguém não familiarizado com o projeto em 2 minutos.
Fase 2: Escrever Spec
Objetivo: Produzir um documento de spec completo seguindo O Formato da Spec acima.
- Preencher cada seção do template. Nenhuma seção em branco.
- Numerar todos os requisitos (RF-, RNF-, CA-, CE-, FE-*).
- Usar palavras-chave RFC 2119 com precisão.
- Escrever critérios de aceitação no formato Dado/Quando/Então.
- Definir contratos de API com tipos no estilo TypeScript.
- Listar exclusões explícitas em Fora do Escopo.
Critério de saída: A spec pode ser entregue a um desenvolvedor que não estava na reunião de requisitos, e ele pode implementar o recurso sem fazer perguntas de esclarecimento.
Fase 3: Validar Spec
Objetivo: Verificar se a spec está completa, consistente e implementável.
Executar spec_validator.py contra o arquivo de spec:
python spec_validator.py --file spec.md --strict
Lista de verificação de validação manual:
Critério de saída: Spec pontua 80+ no validador, e todos os itens da lista de verificação manual passam.
Fase 4: Gerar Testes
Objetivo: Extrair casos de teste dos critérios de aceitação antes de escrever o código de implementação.
Executar test_extractor.py contra a spec aprovada:
python test_extractor.py --file spec.md --framework pytest --output tests/
- Cada critério de aceitação se torna um ou mais casos de teste.
- Cada caso extremo se torna um caso de teste.
- Os testes são stubs — definem a asserção mas não a implementação.
- Todos os testes DEVEM falhar inicialmente (fase vermelha do TDD).
Critério de saída: Você tem um arquivo de teste onde todo teste falha com "não implementado" ou equivalente.
Fase 5: Implementar
Objetivo: Escrever código que faça os testes com falha passarem, um critério de aceitação por vez.
- Escolher um critério de aceitação (começar pelo mais simples).
- Fazer seus teste(s) passarem com código mínimo.
- Executar o conjunto completo de testes — sem regressões.
- Fazer commit.
- Escolher o próximo critério de aceitação. Repetir.
Regras:
- NÃO implementar nada que não esteja na spec.
- NÃO otimizar antes de todos os critérios de aceitação passarem.
- NÃO refatorar antes de todos os critérios de aceitação passarem.
- Se você descobrir um requisito ausente, PARE e atualize a spec primeiro.
Critério de saída: Todos os testes passam. Todos os critérios de aceitação satisfeitos.
Fase 6: Auto-Revisão
Objetivo: Verificar se a implementação corresponde à spec antes de marcar como pronto.
Percorrer a Lista de Verificação de Auto-Revisão abaixo. Se algum item falhar, corrija antes de declarar a tarefa concluída.
Lista de Verificação de Auto-Revisão
Antes de marcar qualquer implementação como pronta, verificar TODOS os seguintes:
Integração com Guia de TDD
O fluxo de trabalho orientado por spec e o TDD são complementares, não concorrentes:
Spec-Driven Workflow TDD (Red-Green-Refactor)
───────────────────── ──────────────────────────
Fase 1: Coletar Requisitos
Fase 2: Escrever Spec
Fase 3: Validar Spec
Fase 4: Gerar Testes ──→ VERMELHO: Testes existem e falham
Fase 5: Implementar ──→ VERDE: Código mínimo para passar
Fase 6: Auto-Revisão ──→ REFATORAR: Limpar internos
A transferência: O fluxo de trabalho orientado por spec produz os stubs de teste (Fase 4). O TDD assume a partir daí. A spec diz O QUE testar. O TDD diz COMO implementar.
Use engineering-team/tdd-guide para:
- Disciplina do ciclo red-green-refactor
- Análise de cobertura e detecção de lacunas
- Padrões de teste específicos por framework (Jest, Pytest, JUnit)
Use engineering/spec-driven-workflow para:
- Definir o que construir antes de construir
- Autoria de critérios de aceitação
- Validação de completude
- Controle de escopo
Exemplos
Um exemplo completo trabalhado (spec de Redefinição de Senha com casos de teste extraídos) está disponível em spec_format_guide.md. Demonstra todas as 9 seções, numeração de requisitos, critérios de aceitação, casos extremos e os stubs de pytest correspondentes gerados por test_extractor.py.
Anti-Padrões
1. Codificar Antes da Aprovação da Spec
Sintoma: "Vou começar a codificar enquanto a spec está sendo revisada."
Problema: A revisão levantará mudanças. Agora você tem código que implementa um design rejeitado.
Regra: A implementação não começa até que o status da spec seja "Aprovado."
2. Critérios de Aceitação Vagos
Sintoma: "O sistema deve funcionar bem" ou "A UI deve ser responsiva."
Problema: Não testável. O que "bem" significa? O que "responsiva" significa?
Regra: Todo critério de aceitação deve ser verificável por uma máquina. Se você não consegue escrever um teste para ele, reescreva o critério.
3. Casos Extremos Ausentes
Sintoma: O caminho feliz é especificado, os caminhos de erro não são.
Problema: Os desenvolvedores inventam tratamento de erros on-the-fly, levando a comportamento inconsistente.
Regra: Para cada dependência externa (API, banco de dados, sistema de arquivos, entrada do usuário), especifique pelo menos um cenário de falha.
4. Spec como Documentação Post-Hoc
Sintoma: "Deixa eu escrever a spec agora que o recurso está pronto."
Problema: Isso é documentação, não especificação. Descreve o que foi construído, não o que deveria ter sido construído. Não pode detectar erros de design porque o design já está congelado.
Regra: Se a spec foi escrita após o código, não é uma spec. Rotule como documentação.
5. Gold-Plating Além da Spec
Sintoma: "Enquanto estava lá, também adicionei..."
Problema: Código não testado. Design não revisado. Potencial para bugs sutis no recurso "bônus".
Regra: Se não está na spec, não é construído. Crie uma nova spec para recursos adicionais.
6. Critérios de Aceitação Sem Rastreabilidade de Requisito
Sintoma: CA-7 existe mas não referencia nenhum RF-* ou RNF-.
Problema: Critérios órfãos significam que um requisito está ausente ou o critério é desnecessário.
Regra: Todo CA- DEVE referenciar pelo menos um RF-* ou RNF-*.
7. Pular a Validação
Sintoma: "A spec parece boa, vamos começar."
Problema: Seções ausentes descobertas durante a implementação causam atrasos bloqueantes.
Regra: Sempre execute spec_validator.py --strict antes de iniciar a implementação. Corrija todos os avisos.
Referências Cruzadas
engineering-team/tdd-guide — Ciclo red-green-refactor, geração de testes, análise de cobertura. Use após a Fase 4 deste fluxo de trabalho.engineering/focused-fix — Reparo profundo de recurso. Quando uma implementação orientada por spec tem problemas sistêmicos, use focused-fix para diagnóstico.engineering/rag-architect — Se o recurso envolve recuperação ou sistemas de conhecimento, use rag-architect para o design técnico dentro da spec.references/spec_format_guide.md — Template completo com explicações seção a seção.references/bounded_autonomy_rules.md — Matriz completa de decisão para quando parar versus continuar.references/acceptance_criteria_patterns.md — Biblioteca de padrões para escrever critérios Dado/Quando/Então.
Ferramentas
| Script | Propósito | Flags Principais |
|---|
spec_generator.py | Gerar template de spec a partir do nome/descrição do recurso | --name, --description, --format, --json |
spec_validator.py | Validar completude da spec (pontuação 0-100) | --file, --strict, --json |
test_extractor.py | Extrair stubs de teste dos critérios de aceitação | --file, --framework, --output, --json |
python spec_generator.py --name "User Authentication" --description "OAuth 2.0 login flow"
python spec_validator.py --file specs/auth.md --strict
python test_extractor.py --file specs/auth.md --framework pytest --output tests/test_auth.py
