Spec-Gatekeeper: Fluxo de Desenvolvimento Orientado por Especificações
Use esta skill sempre que a escrita de código-fonte for bloqueada pelo spec-gatekeeper, ou ao iniciar uma nova funcionalidade, serviço ou refatoração substancial.
O Desenvolvimento Orientado por Especificações (DDD) garante clareza e elimina desvios ao exigir um contrato arquitetural estruturado e acordado antes da implementação.
Etapas do Fluxo
Etapa 1: Conduzir a Entrevista de 4 Perguntas com o Desenvolvedor
Antes de escrever qualquer código ou criar arquivos, faça as seguintes 4 perguntas ao desenvolvedor (ou extraia respostas dos requisitos existentes e peça confirmação):
-
Escopo e Segurança:
- Quais são os objetivos principais e as não-metas explícitas desta tarefa?
- Quais componentes arquiteturais ou limites do sistema estão envolvidos?
- Quais são as restrições de segurança, permissões, autenticação ou sandbox?
-
Contratos de Dados:
- Quais são os esquemas exatos, interfaces de API, tipos e formatos de protocolo?
- Quais são os parâmetros de entrada precisos e as cargas de saída esperadas?
-
Casos Extremos e Resiliência:
- Quais são os principais modos de falha, interrupções de rede/E/S e entradas malformadas?
- Quais mecanismos de tratamento de erros, validação e fallback devem estar em vigor?
-
Critérios de Aceitação:
- Qual matriz de verificação determinística e casos de teste definem "Concluído"?
- Como cada critério de aceitação será validado?
Etapa 2: Elaborar SPEC.md
Crie ou atualize SPEC.md na raiz do projeto resolvida (<repo_root>/SPEC.md).
Estrutura Obrigatória
O arquivo de especificação deve atender a:
- Requisito de Tamanho: Pelo menos 300 bytes UTF-8 de conteúdo substantivo.
- Cabeçalhos de Seção Canônicos: Cabeçalhos Markdown de nível 1 a 3 fora de blocos de código, correspondendo a cada uma das 4 seções obrigatórias:
- Escopo e Segurança: Cabeçalhos contendo
Escopo,Segurança,Arquitetura,Visão Geral,Visão,Limites,Modelo de AmeaçasouPermissões. - Contratos de Dados: Cabeçalhos contendo
Contrato de Dados,Contratos de Dados,Esquema,Esquemas,Interface,Interfaces,API,Tipos,PayloadouProtocolo. - Casos Extremos: Cabeçalhos contendo
Caso Extremo,Casos Extremos,Tratamento de Erros,Modo de Falha,Resiliência,RestriçõesouFallbacks. - Critérios de Aceitação: Cabeçalhos contendo
Critério de Aceitação,Critérios de Aceitação,Teste de Aceitação,Matriz de Teste,Verificação,Testagem,Definição de ProntoouValidação.
- Escopo e Segurança: Cabeçalhos contendo
Modelo
# Especificação: <Nome da Funcionalidade ou Serviço>
## 1. Escopo e Segurança
### Objetivos e Limites Arquiteturais
- Descrição detalhada do escopo...
### Segurança e Modelo de Ameaças
- Verificações de permissão e limites de segurança...
## 2. Contratos de Dados
### Esquemas e Interfaces
- Tipos, assinaturas de API, formatos de requisição/resposta...
## 3. Casos Extremos e Resiliência
### Tratamento de Erros e Fallbacks
- Condições de contorno, validação de entrada, modos de falha...
## 4. Critérios de Aceitação
### Verificação e Matriz de Teste
- AT-01: ...
- AT-02: ...
Etapa 3: Aprovação do Desenvolvedor e Implementação
- Apresente o rascunho do
SPEC.mdao desenvolvedor para revisão e aprovação explícita. - Uma vez que o
SPEC.mdseja commitado e válido (>= 300 bytes com todas as 4 seções), o hookspec-gatekeeperpermitirá automaticamente a escrita dos arquivos de código-fonte da implementação.