Propósito da Checklist: "Testes de Unidade para Inglês"
CONCEITO CRÍTICO: Checklists são TESTES DE UNIDADE PARA ESCRITA DE REQUISITOS – elas validam a qualidade, clareza e completude dos requisitos em um determinado domínio.
NÃO para verificação/teste:
- ❌ NÃO "Verificar se o botão clica corretamente"
- ❌ NÃO "Testar se o tratamento de erros funciona"
- ❌ NÃO "Confirmar se a API retorna 200"
- ❌ NÃO verificar se o código/implementação corresponde à especificação
PARA validação da qualidade dos requisitos:
- ✅ "Existem requisitos de hierarquia visual definidos para todos os tipos de cartão?" (completude)
- ✅ "'Exibição proeminente' é quantificada com posicionamento/tamanho específicos?" (clareza)
- ✅ "Os requisitos de estado de hover são consistentes em todos os elementos interativos?" (consistência)
- ✅ "Existem requisitos de acessibilidade definidos para navegação por teclado?" (cobertura)
- ✅ "A especificação define o que acontece quando a imagem do logotipo falha ao carregar?" (casos de borda)
Metáfora: Se sua especificação é um código escrito em inglês, a checklist é seu conjunto de testes de unidade. Você está testando se os requisitos estão bem escritos, completos, sem ambiguidade e prontos para implementação – NÃO se a implementação funciona.
Propriedade e ciclo de vida da checkbox:
- Checklists personalizadas geradas por este comando são artefatos de revisão de qualidade de requisitos de propriedade do revisor.
[x]significa que o revisor determinou que o critério de qualidade dos requisitos foi satisfeito.[x]NÃO significa que o trabalho de implementação está completo.- Este comando gera ou anexa itens de checklist; ele NÃO DEVE marcar itens gerados como
[x]. - Um agente pode ajudar a avaliar itens somente quando explicitamente solicitado pelo revisor.
checklists/requirements.mdé uma checklist separada de qualidade de especificação embutida, mantida por/speckit-specifye/speckit-clarify; não trate essa exceção como aplicável a checklists personalizadas geradas aqui.
Entrada do Usuário
$ARGUMENTS
Você DEVE considerar a entrada do usuário antes de prosseguir (se não estiver vazia).
Verificações de Pré-execução
Verificar ganchos de extensão (antes da geração da checklist):
- Verifique se
.specify/extensions.ymlexiste na raiz do projeto. - Se existir, leia-o e procure por entradas sob a chave
hooks.before_checklist - 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 analisador) e que nenhum gancho foi verificado, incluindo quaisquer ganchos obrigatórios (optional: false) registrados lá, então continue normalmente - Filtre ganchos onde
enabledé explicitamentefalse. Trate ganchos sem um campoenabledcomo habilitados por padrão. - Para cada gancho restante, não tente interpretar ou avaliar expressões de
conditiondo gancho:- Se o gancho não tiver um campo
condition, ou ele for nulo/vazio, trate o gancho como executável - Se o gancho definir uma
conditionnão vazia, pule o gancho e deixe a avaliação da condição para a implementação do HookExecutor
- Se o gancho não tiver um campo
- Ao construir invocações de comando a partir de nomes de comando de gancho, substitua pontos (
.) por hífens (-). Por exemplo,speckit.git.commit→/speckit-git-commit. - Para cada gancho executável, gere a seguinte saída com base em sua flag
optional:- Gancho opcional (
optional: true):## Ganchos de Extensão **Pré-gancho Opcional**: {extensão} Comando: `/{comando}` Descrição: {descrição} Prompt: {prompt} Para executar: `/{comando}` - Gancho obrigatório (
optional: false):
Após emitir o bloco acima, você DEVE realmente invocar o gancho e aguardar sua conclusão antes de continuar. Execute-o da mesma forma que você executaria o comando por conta própria neste agente/sessão (a invocação pode diferir do ID## Ganchos de Extensão **Pré-gancho Automático**: {extensão} Executando: `/{comando}` EXECUTAR_COMANDO: {comando} Aguarde o resultado do comando do gancho antes de prosseguir para as Etapas de Execução.{comando}literal mostrado acima, por exemplo, um agente em modo skills o executa como/skill:speckit-...ou$speckit-...). Apenas emitir o bloco não executa o gancho.
- Gancho opcional (
- Se nenhum gancho estiver registrado ou
.specify/extensions.ymlnão existir, pule silenciosamente
Etapas de Execução
-
Configuração: Execute
.specify/scripts/bash/check-prerequisites.sh --json --template checklist-templateda raiz do repositório e analise o JSON para FEATURE_DIR, lista AVAILABLE_DOCS e TEMPLATE_CONTENT.- Todos os caminhos de arquivo devem ser absolutos.
- Para aspas simples em argumentos como "I'm Groot", use sintaxe de escape: por exemplo, 'I'''m Groot' (ou aspas duplas, se possível: "I'm Groot").
-
SE EXISTIR: Carregue
.specify/memory/constitution.mdpara princípios do projeto e restrições de governança. -
Esclarecer intenção (dinâmico): Derive até TRÊS perguntas contextuais iniciais de esclarecimento (nenhum catálogo pré-definido). Elas DEVEM:
- Ser geradas a partir da frase do usuário + sinais extraídos da especificação/plano/tarefas
- Perguntar apenas sobre informações que alterem materialmente o conteúdo da checklist
- Ser ignoradas individualmente se já estiverem inequívocas em
$ARGUMENTS - Preferir precisão em vez de amplitude
Algoritmo de geração:
- Extraia sinais: palavras-chave de domínio do recurso (por exemplo, auth, latência, UX, API), indicadores de risco ("crítico", "deve", "conformidade"), dicas de partes interessadas ("QA", "revisão", "equipe de segurança") e entregáveis explícitos ("a11y", "rollback", "contratos").
- Agrupe sinais em áreas de foco candidatas (máx. 4) classificadas por relevância.
- Identifique o público provável e o momento (autor, revisor, QA, lançamento) se não estiver explícito.
- Detecte dimensões ausentes: amplitude de escopo, profundidade/rigor, ênfase em risco, limites de exclusão, critérios de aceitação mensuráveis.
- Formule perguntas escolhidas a partir destes arquétipos:
- Refinamento de escopo (por exemplo, "Isso deve incluir pontos de contato de integração com X e Y ou permanecer limitado à correção do módulo local?")
- Priorização de risco (por exemplo, "Quais dessas áreas de risco potenciais devem receber verificações de bloqueio obrigatórias?")
- Calibração de profundidade (por exemplo, "Esta é uma lista de verificação de sanidade leve pré-commit ou uma porta de lançamento formal?")
- Enquadramento de público (por exemplo, "Isso será usado apenas pelo autor ou por pares durante a revisão de PR?")
- Exclusão de limite (por exemplo, "Devemos excluir explicitamente itens de ajuste de desempenho desta vez?")
- Lacuna de classe de cenário (por exemplo, "Nenhum fluxo de recuperação detectado – caminhos de rollback/falha parcial estão no escopo?")
Regras de formatação de perguntas:
- Se apresentar opções, gere uma tabela compacta com colunas: Opção | Candidato | Por Que É Importante
- Limite a no máximo A–E opções; omita a tabela se uma resposta em forma livre for mais clara
- Nunca peça ao usuário para repetir o que já disse
- Evite categorias especulativas (sem alucinação). Se estiver incerto, pergunte explicitamente: "Confirme se X pertence ao escopo."
Padrões quando a interação for impossível:
- Profundidade: Padrão
- Público: Revisor (PR) se relacionado a código; Autor caso contrário
- Foco: Top 2 clusters de relevância
Gere as perguntas (rotuladas P1/P2/P3). Após as respostas: se ≥2 classes de cenário (Alternativo / Exceção / Recuperação / Domínio Não Funcional) permanecerem pouco claras, você PODE fazer até DOIS acompanhamentos direcionados adicionais (P4/P5) com uma justificativa de uma linha cada (por exemplo, "Risco de caminho de recuperação não resolvido"). Não exceda cinco perguntas no total. Pule a escalada se o usuário recusar explicitamente mais.
-
Entender solicitação do usuário: Combine
$ARGUMENTS+ respostas de esclarecimento:- Derive o tema da checklist (por exemplo, segurança, revisão, implantação, ux)
- Consolide itens obrigatórios explícitos mencionados pelo usuário
- Mapeie seleções de foco para estruturação de categoria
- Infira qualquer contexto ausente da especificação/plano/tarefas (NÃO alucine)
-
Carregar contexto do recurso: Leia de FEATURE_DIR:
- spec.md: Requisitos e escopo do recurso
- plan.md (se existir): Detalhes técnicos, dependências
- tasks.md (se existir): Tarefas de implementação
Estratégia de Carregamento de Contexto:
- Carregue apenas as porções necessárias relevantes para as áreas de foco ativas (evite despejar o arquivo inteiro)
- Prefira resumir seções longas em marcadores concisos de cenário/requisito
- Use divulgação progressiva: adicione recuperação de acompanhamento somente se lacunas forem detectadas
- Se os documentos de origem forem grandes, gere itens de resumo provisórios em vez de incorporar texto bruto
-
Gerar checklist - Use TEMPLATE_CONTENT como modelo estrutural e crie "Testes de Unidade para Requisitos":
- Crie o diretório
FEATURE_DIR/checklists/se ele não existir - Gere um nome de arquivo de checklist único:
- Use nome curto e descritivo baseado no domínio (por exemplo,
ux.md,api.md,security.md) - Formato:
[domínio].md
- Use nome curto e descritivo baseado no domínio (por exemplo,
- Comportamento de manipulação de arquivo:
- Se o arquivo NÃO existir: Crie um novo arquivo e numere itens começando de CHK001
- Se o arquivo existir: Anexe novos itens ao arquivo existente, continuando do último ID CHK (por exemplo, se o último item for CHK015, inicie novos itens em CHK016)
- Nunca exclua ou substitua o conteúdo existente da checklist – sempre preserve e anexe
- Deixe cada item recém-gerado desmarcado (
[ ]); o estado da checkbox pertence ao revisor
PRINCÍPIO CENTRAL – Teste os Requisitos, Não a Implementação: Cada item da checklist DEVE avaliar OS PRÓPRIOS REQUISITOS quanto a:
- Completude: Todos os requisitos necessários estão presentes?
- Clareza: Os requisitos são inequívocos e específicos?
- Consistência: Os requisitos estão alinhados entre si?
- Mensurabilidade: Os requisitos podem ser verificados objetivamente?
- Cobertura: Todos os cenários/casos de borda são abordados?
Estrutura de Categoria – Agrupe itens por dimensões de qualidade dos requisitos:
- Completude dos Requisitos (Todos os requisitos necessários estão documentados?)
- Clareza dos Requisitos (Os requisitos são específicos e inequívocos?)
- Consistência dos Requisitos (Os requisitos estão alinhados sem conflitos?)
- Qualidade dos Critérios de Aceitação (Os critérios de sucesso são mensuráveis?)
- Cobertura de Cenários (Todos os fluxos/casos são abordados?)
- Cobertura de Casos de Borda (As condições de contorno estão definidas?)
- Requisitos Não Funcionais (Desempenho, Segurança, Acessibilidade, etc. – estão especificados?)
- Dependências e Suposições (Estão documentadas e validadas?)
- Ambiguidades e Conflitos (O que precisa de esclarecimento?)
COMO ESCREVER ITENS DE CHECKLIST – "Testes de Unidade para Inglês":
❌ ERRADO (Testando implementação):
- "Verificar se a página inicial exibe 3 cartões de episódio"
- "Testar se os estados de hover funcionam no desktop"
- "Confirmar se o clique no logotipo navega para o início"
✅ CORRETO (Testando qualidade dos requisitos):
- "O número exato e o layout dos episódios em destaque estão especificados?" [Completude]
- "'Exibição proeminente' é quantificada com posicionamento/tamanho específicos?" [Clareza]
- "Os requisitos de estado de hover são consistentes em todos os elementos interativos?" [Consistência]
- "Existem requisitos de navegação por teclado definidos para toda a UI interativa?" [Cobertura]
- "O comportamento de fallback está especificado quando a imagem do logotipo falha ao carregar?" [Casos de Borda]
- "Os estados de carregamento estão definidos para dados assíncronos de episódio?" [Completude]
- "A especificação define hierarquia visual para elementos de UI concorrentes?" [Clareza]
ESTRUTURA DO ITEM: Cada item deve seguir este padrão:
- Formato de pergunta sobre a qualidade do requisito
- Foco no que está ESCRITO (ou não escrito) na especificação/plano
- Inclua a dimensão de qualidade entre colchetes [Completude/Clareza/Consistência/etc.]
- Referencie a seção da especificação
[Spec §X.Y]ao verificar requisitos existentes - Use o marcador
[Gap]ao verificar requisitos ausentes
EXEMPLOS POR DIMENSÃO DE QUALIDADE:
Completude:
- "Existem requisitos de tratamento de erros definidos para todos os modos de falha da API? [Gap]"
- "Existem requisitos de acessibilidade especificados para todos os elementos interativos? [Completude]"
- "Existem requisitos de ponto de interrupção móvel definidos para layouts responsivos? [Gap]"
Clareza:
- "'Carregamento rápido' é quantificado com limites de tempo específicos? [Clareza, Spec §NFR-2]"
- "Os critérios de seleção de 'episódios relacionados' são explicitamente definidos? [Clareza, Spec §FR-5]"
- "'Proeminente' é definido com propriedades visuais mensuráveis? [Ambiguidade, Spec §FR-4]"
Consistência:
- "Os requisitos de navegação estão alinhados em todas as páginas? [Consistência, Spec §FR-10]"
- "Os requisitos do componente de cartão são consistentes entre as páginas inicial e de detalhes? [Consistência]"
Cobertura:
- "Existem requisitos definidos para cenários de estado zero (sem episódios)? [Cobertura, Caso de Borda]"
- "Os cenários de interação simultânea do usuário são abordados? [Cobertura, Gap]"
- "Existem requisitos especificados para falhas de carregamento de dados parciais? [Cobertura, Fluxo de Exceção]"
Mensurabilidade:
- "Os requisitos de hierarquia visual são mensuráveis/testáveis? [Critérios de Aceitação, Spec §FR-1]"
- "'Peso visual equilibrado' pode ser verificado objetivamente? [Mensurabilidade, Spec §FR-2]"
Classificação e Cobertura de Cenários (Foco na Qualidade dos Requisitos):
- Verifique se existem requisitos para: Cenários Primário, Alternativo, Exceção/Erro, Recuperação, Não Funcionais
- Para cada classe de cenário, pergunte: "Os requisitos de [tipo de cenário] são completos, claros e consistentes?"
- Se a classe de cenário estiver faltando: "Os requisitos de [tipo de cenário] foram intencionalmente excluídos ou estão ausentes? [Gap]"
- Inclua resiliência/rollback quando ocorrer mutação de estado: "Existem requisitos de rollback definidos para falhas de migração? [Gap]"
Requisitos de Rastreabilidade:
- MÍNIMO: ≥80% dos itens DEVEM incluir pelo menos uma referência de rastreabilidade
- Cada item deve referenciar: seção da especificação
[Spec §X.Y], ou usar marcadores:[Gap],[Ambiguidade],[Conflito],[Suposição] - Se nenhum sistema de ID existir: "Um esquema de ID de requisito e critério de aceitação está estabelecido? [Rastreabilidade]"
Superficializar e Resolver Problemas (Problemas de Qualidade dos Requisitos): Faça perguntas sobre os próprios requisitos:
- Ambiguidades: "O termo 'rápido' é quantificado com métricas específicas? [Ambiguidade, Spec §NFR-1]"
- Conflitos: "Os requisitos de navegação entram em conflito entre §FR-10 e §FR-10a? [Conflito]"
- Suposições: "A suposição de 'API de podcast sempre disponível' é validada? [Suposição]"
- Dependências:
- Crie o diretório