spec-gatekeeper

Realiza uma entrevista focada com 4 perguntas ao desenvolvedor e elabora um SPEC.md determinístico (Escopo e Segurança, Contratos de Dados, Casos Extremos, Critérios de Aceitação) antes de escrever o código-fonte.

O que é spec-gatekeeper?

O Spec-Gatekeeper é uma skill para agentes de IA (como Claude Code, Cursor ou Codex) que impõe um fluxo de desenvolvimento orientado por especificações (Spec-Driven Development - SDD). Antes de qualquer código ser escrito, a skill conduz uma breve entrevista de 4 perguntas com o desenvolvedor, cobrindo escopo e segurança, contratos de dados, casos extremos e critérios de aceitação. Com base nas respostas, ela gera automaticamente um arquivo `SPEC.md` de estrutura canônica no repositório, garantindo pelo menos 300 bytes de conteúdo substantivo. Após a aprovação manual do desenvolvedor e a validação do arquivo, o hook `spec-gatekeeper` libera a escrita do código-fonte. Essa abordagem elimina ambiguidades, reduz retrabalho e alinha todos os envolvidos antes da implementação, suportando qualquer plataforma de agente que use arquivos de especificação como gatekeeper.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dansierrasam79/spec-gatekeeper/tree/main/skills/spec-gatekeeper

Installed? Explore more Produtividade e Colaboração skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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):

  1. 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?
  2. 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?
  3. 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?
  4. 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:

  1. Requisito de Tamanho: Pelo menos 300 bytes UTF-8 de conteúdo substantivo.
  2. 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ças ou Permissões.
    • Contratos de Dados: Cabeçalhos contendo Contrato de Dados, Contratos de Dados, Esquema, Esquemas, Interface, Interfaces, API, Tipos, Payload ou Protocolo.
    • Casos Extremos: Cabeçalhos contendo Caso Extremo, Casos Extremos, Tratamento de Erros, Modo de Falha, Resiliência, Restrições ou Fallbacks.
    • 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 Pronto ou Validação.

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

  1. Apresente o rascunho do SPEC.md ao desenvolvedor para revisão e aprovação explícita.
  2. Uma vez que o SPEC.md seja commitado e válido (>= 300 bytes com todas as 4 seções), o hook spec-gatekeeper permitirá automaticamente a escrita dos arquivos de código-fonte da implementação.

Habilidades Relacionadas