propor-requisitos-de-funcionalidade

Habilidade: Propor Requisitos de Funcionalidade

Propósito

Criar uma especificação formal de requisitos para uma funcionalidade usando notação EARS. Isso traduz o conceito em requisitos testáveis e específicos.

Quando Usar

• O conceito da funcionalidade existe e foi aprovado
• É necessário especificar exatamente o que o sistema deve fazer
• Pronto para definir requisitos funcionais e não funcionais

Pré-requisitos

• O documento de conceito da funcionalidade existe em docs/features/NNNN-feature-name/concept.md
• O conceito foi revisado e aprovado
• O usuário entende o escopo da funcionalidade

Procedimento

1. Verificar se o Conceito Existe

# Verificar se o conceito existe
ls ./docs/features/NNNN-feature-name/concept.md

Se não existir, use a habilidade propor-conceito-de-funcionalidade primeiro.

2. Verificar Documento de Refinamento de Ideia

ls ./planning/NNNN-feature-name/idea-honing.md 2>/dev/null

Se existir, revise-o para obter insights que informem os requisitos. As perguntas e respostas podem revelar casos extremos e restrições.

3. Copiar o Modelo de Requisitos

cp ./docs/features/0000-templates/requirements.md ./docs/features/NNNN-feature-name/

4. Determinar o Prefixo dos Requisitos

Escolha um prefixo curto (2-5 caracteres) para os IDs dos requisitos:

• Deve ser descritivo da funcionalidade
• Exemplos: SEM para busca-semântica, REG para gerenciamento-de-registro
• Será usado como SEM-1, SEM-2, etc.

5. Preencher a Visão Geral

Escreva uma breve descrição do que esta especificação cobre. Faça referência ao documento de conceito.

6. Definir Requisitos Funcionais

Para cada requisito, use o formato EARS:

**ENQUANTO** [estado ou condição]
**QUANDO** [gatilho ou evento]
**ENTÃO** o sistema **DEVE** [comportamento exigido]

Adicione exemplos inline apenas se forem realmente pequenos (1-3 linhas):

chave = "valor"

Para exemplos maiores, anote-os para os apêndices.

7. Definir Requisitos Não Funcionais

Adicione requisitos de desempenho, usabilidade, segurança ou outras qualidades:

**ENQUANTO** [condição de operação]
**ENTÃO** o sistema **DEVE** [requisito de desempenho]

Perguntas de escalabilidade (faça estas para cada operação principal):

• O que acontece quando há 1000x mais itens? 1M arquivos? 10M linhas?
• O uso de memória deve escalar com o tamanho dos dados, ou permanecer constante?
• Qual é a latência aceitável? Ela degrada com a escala?

Essas perguntas revelam restrições que se tornarão Restrições Críticas na fase de design. Se uma operação deve ser O(1) em memória ou O(log n) em tempo, declare isso aqui.

8. Definir Tratamento de Erros

Especifique como os erros devem ser tratados:

**ENQUANTO** [operação em andamento]
**ONDE** [ocorre a condição de erro]
**ENTÃO** o sistema **DEVE** [comportamento de tratamento de erro]

9. Adicionar Apêndices

Para exemplos maiores que poluiriam os requisitos:

• Esquemas de resposta de API
• Formatos de arquivos de configuração
• Estruturas de dados
• Especificações de protocolo

Cada apêndice deve ser claramente rotulado:

## Apêndice A: Esquema de Resposta da API
## Apêndice B: Formato de Arquivo de Configuração

10. Revisar para Completude

Garanta que:

• Todos os requisitos usam palavras-chave EARS
• Os requisitos são testáveis e específicos
• Exemplos inline são realmente pequenos
• Exemplos maiores estão nos apêndices
• Os requisitos possuem IDs únicos com o prefixo escolhido

Validação

Verifique o documento de requisitos:

# Verificar se o arquivo existe
ls ./docs/features/NNNN-feature-name/requirements.md

# Verificar se tem conteúdo
head -50 ./docs/features/NNNN-feature-name/requirements.md

# Verificar palavras-chave EARS
grep -E "(ENQUANTO|QUANDO|ONDE|ENTÃO|DEVE)" ./docs/features/NNNN-feature-name/requirements.md

Problemas Comuns

Palavras-chave EARS ausentes: Todo requisito deve usar ENQUANTO/QUANDO/ONDE/ENTÃO/DEVE.

Muito vago: Os requisitos devem ser específicos o suficiente para serem testados.

Exemplos inline muito grandes: Mova qualquer coisa com mais de 3 linhas para um apêndice.

Prefixo inconsistente: Todos os IDs de requisitos devem usar o mesmo prefixo.

Próximos Passos

Após criar os requisitos:

1. Revise para completude e testabilidade
2. Obtenha feedback dos implementadores
3. Assim que os requisitos estiverem sólidos, passe para o design usando a habilidade propor-design-de-funcionalidade