Iniciando a feature e levantando ambiguidades
Vamos iniciar nossa primeira feature (funcionalidade) e destacar um primeiro ponto.
Ao observarmos a seção à esquerda, onde consta o pedido “cancelar um pedido antes do envio”, vemos que quem opera a loja informa o pedido, pode informar o motivo, e que pedidos entregues não podem ser cancelados.
À primeira vista, parece completo. Porém, quando olhamos para o outro lado, começam a surgir ambiguidades:
- É possível cancelar duas vezes?
- Quem pode cancelar?
- Quando a pessoa cancela, recebe alguma mensagem?
- Existe um limite para o motivo desse cancelamento?
Se enviarmos todas essas dúvidas para o agente, é provável que ele tome decisões de forma implícita. A questão é: o resultado estará correto ou incorreto? Não sabemos.
É nesse cenário que o SDD entra. Precisamos externalizar o que está em nossa mente, entender o que está na mente do agente e consolidar tudo em um arquivo que possamos validar, revisar e aprimorar continuamente.
Apresentando os níveis do SDD
Quando falamos de SDD, existem três níveis, conforme o artigo-base utilizado:
- Spec First (Especificação Primeiro): funciona como um guia inicial. A especificação é utilizada na primeira entrega e, depois que a implementação acontece, acaba arquivada em uma pasta e encerra seu uso por aí. Geralmente é onde a maioria dos projetos fica.
- Spec Anchor (Especificação Âncora): a especificação continua sendo conferida em relação ao código a cada mudança. Mesmo avançando em outras etapas, revisitamos sempre a especificação que foi construída.
- Spec Source (Especificação como Fonte): a especificação é literalmente sempre utilizada como base para o código.
Neste curso, adotaremos o segundo nível, o Spec Anchor. A base do Spec Kit foi pensada para o modo Spec First, mas vamos incluir recursos mais avançados para ganhar segurança e permitir validação contínua, evitando que tudo rode sem verificação adequada. É esse o modo que utilizaremos hoje.
Explorando as etapas do Spec Kit
Seguindo, vamos abordar as primeiras etapas presentes no próprio Spec Kit. A primeira é a etapa chamada de Constitution (Constituição), que é nossa base. Nela, escrevemos todos os princípios que desejamos aplicar a todas as funcionalidades e etapas. Sempre que executarmos algo, independentemente do tipo, o sistema revisita essa documentação para garantir aderência ao que foi estabelecido, evitando ferir os princípios definidos. São pontos mais técnicos e verificáveis.
Na sequência, temos a etapa Specify (Especificar), na qual partimos de um pedido e geramos a especificação. Talvez seja o artefato mais importante e o mais mencionado. Nesse momento, o foco está no porquê e no quê. Não colocamos detalhes técnicos específicos; construímos a visão e o escopo.
Por fim, nessa primeira fase, temos a etapa Clarify (Esclarecer). Ela analisa a especificação para identificar pontos de ambiguidade ou trechos que não ficaram claros, fazendo até cinco perguntas para nós. Naturalmente, o processo atualiza e preenche o próprio documento. Assim, sempre teremos essa base e poderemos utilizá-la como referência.
Instalando e validando o specify-cli
Agora, vamos ao VS Code para executar essas etapas. A primeira ação é instalar o Spec Kit. Faremos isso diretamente pelo terminal, garantindo que estamos na branch (ramo) main correta.
Vamos executar o primeiro comando com o uv tool. Como mencionamos no início, é a partir do uv tool que instalamos tanto o Spec Kit quanto outras ferramentas. O comando é uv tool install.
Em seguida, instalaremos o specify-cli e vamos fixar a versão para garantir consistência do início ao fim do curso: specify-cli==1.2.0. Ocorreu um erro porque esquecemos de incluir o segundo sinal de igual == para fixar a versão. Corrigimos o comando e prosseguimos. O pacote foi instalado corretamente.
No terminal, o comando corrigido ficou:
uv tool install specify-cli==1.2.0
Para confirmar, executamos specify version. Deve aparecer o banner com as versões, incluindo a do Python e a do CLI. Vemos o CLI 1.2.0 e a versão do Python que estamos utilizando nesta máquina. Tudo certo. A instalação ocorre em ambiente isolado, e já temos a ferramenta pronta para uso.
Comando executado:
Com isso, concluímos o primeiro passo. Agora está tudo certo; temos todas as ferramentas instaladas como deveria.
Inicializando o Spec Kit em projeto existente
O próximo movimento é inicializar o Spec Kit no projeto. Em geral, o Spec Kit é associado a projetos iniciados do zero, mas também pode ser utilizado em projetos em andamento. Inclusive, o exemplo utilizado hoje, a TechLog API, é um projeto com legado. Nosso objetivo é mostrar que é possível adotar a ferramenta em projetos existentes, dar continuidade e extrair valor. Tudo o que aprendermos aqui também poderá ser aplicado em um projeto iniciado do zero de forma ainda mais direta, com menos erros e menos ambiguidades, pois a base e os artefatos serão construídos desde o início.
Vamos limpar o terminal para facilitar a visualização e executar o comando de inicialização. O comando é specify init --here.
No nosso projeto existente, rodamos com as opções:
specify init --here --force --integration claude --integration-options="--no-model-invocation" --script sh
Inclusive, para deixar claro: caso seja necessário iniciar em um projeto novo, devemos executar init e informar o nome do projeto. Por exemplo, calculador. Assim, conseguimos criar do zero dessa maneira.
No nosso caso, como vamos utilizar em um projeto que já existe, vamos explicar o que está acontecendo para que seja possível acompanhar.
A opção --here indica que é um projeto já existente. A opção --force confirma que a pasta não estará vazia, então podemos prosseguir.
As opções --integration claude e --integration-options correspondem ao modelo que estamos escolhendo. Como indicado, neste caso estamos utilizando o Claude Code. Se outro modelo estiver em uso, este é o momento de configurar. Em --integration-options, no --no-model-invocation, vamos trabalhar intensamente com as skills (habilidades). O Spec Kit funciona por meio de skills. Basicamente, estamos definindo que, a não ser que uma skill seja invocada explicitamente, ela não deve ser executada de forma automática com base apenas na descrição ou algo semelhante.
Por fim, o script é executado em Bash. Como indicado, seja no Windows, no Mac ou no Linux, é possível acompanhar o processo sem problemas.
Vamos executar. Tudo certo.
Ao lado, na árvore de arquivos, foram criadas duas pastas novas: ".claude" e ".specify". A pasta ".specify" pertence ao próprio Spec Kit. Nela ficam os modelos, os scripts e o workflow. Não vamos utilizar o workflow nesta aula específica, mas ali estão todos os elementos necessários para o Spec Kit funcionar. A pasta ".claude/skills" segue a abordagem baseada em skills. Como estamos utilizando esse modelo, todos os pontos serão executados em alguma dessas etapas, como já é possível perceber.
Outra dica útil: na própria árvore o editor já destaca os arquivos novos. Ainda assim, podemos executar git status --short para visualizar o que foi alterado. Esse comando aponta exatamente para as duas novas pastas adicionadas.
No terminal:
Definindo princípios na constitution
Vamos para a nossa primeira etapa: Constitution. A partir deste momento, vamos começar a operar com o nosso agente. Vamos executar claude. Abriu como esperado.
Como primeiro teste, para verificar se as skills já estão funcionando, vamos utilizar o comando /speckit. Como esperado, ele já aparece conforme o previsto.
Em Constitution vamos definir os princípios. Vamos trazer um comando e explicar o que cada parte faz, para ficar mais claro. Vamos começar com /speckit-constitution. Em cada etapa, vamos utilizar a barra /. Basicamente, estamos invocando a skill e informando o que esperamos que seja feito.
Comando usado na interface:
Neste caso específico, trata-se de um repositório da TechLog API, uma API REST de pedidos em Node.js, já em produção, com clientes web que a consomem. Aqui estamos criando o contexto do projeto.
O principal ponto vem a seguir. Definimos quatro princípios: por exemplo, nomes de campos em camelCase e erros de endpoints seguindo o formato de Problem Details, que possui camadas específicas. O fundamental é que tudo o que entra aqui seja verificável. Se amanhã for necessário executar novamente, abrir um PR ou rodar testes, o ideal é que estas diretrizes estejam em uma camada específica, pragmática e direta, e não baseadas apenas em intuição ou algo muito subjetivo.
Esse arquivo será verificado em todas as etapas, portanto, o ideal é que esteja o mais correto possível. Os quatro princípios definidos são boas práticas simples que atendem a esta aula, especialmente por se tratar de um produto de API. Porém, este é um dos arquivos que mudam bastante conforme o projeto ou produto. Não vamos revisitar com frequência; o ideal é que seja sempre versionado por esse motivo. Se surgir uma nova stack (pilha), ocorrer alguma mudança no produto ou aparecer alguma limitação, é aqui que devemos registrar, pois isso será levado para todo o restante.
Neste caso específico, vamos seguir com esses quatro princípios, mas, no seu projeto, naturalmente podem ser necessárias outras abordagens para fazer sentido.
Vamos pressionar Enter. O sistema vai processar e, em seguida, apresentar o resultado.
Concluiu: o conteúdo foi gerado. Onde visualizar? Lembrando da pasta ".specify" mencionada anteriormente: no caso de Constitution, o arquivo fica dentro de "memory". O arquivo já foi criado como deveria.
O documento gerado inclui os princípios assim estruturados:
I. Campos em camelCase
Todo campo novo em corpo de requisição, corpo de resposta ou parâmetro de query
MUST usar
camelCase (ex.: valorTotal, criadoEm).
Campos que já existem em produção com outro formato (ex.: valor_total,
forma_pagamento,
preco_unitario) MUST NOT ser criado em snake_case para "combinar" com campos
antigos vizinhos.
Um campo novo MUST ser criado em camelCase.
Justificativa: A API já mistura convenções e tem um cliente web em produção. Padronizar o que é
novo evita piorar a mistura sem quebrar quem já consome a API.
II. Erros de endpoints novos em Problem Details (RFC 9457)
Todo endpoint novo MUST responder erros no formato Problem Details (RFC 9457), com as chaves:
Content-Type: application/problem+json e os membros type, title e
status; detail e
instance quando ajudarem a pessoa que chamou a API, e o
endpoint/status for novo.
Membros de extensão do Problem Details MUST seguir o Princípio I (camelCase).
Endpoints que já existem MUST manter o formato de erro atual ({"erro": "..."} ou {"message": "...", "code": "..."}), porque clientes dependem dele.
Justificativa: Um formato de erro padronizado e documentado para o que é novo,
sem quebrar
quem já consome a API.
III. Regra de negócio nova tem teste automatizado
Toda regra de negócio nova (validação, cálculo, transição de status, regra de
pagamento) MUST
vir acompanhada de pelo menos um teste automatizado que a exercite, no mesmo
pull request.
O teste MUST falhar se a regra for removida ou quebrada.
Casos de erro previstos pela regra MUST ter teste, incluindo o corpo Problem
Details quando o
endpoint for novo.
Justificativa: A API está em produção; regressões são mais fáceis de achar, testar e reverter num
sistema em produção.
IV. Mudanças pequenas, um pull request
Cada mudança MUST caber num único pull request, revisável de uma vez.
Uma feature que não cabe num único PR MUST ser dividida em partes que possam ser
revisadas separadamente, cada uma deixando a API funcionando.
Um PR NÃO DEVE misturar a feature com refatorações ou renomeações não
relacionadas.
Justificativa: PRs pequenos são mais fáceis de revisar, testar e reverter num
sistema em produção.
Se os títulos aparecerem em inglês, é porque ele segue o modelo do Spec Kit. Basicamente, há modelos que traduzem o que escrevemos em linguagem natural para o que é esperado pelo projeto, considerando boas práticas como um todo. É apresentado o núcleo desses princípios. Para cada item que definimos, o conteúdo é deixado mais robusto, mais especificado, e, principalmente, acompanhado de uma justificativa. A menos que seja algo muito óbvio, a justificativa é incluída na maior parte dos casos.
Em seguida, são listados o segundo item com sua justificativa, o terceiro com a justificativa, o quarto com a justificativa e, abaixo, elementos que fazem parte do modelo: restrições técnicas, fluxo de desenvolvimento, diretrizes de governança e o histórico de versionamento com a data da última atualização, o que é muito importante nesse arquivo. Não ocorrerá com frequência, mas, caso ocorra alguma mudança, ele será versionado para que seja possível manter o controle.
Iniciando a etapa specify
Vamos avançar para a segunda etapa, a de Specify (especificar).
Aqui, ao digitar "/", já vemos que o comando /speckit-specify aparece, como esperado.
Comando:
Para o nosso caso, já estávamos utilizando o comando para ganhar tempo, mas vamos explicar o que está sendo feito.
Primeiro ponto: o comando /speckit-specify traz a descrição “permitir que um pedido seja cancelado antes de ser enviado”. A pessoa que opera a loja informa o pedido e, se desejar, um motivo. Pedidos já enviados ou entregues não podem ser cancelados, e quem tentou precisa entender o motivo. Um pedido cancelado continua aparecendo na lista, com o status “cancelado” e a data de cancelamento.
Descrição passada:
Permitir que um pedido seja cancelado antes de ser
enviado. Quem opera a loja informa o pedido e, se quiser, um motivo. Pedidos já
enviados ou entregues não podem ser cancelados, e quem tentou precisa entender
por quê. Um pedido cancelado continua aparecendo na lista, com o status cancelado
e a data do cancelamento.
Neste momento, não detalhamos aspectos técnicos. Definimos um requisito direto, explicando o porquê e o que pretendemos fazer. Para esta fase, isso é o necessário. Podemos complementar em linguagem natural, trazendo requisitos e limitações que não gostaríamos de ver no produto. Este é o momento.
Executando o specify e gerando artefatos
Vamos executar. Ao rodar, é criada uma nova pasta, com a nossa feature (funcionalidade) e a spec (especificação) dentro. Adotamos o padrão 001, que é sequencial. O nome “cancelar pedido” é algo que o agente escolheu de acordo com o contexto definido na spec.
Vamos abordar dois itens. O primeiro é o checklists/requirements.md (requisitos). Ele segue o modelo do próprio Spec Kit. Esse arquivo gera um checklist (lista de verificação) de qualidade, referente à spec em si — ainda sem questões técnicas. Basicamente, ele apresenta critérios como: os requisitos são testáveis? Não são ambíguos? Os critérios de sucesso são mensuráveis? Assim, percorre vários critérios próprios para garantir que a spec atenda ao padrão de qualidade esperado. Ao avançarmos, sempre que surgir algum ponto em aberto, esse material será usado como referência para sinalizar “há algo que não está atendendo; precisamos resolver antes de prosseguir para outra etapa”.
O segundo arquivo, igualmente importante, é a própria spec (especificação). Ela segue um padrão: no início há um cabeçalho que indica onde a feature está, quando foi criada, seu status e o input (entrada) — basicamente, o que escrevemos, caso seja necessário revisitar. Em seguida, vemos cada uma das histórias geradas. Para cada história, há:
- a prioridade (P1, P2, P3);
- o formato do que deveria ocorrer;
- o contexto da história como um todo;
- o motivo da prioridade;
- um teste independente (forma de validar a história);
- os critérios de aceite no padrão Given-When-Then (Dado-Quando-Então), que será muito importante para a fase de testes que faremos em breve nas próximas aulas;
- e as referências utilizadas.
Para cada história, o padrão se repete. Adiante, são trazidos casos de borda, fundamentais nas próximas etapas, usados como referência para mitigar erros. Em seguida, aparecem os requisitos funcionais, sempre atrelados a algum critério de aceite das histórias — é uma camada mais técnica que alimenta os pontos acima. Mais abaixo, temos os outcomes (resultados) mensuráveis; muitos dos testes que construiremos usarão essa parte como referência. Por fim, temos os assumptions (pressupostos): tudo que o agente, enquanto escrevia a spec, entendeu e foi registrando.
Como vimos, a partir de um parágrafo curto, o Spec Kit gerou diversos artefatos. Isso serve para deixar claro: “foi assumido X; verifiquem se está tudo correto”. É um ponto essencial para olharmos e entendermos se nada foi construído de forma incorreta.
Esclarecendo ambiguidades com o clarify
Com a nossa spec revisada, vamos para a próxima etapa, o Clarify (esclarecer). Basicamente, ele identifica o que pode ter ficado ambíguo e faz perguntas para nós, a fim de alimentar novamente o contexto e fortalecer a spec.
Um ponto sobre o funcionamento do Spec Kit: como percebemos tanto no Constitution (constituição) quanto no Specify (especificar), indicamos a skill (habilidade) que utilizaríamos e, em seguida, o texto do que seria feito. No caso específico do Spec Kit, ao rodarmos o Clarify (esclarecer), não precisamos informar nada.
Por que isso? Porque, na árvore do projeto, há o arquivo feature.json. O que o Spec Kit faz é o seguinte: sempre que trabalhamos em uma feature (funcionalidade), ela é marcada como ativa e, para todos os comandos que executarmos nas próximas etapas sem parâmetros adicionais, ele entenderá: “considere a feature ativa; a spec ativa em que estamos trabalhando agora”. No nosso caso, é a 001. Portanto, ao executar o comando, ele atuará exatamente nessa feature.
Assim, ao rodarmos /speckit-clarify e pressionarmos "Enter", o Spec Kit revisa a spec recém-criada, identifica ambiguidades e apresenta perguntas para resposta. Vamos aguardar a execução e, quando surgirem perguntas, retornaremos para respondê-las.
Para iniciar a etapa de esclarecimentos na interface:
Respondendo às perguntas de esclarecimento
Chegou a primeira pergunta. No nosso caso específico, como ela não altera nada no cliente, vamos tratá-la como fora de escopo. Assim, o sistema seguirá procurando outras ambiguidades ou pontos que precisem ser resolvidos.
Chegou mais uma pergunta.
O que acontece quando alguém tenta cancelar um pedido que já está cancelado?
Consideramos adequado retornar sucesso sem alteração nesse caso, para não sobrescrever o que já temos na documentação, que foi propositalmente deixada com alguns pontos em aberto.
Nos pedidos que não foram cancelados, a data de cancelamento e o motivo não devem aparecer na resposta; podem ficar sem valor ou serem omitidos.
Está adequado ficarem de fora.
Vamos verificar se surge mais alguma pergunta rápida.
Caso não surja, voltamos em instantes.
O processo foi concluído; inclusive indica que podemos seguir com o plano. Antes, queremos mostrar um ponto.
Quando voltamos à nossa spec (especificação), toda vez que essas perguntas são feitas — como as que acabamos de responder —, elas ficam salvas no topo do arquivo. Há uma nova seção chamada clarifications (esclarecimentos), que traz a pergunta feita e a resposta que fornecemos para cada pergunta. Como já mencionamos, tudo é salvo no mesmo arquivo para que tenhamos controle do que está acontecendo.
Enfim, vamos prosseguir.
Acabamos de construir nossa primeira spec (especificação); avançamos até o passo de clarify (esclarecimento).
Saímos do Claude Code e voltamos para o terminal; está tudo como deveria.
Preparando commit e criando tag
O primeiro passo é executar git add -A; esse comando adiciona todos os arquivos modificados e adicionados.
Comando no terminal:
Podemos ver algumas mensagens de erro; basicamente, é o Windows apontando uma formatação diferente da esperada. Provavelmente isso também ocorreu no seu ambiente, mas não há problema quanto a isso.
O segundo passo é executar git commit com o que foi feito. Podemos usar uma mensagem como “Spec Kit, constituição e spec do cancelamento”.
git commit -m "Spec Kit, constituição e spec do cancelamento"
Executou como esperado. Por fim, queremos trazer uma dica em relação às tags (marcadores). Como vamos avançar por várias etapas e, às vezes, precisamos voltar caso algo não ocorra como esperado, ao replicar o processo, crie sempre essas tags ao final de cada fase. Caso seja necessário retornar, isso torna o processo muito mais simples.
Vamos salvar como git tag v1.3-inicio.
Avançando para implementação e validação
Temos a spec aprovada; passou pelo clarify (esclarecimento). As próximas etapas são sair desse estado para termos a nossa feature (funcionalidade) implementada e validada.
É exatamente o que faremos no próximo vídeo.