Pular para o conteúdo principal

Aula 19: Spec-Driven Development com Jakarta EE e Quarkus

Objetivos​

  • Compreender o que é Spec-Driven Development (SDD) e por que ele surgiu como resposta ao vibe coding
  • Identificar os três problemas concretos do vibe coding em projetos que crescem
  • Relacionar os artefatos do SDD (constitution.md, spec.md, plan.md, tasks.md) com os documentos da disciplina (visao.md, prd.md)
  • Elaborar um constitution.md e um spec.md calibrados para a stack Jakarta EE + Quarkus do projeto pessoal
  • Configurar o GitHub Spec Kit no repositório e compreender como ele guia agentes de IA na implementação

Contexto e Motivação​

Existe uma percepção comum de que IA torna documentação desnecessária: você descreve o que quer no chat e ela gera o código. Essa percepção funciona até certo ponto — e quebra de formas previsíveis.

No CritiqueHub, considere a seguinte instrução dada a um agente de IA sem contexto prévio:

"Adiciona ao projeto um sistema de avaliações com nota e comentário."

O agente vai gerar código. Provavelmente vai compilar. Mas sem especificação, ele não sabe:

Decisão não especificadaConsequências possíveis
Uma avaliação por usuário por item, ou múltiplas?Constraint de unicidade presente ou ausente no banco
Nota é inteiro de 1–5 ou decimal de 0–10?Tipo de coluna e validação divergem do restante do sistema
Usuario tem coleção @OneToMany de Avaliacao?Bidirecionalidade implementada ou ignorada
Cascade correto para remoção de usuário?Orphans no banco ou remoção catastrófica em cascata
Camada de serviço separada da backing bean?Arquitetura em camadas violada silenciosamente

A IA não inventou soluções erradas — ela tomou decisões na ausência de especificação. Spec-Driven Development elimina essa ambiguidade ao tornar a especificação o artefato primário de desenvolvimento.

Conteúdo​

O que é Vibe Coding — e onde ele quebra​

Vibe coding descreve o padrão de interação com agentes de IA onde o desenvolvedor fornece prompts informais e aceita o código gerado sem especificação estruturada prévia.

O padrão funciona bem para protótipos isolados. Em projetos que crescem, três problemas emergem de forma sistemática.

Problema 1 — Dívida de contexto​

Cada sessão com um agente de IA começa do zero. A IA não lembra que Avaliacao tem @ManyToOne para Usuario e ItemCultural, que a camada de serviço usa @Transactional, que o application.properties já define o datasource. O desenvolvedor precisa recontextualizar a IA a cada sessão — e quanto mais o projeto cresce, mais tempo é gasto recontextualizando.

aviso

O custo composto da recontextualização: um projeto com 10 funcionalidades implementadas e sem spec pode exigir centenas de linhas de prompt só para reconstruir o contexto a cada nova sessão. A eficiência percebida do vibe coding na semana 1 inverte na semana 4.

Problema 2 — Deriva de requisitos​

Sem um documento que registre o que o sistema deve fazer, a fronteira entre intenção e implementação se torna invisível. Funcionalidades novas são adicionadas sem considerar as anteriores. Regras de negócio são implementadas de formas diferentes em módulos diferentes. O sistema se afasta gradualmente da intenção original — sem que ninguém perceba quando isso aconteceu.

Problema 3 — Código que não pertence ao sistema​

Quando a IA não conhece a arquitetura do projeto, ela gera código que funciona em isolamento mas viola as convenções estabelecidas. Em um projeto Jakarta EE com arquitetura em camadas, um agente sem spec pode:

  • Injetar EntityManager diretamente em uma backing bean (violando a separação de camadas)
  • Usar FetchType.EAGER em coleções (violando a estratégia de fetch do projeto)
  • Gerar um endpoint REST quando o projeto usa apenas Faces
  • Nomear entidades e campos em português quando a convenção é inglês

O resultado é um sistema que funciona parcialmente mas é inconsistente — difícil de manter e de entender por outro desenvolvedor.

Spec-Driven Development — o princípio central​

SDD inverte a relação entre especificação e código:

A especificação não é documentação retroativa — é a fonte da verdade que determina o que o agente de IA vai construir. Isso resolve os três problemas:

Problema do vibe codingComo o SDD resolve
Dívida de contextoA spec é o documento persistente que o agente lê no início de cada sessão
Deriva de requisitosMudanças passam pela spec antes de chegar ao código
Código que não pertenceA spec encoda a arquitetura e as convenções que o agente deve respeitar

Raízes do SDD: TDD, BDD e a evolução das práticas​

O SDD não surge do nada — ele herda e estende uma longa tradição de práticas que colocam a especificação antes da implementação.

PráticaO que especifica antes de implementarEscopo
TDD (Test-Driven Development)Comportamento esperado de uma função ou método — via testes automatizadosUnidade de código
BDD (Behaviour-Driven Development)Comportamento do sistema do ponto de vista do usuário — via cenários Gherkin (Given / When / Then)Funcionalidade
SDD (Spec-Driven Development)Arquitetura, convenções, domínio e unidades de trabalho — via documentos de texto estruturado lidos pelo agente de IASistema completo

A diferença essencial é o consumidor da especificação: em TDD e BDD, quem "lê" a spec é o framework de testes; em SDD, quem lê é o agente de IA antes de escrever qualquer linha de código. O princípio de fundo é o mesmo: tornar as intenções do desenvolvedor explícitas e verificáveis antes da implementação.

observação

TDD e BDD são estudados em detalhe em Testes Automatizados (Aula 06 desta disciplina). O SDD não os substitui — todos podem coexistir no mesmo projeto.

SDD em bases de código grandes e sistemas legados​

Em um sistema com dezenas de entidades, serviços e telas, um agente de IA sem spec enfrenta um problema de contexto estrutural: nenhum modelo tem janela de contexto suficiente para processar o projeto inteiro. Ele vai trabalhar cego para a maior parte do sistema.

O risco concreto: você pede para adicionar uma feature de relatórios. O agente gera o código sem saber que o projeto usa @ApplicationScoped para repositórios, que as queries são JPQL com parâmetros nomeados, que o padrão de paginação já existe no BaseRepository. O código gerado compila, mas viola padrões estabelecidos em vários pontos.

Com SDD: a constitution.md encoda esses padrões explicitamente. O agente os recebe como instrução antes de escrever uma linha de código. O resultado é código que parece nativo ao projeto — não colado de outro sistema.

<!-- Trecho de constitution.md para um projeto Quarkus grande -->

## Padrões de código

- Repositórios: `@ApplicationScoped`, injetam `EntityManager` via `@Inject`
- Queries: JPQL com parâmetros nomeados (nunca concatenação de String)
- Paginação: seguir o padrão de `BaseRepository.paginar(query, pagina, tamanho)`
- Nenhuma lógica de negócio em backing beans — apenas delegação para a camada de serviço
- Serviços: `@ApplicationScoped` com `@Transactional` nos métodos de escrita

Os quatro artefatos do Spec Kit​

O GitHub Spec Kit é uma CLI open source lançada pelo GitHub em setembro de 2025 para implementar SDD com agentes de IA. Rapidamente se tornou uma das ferramentas mais adotadas nesse espaço — sinal de que a dor que ela resolve é real e amplamente sentida. Ela estrutura o processo em quatro documentos que vivem no repositório e são versionados junto com o código.

ArtefatoPergunta respondidaQuem escreveEquivalente na disciplina
constitution.mdQuais são as regras inegociáveis?DesenvolvedorStack e arquitetura definidas pelo professor + escolhas do aluno
spec.mdO que o sistema deve fazer?Desenvolvedordocs/prd.md (seções 2, 3 e 4)
plan.mdComo a spec será implementada?Agente de IAdocs/prd.md (seções 5 e 6)
tasks.mdQuais são as unidades de trabalho?Agente de IAIssues de Requisito no GitHub
observação

PRD ≠ spec.md, mas a lógica é a mesma. O PRD da disciplina é mais abrangente do que o spec.md do Spec Kit — inclui requisitos não funcionais, diagrama ER e plano de sprints que o Spec Kit distribui entre outros artefatos. O princípio é idêntico: especificação escrita pelo desenvolvedor antes da implementação.

constitution.md — as regras que o agente não pode violar​

A constitution codifica a stack, os padrões de código e as convenções arquiteturais do projeto. É o primeiro documento que o agente lê em qualquer sessão.

# Constitution — [Nome do Projeto]

## Missão

[Uma frase descrevendo o propósito central do sistema.]

## Stack tecnológica

| Camada | Tecnologia | Versão |
|---|---|---|
| Runtime | Quarkus | 3.31.x |
| Jakarta EE | CDI, JPA, Faces, Bean Validation | 3.x |
| ORM | Hibernate ORM | 6.x |
| Banco de dados | PostgreSQL | 16 |
| Build | Maven | 3.9+ |
| Java | JDK | 21 |

## Arquitetura

O projeto segue arquitetura em quatro camadas estrita:

```
Presentation  →  Backing Beans (@Named, @ViewScoped / @RequestScoped)
Service       →  @ApplicationScoped com @Transactional
Repository    →  @ApplicationScoped com EntityManager injetado
Entity        →  @Entity JPA
```

**Regras absolutas:**
- Backing beans delegam para serviços — nunca acessam repositório ou EntityManager diretamente
- Serviços contêm toda a lógica de negócio — nunca expõem entidades JPA diretamente para as views
- Repositórios só executam queries — nenhuma lógica de negócio
- Entidades são POJOs JPA — nenhum import de CDI ou de serviços

## Convenções de código

- Nomes de entidades e campos em **inglês** (ex: `User`, `createdAt`)
- Nomes de classes de serviço terminam em `Service`, repositórios em `Repository`
- Queries JPQL com parâmetros nomeados (`:param`) — nunca concatenação de String
- `FetchType.LAZY` como padrão para coleções — `EAGER` requer justificativa explícita
- `equals()` e `hashCode()` baseados em `id` em todas as entidades

## O que este projeto NÃO usa

- Nenhum endpoint REST (sem `@Path`, `@GET`, `@POST`)
- Nenhum framework de frontend JavaScript
- Nenhuma dependência fora do `pom.xml` aprovado

## Segurança

- Autenticação: Jakarta Security com `@RolesAllowed` em métodos de serviço — sem filtros manuais em backing beans
- Papéis existentes: `ADMIN`, `USER` — definidos em `import.sql`, não codificados na `constitution.md`
- Regra absoluta: nenhum dado de outro usuário pode ser lido ou modificado sem verificação de papel
- `HttpAuthenticationMechanism`: form-based com redirect para `/login.xhtml`
- Senhas: nunca armazenadas em texto plano — delegar ao mecanismo Jakarta Security

spec.md — o que o sistema faz​

A spec descreve comportamentos, regras de negócio e restrições em linguagem precisa. Ela é a ponte entre o domínio e a implementação.

Estrutura recomendada para o contexto da disciplina:

# Spec — [Nome do Projeto]

## Escopo

[2–3 frases descrevendo o sistema e o problema que resolve.]

## Funcionalidades

### F-001: [Nome da funcionalidade]

**Descrição:** [O que o usuário consegue fazer.]

**Regras de negócio:**
- RN-001: [Regra específica e mensurável]
- RN-002: [Regra específica e mensurável]

**Entidades envolvidas:** `User`, `Order`

**Critério de aceite:**
- [ ] [Comportamento observável 1]
- [ ] [Comportamento observável 2]

---

### F-002: [Nome da funcionalidade]
...

Exemplo para o CritiqueHub — funcionalidade de avaliação:

### F-003: Registrar avaliação de item cultural

**Descrição:** Um usuário autenticado pode registrar uma avaliação composta
por nota inteira (1–5) e texto opcional (até 2.000 caracteres) para qualquer
item cultural do catálogo. Cada usuário pode registrar no máximo uma avaliação
por item.

**Regras de negócio:**
- RN-007: Nota deve ser inteiro entre 1 e 5 inclusive — Bean Validation com `@Min(1) @Max(5)`
- RN-008: Um usuário não pode avaliar o mesmo item mais de uma vez — constraint única em `(usuario_id, item_cultural_id)`
- RN-009: A exclusão de um usuário remove todas as suas avaliações em cascata — `CascadeType.REMOVE` com `orphanRemoval = true`
- RN-010: Avaliação não pode ser criada por usuário com status `BLOQUEADO`

**Entidades envolvidas:** `User`, `Review`, `CulturalItem`

**Critério de aceite:**
- [ ] Ao submeter o formulário com nota válida, a avaliação aparece na listagem do item
- [ ] Ao tentar avaliar o mesmo item duas vezes, o sistema exibe mensagem de erro sem lançar exceção para o usuário
- [ ] Nota fora do intervalo 1–5 é rejeitada com mensagem de validação antes de chegar ao serviço
- [ ] Usuário com status BLOQUEADO recebe mensagem de erro ao tentar avaliar
aviso

Critérios de aceite vagos invalidam a spec. "O sistema funciona corretamente" não é um critério de aceite — é uma esperança. Cada critério deve descrever um comportamento observável que você consegue verificar abrindo a aplicação ou lendo o log.

Rubrica de auto-avaliação antes de chamar speckit.plan:

CritérioPergunta de verificação
CompletudeCada RF priorizado no sprint tem pelo menos uma entrada em spec.md?
Separação de camadasA spec descreve o quê, não como? (ex: "usuário vê mensagem de erro" — não "FacesContext lança mensagem do tipo WARN")
TestabilidadeCada critério de aceite pode ser verificado abrindo a aplicação ou lendo um log?
ConsistênciaAlguma funcionalidade contraria as regras inegociáveis de constitution.md?
Não-redundânciaNenhuma regra de negócio aparece descrita de formas diferentes em dois lugares?

Se qualquer critério falhar, chame speckit.clarify antes de prosseguir para speckit.plan.

plan.md — como a spec será implementada​

O plan.md traduz as funcionalidades da spec em decisões técnicas concretas. No fluxo do Spec Kit, ele é gerado pelo agente após a leitura da spec e da constitution — mas você pode e deve revisá-lo antes de autorizar a implementação.

# Plano de implementação — F-003: Registrar avaliação

## Modelo de dados

```java
@Entity
@Table(name = "reviews",
    uniqueConstraints = @UniqueConstraint(columnNames = {"user_id", "cultural_item_id"}))
public class Review extends BaseEntity {

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "user_id", nullable = false)
    private User user;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "cultural_item_id", nullable = false)
    private CulturalItem culturalItem;

    @Min(1) @Max(5)
    @Column(nullable = false)
    private Integer rating;

    @Column(length = 2000)
    private String content;
}
```

## Camada de repositório

`ReviewRepository` com os métodos:
- `save(Review)` — persiste nova avaliação
- `findByUserAndItem(Long userId, Long itemId): Optional<Review>`
- `findByItem(Long itemId): List<Review>`

## Camada de serviço

`ReviewService.register(Long userId, Long itemId, int rating, String content)`:
1. Verificar status do usuário — lança `BusinessException` se BLOQUEADO
2. Verificar duplicidade via `ReviewRepository.findByUserAndItem`
3. Construir e persistir a entidade `Review`

## Camada de apresentação

`ReviewBacking` (`@Named`, `@ViewScoped`) com campos `rating`, `content` e método `submit()` que delega para `ReviewService`.

tasks.md — unidades de trabalho​

O tasks.md quebra o plano em tarefas atômicas que o agente executa uma por uma, com verificação entre cada uma.

# Tarefas — F-003: Registrar avaliação

## Tarefa 1: Entidade Review

- [ ] Criar classe `Review` em `br.edu.exemplo.critiquehub.entity`
- [ ] Mapear `@ManyToOne` para `User` e `CulturalItem` com `FetchType.LAZY`
- [ ] Adicionar constraint única `(user_id, cultural_item_id)` via `@UniqueConstraint`
- [ ] Implementar `equals()` e `hashCode()` baseados em `id`
- **Verificação:** `mvn quarkus:dev` sobe sem erro; tabela `reviews` criada pelo Hibernate

## Tarefa 2: ReviewRepository

- [ ] Criar `ReviewRepository` em `.repository`
- [ ] Implementar `save(Review)`, `findByUserAndItem`, `findByItem`
- **Verificação:** métodos compilam; repositório é injetável via CDI

## Tarefa 3: ReviewService

- [ ] Criar `ReviewService` em `.service` com `@ApplicationScoped`
- [ ] Implementar `register()` com verificações de status e duplicidade
- [ ] Anotar o método com `@Transactional`
- **Verificação:** lógica cobre os critérios de aceite RN-007 a RN-010

## Tarefa 4: ReviewBacking + view Faces

- [ ] Criar `ReviewBacking` em `.backing` com `@Named` e `@ViewScoped`
- [ ] Criar `avaliacao.xhtml` com formulário de nota e texto
- [ ] Exibir mensagem de erro via `FacesContext` nos casos de exceção
- **Verificação:** formulário funcional no browser; erro exibido para duplicidade
observação

Verificações são checkpoints humanos. O fluxo do Spec Kit não é "IA implementa tudo e você verifica no final" — é "IA implementa uma tarefa, você verifica, IA implementa a próxima". Isso é o oposto do vibe coding: o humano permanece no controle do que está sendo construído.

F-003 de ponta a ponta: como os artefatos se encadeiam​

Os exemplos das seções anteriores formam uma cadeia completa para a funcionalidade F-003 do CritiqueHub. Cada artefato opera em um nível de abstração diferente e alimenta o seguinte:

A constitution.md define o que o agente não pode fazer. A spec.md descreve o que o usuário consegue fazer e as regras de domínio. O plan.md traduz essas regras em decisões técnicas concretas. O tasks.md quebra o plano em passos atômicos verificáveis.

Anti-patterns comuns no SDD​

Saber o que não fazer é tão importante quanto conhecer o fluxo correto. Os erros abaixo aparecem com frequência quando se começa a usar SDD:

Anti-patternSintoma observávelCorreção
Spec que descreve implementaçãospec.md menciona @ManyToOne, FetchType.LAZY, nomes de tabelas ou classes JavaMover para plan.md; spec.md usa linguagem de domínio
Constitution estáticaconstitution.md escrito no Sprint 1 e nunca mais revisadoAtualizar sempre que a stack ou arquitetura evoluir
Critério de aceite no imperativo"O sistema deve validar o status antes de processar"Reescrever como comportamento observável: "Ao tentar cancelar pedido ENVIADO, o usuário vê mensagem X"
Pular speckit.clarifyplan.md gerado ignora casos-limite evidentes da specChamar speckit.clarify antes de speckit.plan quando a spec tiver áreas vagas
Código antes da specCódigo alterado sem atualizar spec.md primeiroRFC → prd.md → spec.md → plan.md → código; nunca inverter a ordem
perigo

O anti-pattern mais custoso é o último. Quando o código diverge da spec, o agente lê uma spec que não descreve mais o sistema real. Na próxima sessão, ele vai "corrigir" o código para seguir a spec desatualizada — desfazendo mudanças intencionais silenciosamente.

Configuração do GitHub Spec Kit​

# Pré-requisito: uv (gerenciador de pacotes Python)
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# macOS com Homebrew:
# brew install uv

# Instalar o Specify CLI (versão estável mais recente)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Verificar instalação
specify version

Relacionamento entre os documentos da disciplina e o SDD​

Agentes do Spec Kit: seleção e workflow​

O Spec Kit instala um conjunto de agentes especializados no repositório. Cada agente lê os artefatos existentes e executa uma etapa bem definida do fluxo SDD — nenhum deles deve ser chamado fora de ordem.

Visão geral dos agentes​

AgenteQuando chamarEntradaSaída
speckit.constitutionUma vez, no início do projetoPerguntas interativas sobre o projetospec/constitution.md criado/atualizado
speckit.specifyPara cada funcionalidade nova ou RFC recebidoDescrição em linguagem naturalspec/spec.md atualizado
speckit.clarifyQuando a spec tiver lacunas ou ambiguidadesspec.md com áreas vagasAté 5 perguntas + respostas incorporadas na spec
speckit.planApós a spec estar aprovadaconstitution.md + spec.mdspec/plan.md gerado
speckit.tasksApós revisar o plan.mdplan.mdspec/tasks.md com tarefas ordenadas por dependência
speckit.implementPara executar o planotasks.mdCódigo implementado tarefa por tarefa
speckit.analyzeApós atualizar qualquer artefatoTodos os artefatosRelatório de inconsistências entre spec, plan e tasks
speckit.checklistAntes de abrir um PRRequisitos da funcionalidadeChecklist de validação customizado

Sequência do fluxo completo​

Como invocar: Claude Code vs GitHub Copilot​

Claude Code — slash commands no terminal integrado:

# Criar/atualizar a constitution interativamente
/speckit.constitution

# Especificar uma funcionalidade nova (ex: F-003)
/speckit.specify

# Refinar a spec quando ela tiver áreas ambíguas
/speckit.clarify

# Gerar o plano de implementação a partir da spec
/speckit.plan

# Gerar as tarefas ordenadas a partir do plano
/speckit.tasks

# Executar as tarefas em loop com verificação entre cada uma
/speckit.implement

# Verificar consistência entre spec, plan e tasks após qualquer mudança
/speckit.analyze

GitHub Copilot — agentes no painel Chat do VS Code:

No painel Copilot Chat (Ctrl+Alt+I), selecione o agente pelo seletor de modo ou use @:

@speckit.specify Adicionar funcionalidade de avaliação ao CritiqueHub
@speckit.plan Gerar plano para a F-003
@speckit.tasks Criar tasks a partir do plan.md atual
@speckit.implement Executar a próxima tarefa pendente
observação

Qual agente usar na disciplina? Para quem usa VS Code com Copilot, os agentes @speckit.* no Chat são a integração mais direta. Para quem usa Claude Code, os slash commands /speckit.* são equivalentes. Os artefatos gerados — plan.md, tasks.md — são idênticos independentemente do agente escolhido.

SDD no ciclo de sprints da disciplina​

O fluxo do Spec Kit se encaixa diretamente no modelo de sprints. A tabela abaixo mapeia quando cada artefato é criado ou atualizado ao longo do projeto:

Momento no projetoAção SDDArtefato produzido
Início do projeto (antes do Sprint 1)speckit.constitution — preencher stack e arquiteturaconstitution.md inicial
Início de cada sprintspeckit.specify para cada RF priorizadospec.md com novas funcionalidades
Antes de implementarspeckit.clarify se houver ambiguidades; depois speckit.planplan.md revisado pelo aluno
Início da implementaçãospeckit.taskstasks.md com tarefas ordenadas por dependência
Durante o sprintspeckit.implement tarefa por tarefa, com verificação em cada etapaCódigo integrado ao repositório
Ao receber RFCAtualizar prd.md → speckit.specify → speckit.plan → speckit.tasksArtefatos sincronizados
Antes de abrir PRspeckit.analyze → speckit.checklistRelatório de consistência
Revisão de sprintVerificar se constitution.md ainda reflete as decisões do projetoconstitution.md atualizado se necessário
observação

A constitution não é estática. Na semana 1 do projeto, você ainda não conhece todas as convenções que vai adotar. Atualize a constitution.md cada vez que o projeto estabelecer um novo padrão arquitetural — antes que o agente gere código inconsistente com ele.

Laboratório — Elaborando os artefatos SDD do projeto pessoal​

Exercício 1: constitution.md​

Crie o arquivo spec/constitution.md no repositório do seu projeto com as seguintes seções obrigatórias:

  1. Missão — uma frase descrevendo o propósito do sistema
  2. Stack tecnológica — tabela com tecnologia e versão (baseie-se no pom.xml gerado na Sprint 1)
  3. Arquitetura — reproduza o diagrama de camadas e enumere as regras absolutas específicas do seu projeto
  4. Convenções de código — pelo menos 5 regras concretas (nomenclatura, padrões de query, estratégia de fetch, etc.)
  5. Fora de escopo — liste o que este projeto explicitamente não faz

Critério de aceite: outro aluno consegue ler sua constitution.md e entender quais decisões técnicas não são negociáveis no seu projeto, sem precisar ler o código.

Exercício 2: spec.md — primeira funcionalidade​

Escreva a especificação de uma funcionalidade de prioridade Alta do seu PRD no formato de spec.md.

O documento deve conter:

  • Descrição em linguagem de domínio (sem termos técnicos como "tabela" ou "query")
  • Pelo menos 3 regras de negócio numeradas (RN-XXX) com critério mensurável
  • Lista de entidades JPA envolvidas
  • Pelo menos 3 critérios de aceite verificáveis

Exemplo de regra de negócio aceitável vs. inaceitável:

- RN-012: Um pedido só pode ser cancelado se seu status for PENDENTE ou
  CONFIRMADO — pedidos com status ENVIADO ou ENTREGUE não podem ser
  cancelados; a tentativa deve retornar mensagem de erro específica para
  cada status inválido

Exercício 3: Mapeamento PRD → artefatos SDD​

Preencha a tabela abaixo para o seu projeto, identificando qual seção do PRD corresponde a qual artefato do Spec Kit e o que ainda precisaria ser detalhado para usar o Spec Kit completamente:

Seção do PRDArtefato SDD correspondenteO que está detalhadoO que falta detalhar
Seção 2 — RFspec.md (funcionalidades)
Seção 3 — RNFconstitution.md (restrições)
Seção 4 — Modelo ERspec.md (entidades)
Seção 5 — Arquiteturaconstitution.md (stack + camadas)
Seção 6 — Plano de sprintstasks.md (agrupado por sprint)

Exercícios (Checkpoints)​

  1. Descreva os três problemas do vibe coding com exemplos concretos do domínio do seu próprio projeto — não exemplos genéricos. Para cada problema, explique como a escrita do PRD o endereça.

  2. Um colega argumenta: "meu projeto é pequeno, tem só 5 entidades, não preciso de spec". Construa um contra-argumento usando os conceitos de dívida de contexto e deriva de requisitos.

  3. Qual a diferença entre constitution.md e spec.md? Dê um exemplo de informação que pertence a cada um no contexto de um sistema Quarkus com Jakarta Faces.

  4. Um RFC é emitido no seu repositório modificando a funcionalidade F-003 do seu PRD. Descreva em ordem os artefatos que precisam ser atualizados e por quê a spec deve ser atualizada antes do código.

  5. Compare o fluxo de trabalho do Spec Kit com o modelo de sprints da disciplina. Onde os dois se complementam? Existe alguma tensão entre eles?

  6. (Desafio) Instale o Spec Kit no repositório do projeto e rode specify init com o agente de sua preferência. Documente no docs/relatorio.md: o que foi criado, qual foi o primeiro prompt que você testou, e o que o agente gerou de diferente quando tinha acesso à constitution.md versus sem ela.

Outros frameworks e abordagens SDD​

O Spec Kit não é o único projeto que formaliza o fluxo de especificação antes da implementação com agentes de IA. A tabela abaixo apresenta as principais alternativas e como cada uma se diferencia:

FerramentaMantida porObjetivo principalDiferença em relação ao Spec Kit
Cursor RulesAnysphere (Cursor)Configurar regras e contexto permanente para o agente dentro do editor CursorFocada em um editor específico; não estrutura o fluxo completo spec → plan → tasks — apenas injeta regras no contexto
Claude CLAUDE.mdAnthropicArquivo de memória persistente lido pelo Claude Code em todas as sessõesEquivalente informal ao constitution.md; não inclui agentes para plan.md e tasks.md
OpenAI Codex InstructionsOpenAIInstruções de sistema persistentes para o agente no ambiente cloudInstrução de contexto, não um fluxo estruturado; não cobre spec ou decomposição em tarefas
aiderPaul GauthierEdição de código com agente via terminal, com histórico de conversas no repositórioFerramenta de edição incremental; usa .aider.conf.yml para convenções, mas não tem estrutura de spec/plan/tasks
AutoDevUnit MeshPlugin de IDE (IntelliJ/VS Code) que estrutura o desenvolvimento em stories → tarefasMais próximo do Spec Kit em estrutura; orientado a histórias de usuário no formato ágil, não a artefatos de spec
BMAD Methodbmadcode (comunidade)Breakthrough Method of Agile AI-Driven Development — orquestra múltiplos agentes especializados (Analista, Arquiteto, Dev, QA) ao longo de todo o ciclo de desenvolvimentoA diferença mais marcante: o BMAD define personas de agente (cada agente assume um papel — PM, Arquiteto, Dev) e coordena handoffs entre eles; o Spec Kit foca nos artefatos como fonte de verdade lida por um único agente

A distinção central do Spec Kit em relação a essas abordagens é o fluxo completo e versionado: constitution.md → spec.md → plan.md → tasks.md, todos vivendo no repositório como código, com agentes especializados para cada etapa. As demais ferramentas tendem a focar em uma única camada — contexto do agente, edição incremental ou instruções de sistema — sem cobrir o ciclo de vida completo da especificação até a decomposição em tarefas verificáveis.

Referências​

Principais​

Aprofundamento​