Definir requisitos verificáveis para uma aplicação de linha de comando

A aplicação será útil para uma pessoa que trabalha no terminal e mantém um catálogo local em JSON. Ela precisa localizar um registro pelo identificador e corrigir seu nome quando encontrar uma informação desatualizada ou digitada incorretamente.

Essa é a necessidade do usuário: consultar e corrigir dados existentes. Ela não diz ainda como o programa será organizado internamente.

Para a primeira entrega, o catálogo já existe. O produto terá duas capacidades: consultar um registro por identificador e atualizar o nome de um registro identificado.

Delimitar o escopo não reduz a utilidade: garante que o fluxo principal possa ser entregue e verificado por completo.

A imagem mostra a fronteira proposta para o produto.

Registre explicitamente as exclusões da primeira entrega:

• criar registros;
• remover registros;
• oferecer interface gráfica;
• sincronizar dados pela rede;
• permitir que vários processos usem o mesmo catálogo ao mesmo tempo.

Uma exclusão não é uma falha escondida: é uma capacidade que não faz parte deste compromisso.

Um caso de uso descreve uma intenção observável da pessoa usuária — não uma função, classe ou sequência interna do programa.

Para o catálogo local, a primeira entrega tem duas intenções:

• Consultar um registro pelo seu identificador.
• Atualizar o nome de um registro pelo seu identificador.

Evite especificar agora frases como “chamar buscar_por_id” ou “percorrer a lista”. Elas escolhem uma implementação antes de definir o contrato do produto.

Use um vocabulário pequeno e consistente:

• Catálogo local: arquivo JSON que a pessoa escolhe para operar.
• Registro: item do catálogo com identificador único e nome não vazio.
• Identificador: valor que aponta para um único registro.
• Novo nome: informação fornecida somente na atualização.

Assim, a consulta precisa do catálogo local e do identificador. A atualização precisa desses dois dados mais o novo nome.

Compare as informações fornecidas em cada caso de uso.

Uma especificação fica mais clara quando não mistura estas categorias:

• Precondição: situação que precisa existir para iniciar o cenário. Ex.: há um catálogo local disponível para ser escolhido.
• Entrada: informação fornecida para aquela operação. Ex.: identificador e, na atualização, novo nome.
• Regra de validade: condição que uma informação deve atender. Ex.: cada identificador é único e o nome não pode ser vazio.

A precondição descreve o contexto; a entrada vem da interação; a regra limita valores aceitáveis. Ainda não estamos definindo resultados, mensagens ou alterações no arquivo.

Um requisito funcional descreve um comportamento observável sob condições definidas. Ele não diz como o código deve ser organizado nem como o JSON deve ser formatado.

Para este catálogo, o requisito precisa deixar claro: em que condição a operação ocorre, o que a pessoa vê e qual efeito acontece nos dados — ou que os dados não mudam.

Use esta sequência para revisar cada requisito: condição → resultado apresentado → efeito no catálogo.

A confirmação de atualização não basta por si só. O novo nome precisa aparecer em uma consulta feita em outra execução da aplicação.

O contrato deve cobrir situações previsíveis sem supor detalhes de mensagens ou códigos de saída:

• Se o identificador não existir, a aplicação deve informar que não encontrou o registro e não alterar o catálogo.
• Se o novo nome for vazio, a aplicação deve informar a entrada inválida e não alterar o catálogo.
• Se o catálogo não puder ser lido ou contiver JSON inválido, a aplicação deve informar a falha e não sobrescrever o arquivo.

Assim, uma tentativa sem condições válidas nunca destrói nem modifica dados existentes.

Um requisito expressa um compromisso: “A aplicação deve atualizar o nome de um registro existente.”

Um critério de aceitação torna esse compromisso verificável: define um catálogo inicial completo, a ação do usuário e o que deve ser observado depois. Assim, duas pessoas conseguem chegar à mesma decisão sobre a entrega, sem depender de como o código foi organizado.

Use Dado / Quando / Então para separar estado inicial, ação e resultados observáveis.

Além do sucesso, cubra situações que impedem a atualização:

• Identificador inexistente: informar a ausência e preservar todo o catálogo.
• Nome inválido, como vazio: informar a invalidez e preservar todo o catálogo.

Esses cenários verificam duas coisas: a resposta ao usuário e a ausência de efeito nos dados. Não repita cenários que provam exatamente a mesma regra com valores diferentes sem acrescentar uma condição relevante.

Além de definir o que os comandos fazem, especifique em quais condições eles precisam funcionar. Compatibilidade, capacidade e tempo de resposta são requisitos não funcionais quando incluem uma condição observável e um limite para aprovação.

Evite promessas como “funciona em qualquer computador”, “aceita catálogo grande” ou “é rápido”. Elas não permitem decidir se a entrega foi aprovada.

Compatibilidade não é suporte universal. Declare versões e plataformas, por exemplo: “A aplicação deve executar em Python 3.11 e 3.12 no Windows 11 e no Ubuntu 22.04 LTS.”

Para capacidade, descreva a carga: quantidade de registros, tamanho máximo de cada nome e tamanho do arquivo JSON. Também separe duas fronteiras:

• Faixa suportada: a aplicação deve operar normalmente dentro dela.
• Limite de rejeição: acima dele, deve recusar o catálogo com mensagem clara, sem alterá-lo.

Um limite de tempo só é verificável se disser qual operação, qual carga, em qual ambiente e o que a medição inclui.

Para este catálogo, a fronteira pode ser a execução completa do comando: começa ao iniciá-lo e termina quando ele finaliza, incluindo leitura do JSON, processamento, escrita quando houver atualização e encerramento. Registre processador, memória e tipo de armazenamento; SSD e disco rígido podem produzir resultados diferentes.

Defina também repetições, estatística e limite. Exemplo: usar a mediana de 10 execuções, não apenas uma tentativa favorável.

Um requisito só está pronto para ser aceito quando você sabe como verificá-lo. Registre quatro ligações: requisito → comando planejado → critério → evidência.

Os comandos ainda são apenas uma interface planejada, por exemplo catalogo consultar --arquivo catalogo.json --id 7 e catalogo atualizar --arquivo catalogo.json --id 7 --nome "Caderno". Não é necessário decidir agora como o parser será implementado.

A evidência deve testar o compromisso declarado, não apenas uma parte interna do programa.

Escrever “medir o tempo em cinco execuções” é um plano de verificação. Só será evidência de aceitação quando houver medições registradas nas condições declaradas. Do mesmo modo, uma matriz revela lacunas: se um requisito não tem evidência adequada, ainda não é possível decidir objetivamente se a entrega o cumpre.

A primeira entrega deve atender à necessidade central: uma pessoa usa o terminal para localizar um registro do catálogo e, quando necessário, corrigir seu nome de forma durável.

Priorize cada compromisso por երեք perguntas:

1. É necessário para o usuário concluir esse fluxo?
2. Depende de outro comportamento já incluído?
3. Pode ser verificado por um critério e uma evidência definidos?

Neste catálogo, consulta e atualização persistente formam um conjunto: atualizar sem poder consultar o resultado depois não fecha o fluxo de uso.

A entrega mínima fecha o caminho principal antes de acrescentar extensões.

Uma miniespecificação útil descreve o que será entregue e como será verificado, não como o código será organizado.

Para este produto, o contrato reúne:

• Público e contexto: pessoa que usa o terminal para consultar e corrigir um catálogo JSON local.
• Escopo: consultar um registro por identificador e atualizar seu nome.
• Exclusões: criar ou remover registros, interface gráfica, rede e uso simultâneo por vários processos.
• Dados: cada registro tem identificador único e nome não vazio.
• Resultados: consulta apresenta o registro sem alterar o arquivo; atualização confirma a alteração e a mantém em uma nova execução.
• Falhas previstas: identificador inexistente, nome inválido, arquivo ilegível ou JSON inválido são informados sem sobrescrever o catálogo.

A especificação conecta intenção, comportamento observável e evidência.

Revise este rascunho problemático:

“O programa deve gerenciar bem um catálogo grande. O usuário consulta itens e edita nomes rapidamente. A edição deve salvar. O programa funciona nos sistemas comuns.”

Compare-o com o contrato consolidado. Procure termos vagos, comportamentos ausentes, possíveis contradições entre consulta e atualização e promessas sem uma evidência definida.