Entrada do Usuário
$ARGUMENTS
Você DEVE considerar a entrada do usuário antes de prosseguir (se não estiver vazia).
Verificações Pré-Execução
Verificar hooks de extensão (antes da especificação):
- Verifique se
.specify/extensions.ymlexiste na raiz do projeto. - Se existir, leia-o e procure por entradas sob a chave
hooks.before_specify - Se o YAML não puder ser analisado ou for inválido, não pule silenciosamente: informe ao usuário que
.specify/extensions.ymlnão pôde ser lido (inclua o erro do parser) e que nenhum hook foi verificado, incluindo quaisquer hooks obrigatórios (optional: false) registrados lá, depois continue normalmente - Filtre hooks onde
enabledé explicitamentefalse. Trate hooks sem um campoenabledcomo habilitados por padrão. - Para cada hook restante, não tente interpretar ou avaliar expressões de
conditiondo hook:- Se o hook não tiver um campo
condition, ou ele for nulo/vazio, trate o hook como executável - Se o hook definir uma
conditionnão vazia, pule o hook e deixe a avaliação da condição para a implementação do HookExecutor
- Se o hook não tiver um campo
- Ao construir invocações de comando a partir de nomes de comando do hook, substitua pontos (
.) por hífens (-). Por exemplo,speckit.git.commit→/speckit-git-commit. - Para cada hook executável, produza o seguinte com base em sua flag
optional:- Hook opcional (
optional: true):## Hooks de Extensão **Pré-Hook Opcional**: {extensão} Comando: `/{comando}` Descrição: {descrição} Prompt: {prompt} Para executar: `/{comando}` - Hook obrigatório (
optional: false):
Após emitir o bloco acima, você DEVE realmente invocar o hook e aguardar sua conclusão antes de continuar. Execute-o da mesma forma que você executaria o comando neste agente/sessão (a invocação pode diferir do literal## Hooks de Extensão **Pré-Hook Automático**: {extensão} Executando: `/{comando}` EXECUTE_COMMAND: {comando} Aguarde o resultado do comando do hook antes de prosseguir para o Esboço.{comando}id mostrado acima, por exemplo, um agente no modo skills executa como/skill:speckit-...ou$speckit-...). Apenas emitir o bloco não executa o hook.
- Hook opcional (
- Se nenhum hook estiver registrado ou
.specify/extensions.ymlnão existir, pule silenciosamente
Esboço
O texto que o usuário digitou após /speckit-specify na mensagem de disparo é a descrição da funcionalidade. Presuma que você sempre o tem disponível nesta conversa mesmo que $ARGUMENTS apareça literalmente abaixo. Não peça ao usuário para repeti-lo, a menos que ele tenha fornecido um comando vazio.
Dada essa descrição da funcionalidade, faça o seguinte:
-
Gere um nome curto conciso (2-4 palavras) para a funcionalidade:
- Analise a descrição da funcionalidade e extraia as palavras-chave mais significativas
- Crie um nome curto de 2 a 4 palavras que capture a essência da funcionalidade
- Use o formato ação-substantivo quando possível (ex.: "adicionar-auth-usuario", "corrigir-bug-pagamento")
- Preserve termos técnicos e siglas (OAuth2, API, JWT, etc.)
- Mantenha conciso, mas descritivo o suficiente para entender a funcionalidade rapidamente
- Exemplos:
- "Quero adicionar autenticação de usuário" → "auth-usuario"
- "Implementar integração OAuth2 para a API" → "integracao-oauth2-api"
- "Criar um dashboard para análises" → "dashboard-analises"
- "Corrigir bug de timeout no processamento de pagamento" → "corrigir-timeout-pagamento"
-
Criação de branch (opcional, via hook):
Se um hook
before_specifyfoi executado com sucesso nas Verificações Pré-Execução acima, ele terá criado/alternado para um branch git e produzido JSON contendoBRANCH_NAMEeFEATURE_NUM. Anote esses valores para referência, mas o nome do branch não dita o nome do diretório da especificação.Se o usuário forneceu explicitamente
GIT_BRANCH_NAME, passe-o para o hook para que o script de branch use o valor exato como nome do branch (ignorando toda geração de prefixo/sufixo). -
Crie o diretório da funcionalidade da especificação:
As especificações residem no diretório padrão
specs/, a menos que o usuário forneça explicitamenteSPECIFY_FEATURE_DIRECTORY.Ordem de resolução para
SPECIFY_FEATURE_DIRECTORY:- Se o usuário forneceu explicitamente
SPECIFY_FEATURE_DIRECTORY(por exemplo, via variável de ambiente, argumento ou configuração), use-o como está - Caso contrário, gere-o automaticamente sob
specs/:- Verifique
.specify/init-options.jsonparafeature_numbering(preferido) oubranch_numbering(obsoleto, apenas migração — será removido em uma versão futura) - Se
"timestamp": prefixo éYYYYMMDD-HHMMSS(timestamp atual) - Se
"sequential"ou ausente: prefixo éNNN(próximo número de 3 dígitos disponível após escanear diretórios existentes emspecs/) - Construa o nome do diretório:
<prefixo>-<nome-curto>(ex.:003-auth-usuarioou20260319-143022-auth-usuario) - Defina
SPECIFY_FEATURE_DIRECTORYcomospecs/<nome-do-diretório> - Se
branch_numberingfoi usado (efeature_numberingestava ausente), emita um aviso de uma linha: "⚠️branch_numberingem init-options.json está obsoleto. Renomeie parafeature_numbering."
- Verifique
Crie o diretório e o arquivo de especificação:
mkdir -p SPECIFY_FEATURE_DIRECTORY- Resolva o
spec-templateativo através da pilha de resolução de preset/template do Spec Kit (equivalente aspecify preset resolve spec-template) - Copie o arquivo
spec-templateresolvido paraSPECIFY_FEATURE_DIRECTORY/spec.mdcomo ponto de partida - Defina
SPEC_FILEcomoSPECIFY_FEATURE_DIRECTORY/spec.md - Persista o caminho resolvido em
.specify/feature.json:Escreva o valor real do caminho do diretório resolvido (por exemplo,{ "feature_directory": "<diretório da funcionalidade resolvido>" }specs/003-auth-usuario), não a string literalSPECIFY_FEATURE_DIRECTORY. Isso permite que comandos downstream (/speckit-plan,/speckit-tasks, etc.) localizem o diretório da funcionalidade sem depender de convenções de nome de branch git.
IMPORTANTE:
- Você deve criar apenas uma funcionalidade por invocação de
/speckit-specify - O nome do diretório da especificação e o nome do branch git são independentes — eles podem ser os mesmos, mas isso é uma escolha do usuário
- O diretório e o arquivo de especificação são sempre criados por este comando, nunca pelo hook
- Se o usuário forneceu explicitamente
-
Carregue o arquivo
spec-templateativo resolvido para entender as seções necessárias. -
SE EXISTIR: Carregue
.specify/memory/constitution.mdpara princípios do projeto e restrições de governança. -
Siga este fluxo de execução:
- Analise a descrição do usuário a partir dos argumentos Se vazia: ERRO "Nenhuma descrição de funcionalidade fornecida"
- Extraia conceitos-chave da descrição Identifique: atores, ações, dados, restrições
- Para aspectos pouco claros:
- Faça suposições informadas com base no contexto e padrões da indústria
- Marque apenas com [PRECISA DE ESCLARECIMENTO: pergunta específica] se:
- A escolha impacta significativamente o escopo da funcionalidade ou a experiência do usuário
- Existem múltiplas interpretações razoáveis com implicações diferentes
- Nenhum padrão razoável existe
- LIMITE: Máximo de 3 marcadores [PRECISA DE ESCLARECIMENTO] no total
- Priorize esclarecimentos por impacto: escopo > segurança/privacidade > experiência do usuário > detalhes técnicos
- Preencha a seção Cenários de Usuário e Testes Se nenhum fluxo de usuário claro: ERRO "Não é possível determinar cenários de usuário"
- Gere Requisitos Funcionais Cada requisito deve ser testável Use padrões razoáveis para detalhes não especificados (documente suposições na seção Suposições)
- Defina Critérios de Sucesso Crie resultados mensuráveis e agnósticos em relação à tecnologia Inclua métricas quantitativas (tempo, desempenho, volume) e medidas qualitativas (satisfação do usuário, conclusão de tarefas) Cada critério deve ser verificável sem detalhes de implementação
- Identifique Entidades Chave (se houver dados envolvidos)
- Retorne: SUCESSO (especificação pronta para planejamento)
-
Escreva a especificação em SPEC_FILE usando a estrutura do template, substituindo placeholders por detalhes concretos derivados da descrição da funcionalidade (argumentos), preservando a ordem das seções e cabeçalhos.
-
Validação de Qualidade da Especificação: Após escrever a especificação inicial, valide-a contra critérios de qualidade:
a. Crie a Lista de Verificação de Qualidade da Especificação: Gere um arquivo de lista de verificação em
SPECIFY_FEATURE_DIRECTORY/checklists/requirements.mdusando a estrutura do template de lista de verificação com estes itens de validação:# Lista de Verificação de Qualidade da Especificação: [NOME DA FUNCIONALIDADE] **Propósito**: Validar a completude e qualidade da especificação antes de prosseguir para o planejamento **Criado em**: [DATA] **Funcionalidade**: [Link para spec.md] ## Qualidade do Conteúdo - [ ] Sem detalhes de implementação (linguagens, frameworks, APIs) - [ ] Focado no valor para o usuário e necessidades de negócio - [ ] Escrito para partes interessadas não técnicas - [ ] Todas as seções obrigatórias concluídas ## Completude dos Requisitos - [ ] Nenhum marcador [PRECISA DE ESCLARECIMENTO] permanece - [ ] Requisitos são testáveis e inequívocos - [ ] Critérios de sucesso são mensuráveis - [ ] Critérios de sucesso são agnósticos em relação à tecnologia (sem detalhes de implementação) - [ ] Todos os cenários de aceitação estão definidos - [ ] Casos de borda foram identificados - [ ] Escopo claramente delimitado - [ ] Dependências e suposições identificadas ## Prontidão da Funcionalidade - [ ] Todos os requisitos funcionais têm critérios de aceitação claros - [ ] Cenários de usuário cobrem os fluxos principais - [ ] A funcionalidade atende aos resultados mensuráveis definidos nos Critérios de Sucesso - [ ] Nenhum detalhe de implementação vaza para a especificação ## Notas - Itens marcados como incompletos exigem atualizações na especificação antes de `/speckit-clarify` ou `/speckit-plan`b. Execute a Verificação de Validação: Revise a especificação contra cada item da lista de verificação:
- Para cada item, determine se ele passa ou falha
- Documente problemas específicos encontrados (cite seções relevantes da especificação)
c. Lide com os Resultados da Validação:
-
Se todos os itens passarem: Marque a lista de verificação como concluída e prossiga para a seção Hooks Pós-Execução Obrigatórios
-
Se itens falharem (excluindo [PRECISA DE ESCLARECIMENTO]):
- Liste os itens com falha e problemas específicos
- Atualize a especificação para resolver cada problema
- Reexecute a validação até que todos os itens passem (máximo de 3 iterações)
- Se ainda estiver falhando após 3 iterações, documente os problemas restantes nas notas da lista de verificação e avise o usuário
-
Se marcadores [PRECISA DE ESCLARECIMENTO] permanecerem:
-
Extraia todos os marcadores [PRECISA DE ESCLARECIMENTO: ...] da especificação
-
VERIFICAÇÃO DE LIMITE: Se houver mais de 3 marcadores, mantenha apenas os 3 mais críticos (por impacto de escopo/segurança/UX) e faça suposições informadas para o restante
-
Para cada esclarecimento necessário (máx. 3), apresente opções ao usuário neste formato:
## Pergunta [N]: [Tópico] **Contexto**: [Citação da seção relevante da especificação] **O que precisamos saber**: [Pergunta específica do marcador PRECISA DE ESCLARECIMENTO] **Respostas Sugeridas**: | Opção | Resposta | Implicações | |--------|----------|-------------| | A | [Primeira resposta sugerida] | [O que isso significa para a funcionalidade] | | B | [Segunda resposta sugerida] | [O que isso significa para a funcionalidade] | | C | [Terceira resposta sugerida] | [O que isso significa para a funcionalidade] | | Personalizado | Forneça sua própria resposta | [Explique como fornecer entrada personalizada] | **Sua escolha**: _[Aguardar resposta do usuário]_ -
CRÍTICO - Formatação de Tabela: Garanta que as tabelas markdown estejam formatadas corretamente:
- Use espaçamento consistente com pipes alinhados
- Cada célula deve ter espaços ao redor do conteúdo:
| Conteúdo |não|Conteúdo| - O separador de cabeçalho deve ter pelo menos 3 traços:
|--------| - Teste se a tabela renderiza corretamente na visualização markdown
-
Numere as perguntas sequencialmente (P1, P2, P3 - máx. 3 no total)
-
Apresente todas as perguntas juntas antes de aguardar respostas
-
Aguarde o usuário responder com suas escolhas para todas as perguntas (ex.: "P1: A, P2: Personalizado - [detalhes], P3: B")
-
Atualize a especificação substituindo cada marcador [PRECISA DE ESCLARECIMENTO] pela resposta selecionada ou fornecida pelo usuário
-
Reexecute a validação após todos os esclarecimentos serem resolvidos
-
d. Atualize a Lista de Verificação: Após cada iteração de validação, atualize o arquivo da lista de verificação com o status aprovado/reprovado atual
Hooks Pós-Execução Obrigatórios
Você DEVE concluir esta seção antes de relatar a conclusão ao usuário.
Verifique se .specify/extensions.yml existe na raiz do projeto.
- Se não existir, ou nenhum hook estiver registrado sob
hooks.after_specify, pule para o Relatório de Conclusão. - Se existir, leia-o e procure por entradas sob a chave
hooks.after_specify. - Se o YAML não puder ser analisado ou for inválido, não pule silenciosamente: informe ao usuário que
.specify/extensions.ymlnão pôde ser lido (inclua o erro do parser) e que nenhum hook foi verificado, incluindo quaisquer hooks obrigatórios (optional: false) registrados lá, depois continue para o Relatório de Conclusão. - Filtre hooks onde
enabledé explicitamentefalse. Trate hooks sem um campoenabledcomo habilitados por padrão. - Para cada hook restante, não tente interpretar ou avaliar expressões de
conditiondo hook:- Se o hook não tiver um campo
condition, ou ele for nulo/vazio, trate o hook como executável - Se o hook definir uma
conditionnão vazia, pule o hook e deixe a avaliação da condição para a implementação do HookExecutor
- Se o hook não tiver um campo
- Ao construir invocações de comando a partir de nomes de comando do hook, substitua pontos (
.) por hífens (-). Por exemplo,speckit.git.commit→/speckit-git-commit. - Para cada hook executável, produza o seguinte com base em sua flag
optional:- Hook obrigatório (
optional: false) — Você DEVE emitirEXECUTE_COMMAND:para cada hook obrigatório:
Após emitir o bloco acima, você DEVE realmente invocar o hook e aguardar sua conclusão antes de continuar.## Hooks de Extensão **Hook Automático**: {extensão} Executando: `/{comando}` EXECUTE_COMMAND: {comando} Aguarde o resultado do comando do hook antes de prosseguir para o Relatório de Conclusão. - Hook opcional (
optional: true):## Hooks de Extensão **Hook Opcional**: {extensão} Comando: `/{comando}` Descrição: {descrição} Prompt: {prompt} Para executar: `/{comando}`
- Hook obrigatório (
Relatório de Conclusão
Depois de executar todos os hooks pós-execução, relate ao usuário as seguintes informações:
- Caminho para o arquivo de especificação:
SPEC_FILE - Caminho para o diretório da funcionalidade da especificação:
SPECIFY_FEATURE_DIRECTORY - Resumo das ações executadas (hooks executados, se aplicável)
- Se a validação de qualidade foi bem-sucedida ou se existem problemas não resolvidos (documente na lista de verificação)
- Indicar que a especificação está pronta para planejamento: "Especificação da funcionalidade concluída. Pronto para executar
/speckit-planpara gerar o plano detalhado." - Incluir um resumo da especificação com:
- Nome da funcionalidade
- Número de requisitos funcionais
- Número de cenários de usuário
- Número de entidades identificadas (se houver)
- Quaisquer suposições feitas