00HORAS
00MIN
00SEG
Compre com desconto

Primeiras aulas do curso

SDD: Spec-Driven Development na prática

Da spec ao código com Spec Kit - Apresentação

Apresentando o curso e o instrutor

Olá! Seja bem-vinde ao curso de Spec-Driven Development (Desenvolvimento Orientado por Especificação). Já está claro que agentes conseguem construir funcionalidades em minutos. A questão é: estão fazendo o que deveria ser feito? Será que não estão quebrando outras partes importantes do projeto? É isso que veremos hoje. Vamos seguir o fluxo de ponta a ponta, garantindo que todas as etapas intermediárias disponham das ferramentas necessárias para tornar o processo o mais seguro e assertivo possível. Assim, você poderá dar autonomia ao seu agente e avançar no projeto de forma mais otimizada e produtiva. Vamos começar, pois há muito para aprendermos hoje.

Sou o Júlio Quintela.

Audiodescrição: Júlio é um homem branco, de cabelo castanho, usa óculos e tem barba. Veste uma camiseta preta e uma jaqueta verde e está no estúdio da Alura.

Trabalho com design e produtos há 17 anos, já fundei minha própria empresa e tive a oportunidade de trabalhar em algumas empresas do mercado, parte delas em startups (empresas iniciantes), desde o começo até a saída por aquisição. Isso me deu a oportunidade de aprender muito sobre produtos, tecnologia e sobre como conseguimos otimizar processos para conduzir um produto, muitas vezes, com menos recursos. Hoje, com as ferramentas que temos, seria muito mais fácil. Parte do nosso curso de hoje será dedicada a esse tema. Seja bem-vinde e vamos lá.

Organizando o roteiro e as ferramentas do curso

Vamos detalhar o que abordaremos hoje.

Na Aula 1, a ideia é analisar o Spec Kit, entendê-lo de fato e mapear suas fases e etapas, tanto da primeira quanto da segunda parte. Vamos percorrer desde a spec (especificação) — o porquê e o como — até chegar ao plano. A partir desse plano, veremos como o quebramos em tarefas e, dessas tarefas, como são implementadas e validadas para verificar se fazem sentido. Essa é a primeira camada.

A segunda parte trata da primeira camada de segurança. Em primeiro lugar, vamos garantir que o contrato do nosso projeto — neste caso, uma API — esteja seguindo uma fonte da verdade. Sabemos que o Spec Kit, por padrão, tende a escrever seus próprios contratos, e não queremos isso. Em segundo lugar, abordaremos os testes. Toda tarefa que nasce ali tem critérios de aceite e requisitos funcionais.

Queremos garantir que todos os processos estejam passando como deveriam. Para isso, utilizaremos algumas ferramentas que nos ajudarão nesse objetivo.

O terceiro ponto é começarmos a garantir que esse processo esteja mais automatizado. Assim, toda vez que abrirmos um PR (pull request, solicitação de alteração), queremos que ele já indique se devemos ou não prosseguir. Faremos isso em duas etapas. Na primeira, com o Spectral, garantimos que o Style Guide (guia de estilo) e o nosso contrato estejam seguindo o padrão devido. Na segunda, com o oasdiff, que nos alertará sobre um breaking change (mudança incompatível), garantimos que o contrato da nossa API (Interface de Programação de Aplicações) presente no PR, quando comparado com o da branch main, não terá uma quebra que impacte quem consome essa API.

No quarto movimento, queremos garantir que algumas etapas sejam mais acessíveis para as pessoas que trabalham no projeto. Um exemplo é termos um mock (simulador) da nossa API, para que as pessoas consigam interagir com ela antes de chegar ao servidor. Por meio da conformidade, no nosso caso com o Schemathesis, garantiremos não apenas a verificação do contrato e dos arquivos, mas também validações diretamente na nossa API em execução.

Além disso, faremos validações de tipos, para não precisarmos esperar um PR chegar a fim de entender se as coisas funcionaram. Como também surgem alguns erros de tipos, no momento em que estivermos trabalhando no código ou executando alguns checks (verificações), conseguiremos ganhar tempo e evitar retrabalhos.

Por fim, é onde colocamos tudo isso em conjunto. Voltamos para o Spec Kit, agora muito mais robusto com todas essas ferramentas. Assim, garantimos que o processo percorra de ponta a ponta com muito mais segurança e assertividade.

Monitorando a qualidade contínua

Para garantir que isso funcione de maneira contínua, olharemos também para o eval como um todo, para um placar, assegurando que a qualidade do que está sendo feito — seja o modelo, sejam as etapas do nosso pipeline (fluxo de processamento) ou arquivos de instruções específicas — não fique defasada nem atrapalhe o processo.

Nessas cinco aulas, vamos explorar diversas ferramentas. A ideia é oferecer um leque para que você consiga encaixar da melhor maneira possível no seu projeto e sair com um repertório muito mais completo.

Vamos lá.

Da spec ao código com Spec Kit - Conhecendo a API e o ambiente

Preparando o ambiente e as ferramentas

No arquivo README do repositório que clonamos, já estão listadas as ferramentas que vamos utilizar. Este projeto pode ser executado em macOS, Linux ou Windows. No Windows, vamos padronizar o uso do Git Bash.

Precisamos do Node.js 24, devido à própria stack (pilha) do projeto hipotético que utilizaremos. Também vamos usar Git e GitHub, com conta ativa e o GitHub CLI (interface de linha de comando), para que possamos executar comandos diretamente no terminal.

Utilizaremos o uv, que vai auxiliar na instalação do Spec Kit e também do Schemathesis. Nesse caso, o uv cria um ambiente isolado, portanto não é necessário instalar Python na máquina local.

Quanto ao agente de código, vamos usar o Claude Code, mas você pode utilizar o de sua preferência. O processo terá apenas uma configuração diferente, que vamos demonstrar.

Por fim, como sugestão, revisar conceitos de API REST e TypeScript ajudará a entender alguns trechos de código e modificações ao longo do curso. Em caso de dúvida, consulte as instruções de instalação no README.

Apresentando a TechLog API e a documentação legada

Para o nosso projeto, a TechLog API que vamos utilizar é um projeto hipotético. Basicamente, há um cliente web que lista todos os pedidos. A API em si expõe três endpoints (pontos de extremidade): listagem, busca e criação de pedidos. Por fim, temos uma documentação que, neste caso específico, consideramos como legado, pois já passou por várias mãos. Isso traz três pontos importantes:

  • Mistura de convenções snake_case e camelCase na mesma documentação e na mesma API.
  • Dois formatos de erro em produção, enquanto a documentação sinaliza apenas um.
  • Ausência de um contrato formal estável.

Essas características serão a base que vamos utilizar para seguir o curso como um todo.

Configurando o workspace no VS Code

Agora, vamos para o VS Code. Você pode usar a ferramenta de sua preferência; estamos utilizando o VS Code para facilitar, pois conseguimos ver a árvore de arquivos, abrir o terminal para executar tarefas do projeto e interagir com o próprio Claude Code, além de fazer algumas edições diretas que não necessariamente vêm do agente.

Após clonar o repositório, abrimos o projeto. Utilizamos o comando de menu Open Folder (Abrir Pasta) para abrir a pasta "TechLog". No nosso ambiente de gravação aparece “API gravação”, por se tratar do contexto desta aula, enquanto no repositório de vocês estará vinculado ao curso.

Primeiro, confirmamos que estamos na branch main, garantindo que está tudo certo neste primeiro momento. Em alguns pontos, vamos trazer conteúdos já preenchidos para agilizar e evitar digitação extensa durante o curso.

O repositório que clonamos contém algumas branches que vamos utilizar como suporte, e vamos explicar brevemente sobre elas. O laço for b basicamente serve para trazer todas elas para a nossa máquina local.

A referencia traz os arquivos em sua versão final. O que isso significa? Em alguns momentos, durante este curso, nós vamos escrever um caso de teste de exemplo, mas, no arquivo final, deveríamos ter um 6, 7 ou 8. Essa referência nos ajuda a preencher todas aquelas 200 ou 300 linhas, o que não será o foco aqui neste curso. A ideia é que isso esteja disponível para que você também consiga fazer.

As outras duas, como podemos ver ali, sincronia-2.1 e reserva-1.3, são para o caso de o agente travar ou, caso você obtenha um resultado muito diferente do que estamos mostrando aqui, para que seja possível retornar e seguir corretamente, acompanhando exatamente como estamos exibindo em tela.

Executando os comandos iniciais do projeto

Vamos executar o primeiro comando. Ao pressionarmos "Enter", ele já retornou o resultado e confirmou que todas foram criadas localmente.

O segundo movimento aqui é executar npm install. Basicamente, ele vai obter todas as dependências do nosso projeto e instalá-las na sua máquina. Foi rapidamente; havia poucas coisas para instalar e já foram baixadas.

O próximo é um comando que disponibilizamos: npm run conferir. O que ele faz? Ele gera um relatório e apresenta um "ok" para todas as ferramentas. Lembra daquela verificação no repositório, no README, para conferir se estava tudo certo? É aqui que confirmamos se está tudo certo antes de avançarmos no curso. Ele está retornando "ok" em tudo. No Spec Kit, esse item está marcado como "depois"; nós vamos configurar isso durante uma das aulas em breve, então está tudo bem ainda não estar instalado. Todo o resto está "ok".

Com isso, a configuração está feita. Para facilitar, nós dividimos o terminal para iniciar nossa aplicação e mantê-la rodando. Vamos deixá-la em segundo plano, porque, nos próximos passos, vamos modificar alguns arquivos; o processo já irá atualizar automaticamente, com um fluxo de watch (monitoramento), e conseguiremos acompanhar tudo pela nossa URL (Localizador Uniforme de Recursos).

Agora, vamos abrir nossa aplicação. Já configuramos o host (servidor). Como podemos ver, estamos com o cliente rodando e a aplicação listou os 5 pedidos do nosso exemplo. Tudo aqui está vindo pela API (Interface de Programação de Aplicações), e está tudo certo. Esse é o primeiro ponto.

Revisando a documentação e alinhando expectativas

O segundo ponto, antes de seguirmos, é em relação à documentação. Comentamos que ela está desatualizada de alguma maneira. Está super simples, como vocês vão perceber. Existem alguns tópicos que vamos abordar durante o curso — por exemplo, a questão dos erros. Na documentação, apenas um dos formatos é mencionado, mas veremos que, de fato, são dois: aqui estamos utilizando tanto o formato em snake_case quanto em camelCase. Como mencionamos, a documentação é propositalmente simples. A ideia é simular algo mais próximo da realidade: em algum momento, ampliamos o projeto e não revisamos a documentação tanto quanto deveríamos; algumas dessas diferenças relacionadas à API não quebram o sistema.

Este é o documento que vamos usar como referência. Em alguns momentos, vamos consultar essa documentação para fazer cruzamentos. A proposta de mantê-la simples e um pouco defasada, de propósito, é para que possamos colocar em prática alguns ajustes e mudanças que acabam ajudando, de certa maneira, no nosso projeto.

No próximo vídeo, vamos analisar mais a fundo o Spec Kit: como funciona, como vem configurado e quais são as etapas que podemos utilizar nele, colocando em prática, para sairmos da spec (especificação) até uma feature (funcionalidade) implementada.

Da spec ao código com Spec Kit - Criando constituição e spec

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:

specify version

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:

git status --short

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:

/speckit-constitution

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:

/speckit-specify

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:

/speckit-clarify

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:

git add -A

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.

Sobre o curso SDD: Spec-Driven Development na prática

O curso SDD: Spec-Driven Development na prática possui 191 minutos de vídeos, em um total de 47 atividades. Gostou? Conheça nossos outros cursos de IA para Desenvolvimento de Software em Inteligência Artificial, ou leia nossos artigos de Inteligência Artificial.

Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:

  • Da spec ao código com Spec Kit
  • Contratos OpenAPI e critérios de aceite
  • Gates de validação para pull requests
  • Conformidade da API com o contrato
  • Avaliação e evolução do fluxo

Aprenda IA para Desenvolvimento de Software acessando integralmente esse e outros cursos. Comece hoje!

Plus 24

Todos os cursos, trilhas e certificados para evoluir.

Carregando precos do plano

7 dias para cancelar com reembolso

Alura EmpregabilidadeNOVO
  • Acesso ao maior portal de vagas tech do BrasilExclusivo na Black
  • Modo entrevista técnica e comportamental
  • 2.348 Cursos e 37 Carreiras
  • Certificados reconhecidos pelo mercado
  • Luri: nossa IA exclusiva, que acelera e personaliza seu aprendizado

Pro 24

Aprenda mais rápido com IA, idiomas e imersões.

Carregando precos do plano

7 dias para cancelar com reembolso

TUDO DO PLUS, MAIS:

Alura EmpregabilidadeNOVO
  • Acesso ao maior portal de vagas tech do Brasil
  • Modo entrevista técnica e comportamental
  • Desafios de código
  • System design
  • Luri Vision: a versão mais completa da nossa IA, que permite envio de imagens
  • Livros da Casa do código: Acesso ao acervo de livros da maior editora tech do país
  • Alura Língua: cursos de inglês e espanhol com foco na área tech

Ultra Lab 24

Aceleração de carreira: mentoria, vagas e prática guiada.

Carregando precos do plano

7 dias para cancelar com reembolso

TUDO DO PRO, MAIS:

Alura EmpregabilidadeNOVO
  • Acesso ao maior portal de vagas tech do Brasil
  • Modo entrevista técnica e comportamental
  • Desafios de código
  • System design
  • 2 mentorias individuais com foco na sua carreira
  • Luri Vision Ilimitada: a versão mais completa da nossa IA
  • Lives CareerUp: eventos exclusivos com foco em empregabilidade e carreira
Melhor opção para a sua carreira
Conheça os Planos para Empresas