Fluxo de Trabalho de Desenvolvimento Orientado por Especificações: Da Definição de Requisitos ao Código

O Desenvolvimento Orientado por Especificação (Spec-Driven Development) funciona quando a especificação é um fluxo de trabalho, e não um documento que se arquiva após o início. O objetivo não é produzir um grande documento de requisitos de produto.

O objetivo é avançar por uma sequência de artefatos revisáveis que, cada um, reduzem a ambiguidade antes que qualquer pessoa — humana ou agente de IA — altere o código de produção.

Se você não sabe o que é SDD conceitualmente, comece por O que é Desenvolvimento Orientado por Especificação? para definições, comparações com TDD e BDD, e o argumento para tratar a especificação como fonte da verdade. Este artigo no cluster de documentação Arquitetura de Aplicativos é o guia operacional. Ele percorre as cinco fases, mostra o que cada artefato deve conter, explica onde os agentes de IA se encaixam e fornece modelos reutilizáveis que você pode copiar para seu repositório hoje.

SDD é um Fluxo de Trabalho, Não um Documento

O modo de falha mais comum no desenvolvimento orientado por especificação é tratar a especificação como burocracia. Uma equipe escreve um longo documento de requisitos, o guarda em uma wiki e, em seguida, codifica com base na memória e em threads de chat. A especificação existe, mas não dirige nada. Isso é teatro de documentação, e é pior do que não ter especificação, porque cria falsa confiança.

Um fluxo de trabalho SDD funcional produz uma cadeia de artefatos, cada um revisado antes que a próxima fase comece. Os requisitos reduzem a ambiguidade do produto. O design reduz a ambiguidade técnica. As tarefas reduzem a ambiguidade de execução. A implementação produz código em relação a um alvo conhecido. A validação prova que a cadeia se manteve. Quando qualquer fase revela um erro, você corrige o artefato e reexecuta a partir daquele ponto — e não depois que três mil linhas de desvio tenham chegado ao main.

O fluxo de trabalho é neutro em relação às ferramentas. Você pode executá-lo com arquivos markdown no Git, com o GitHub Spec Kit, com planos do Cursor, com um pacote de habilidades forçado como o Superpowers, ou com um editor de texto simples e um revisor disciplinado. O que importa é a sequência e os pontos de controle de revisão, não a marca das ferramentas.

Fase 1 — Especificar os Requisitos

A fase de especificação responde a qual problema você está resolvendo e como fica o “feito”. Ela evita deliberadamente como construí-lo. No momento em que sua especificação de requisitos diz “usar conjuntos ordenados do Redis”, você parou de especificar e começou a projetar no documento errado. Mantenha a implementação fora dos requisitos. Coloque-a no plano.

Declaração do problema e usuários

Comece com um parágrafo que descreva o problema em linguagem simples. Nomeie os usuários afetados e a situação que torna o problema doloroso. Uma boa declaração de problema permite que um revisor que não esteve na reunião de planejamento decida se uma solução proposta realmente aborda a dor.

Exemplo para um recurso de limitação de taxa de API:

Consumidores de API na camada gratuita podem enviar solicitações ilimitadas, o que causa picos de custo e impacto de vizinho barulhento em inquilinos pagos. Os operadores da plataforma precisam de um limite aplicável por chave sem intervenção manual.

Objetivos, não objetivos e critérios de aceitação

Os objetivos descrevem resultados que você entregará. Os não objetivos descrevem trabalhos adjacentes tentadores que você explicitamente não fará. Juntos, eles limitam a criatividade do agente, o que é essencial quando as ferramentas de IA, de outra forma, “ajudam” a expandir o escopo.

Os critérios de aceitação devem ser precisos o suficiente para que cada um seja mapeado para pelo menos um teste. “O endpoint é seguro” não é um critério de aceitação. “Solicitações não autenticadas recebem HTTP 401” é. Se você não consegue escrever um critério concreto, o requisito ainda é vago demais para ser implementado.

Perguntas em aberto

Liste todas as decisões que ainda não foram resolvidas. Perguntas não claras não são um sinal de falha. Elas são a fase de especificação fazendo seu trabalho. Resolva-as antes de escrever o plano de design, ou você pagará pela ambiguidade em retrabalhos de implementação.

Um modelo mínimo de requisitos:

## Problem
[One paragraph: who hurts, why, and what triggers the pain.]

## Users
- [Primary user role]
- [Secondary user role]

## Goals
1. [Measurable outcome]
2. [Measurable outcome]

## Non-goals
- [Explicitly out of scope]
- [Explicitly out of scope]

## Acceptance criteria
- [ ] [Verifiable behavior]
- [ ] [Verifiable behavior]

## Open questions
- [ ] [Question that blocks planning]

Fase 2 — Planejar o Design

A fase de planejamento traduz a intenção em decisões técnicas. É aqui que os conjuntos ordenados do Redis pertencem, junto com fronteiras de módulos, mudanças de esquema, contratos de API, etapas de migração, restrições de segurança e a estratégia de testes. O plano é derivado da especificação de requisitos mais as restrições existentes do seu projeto — escolhas de pilha, registros de decisão, e convenções armazenadas em arquivos como AGENTS.md ou uma constituição do projeto.

Arquitetura e módulos afetados

Nomeie os módulos, serviços ou pacotes que mudarão e resuma o padrão de integração. Se o recurso cruzar uma fronteira de serviço, documente o contrato em ambos os lados. Agentes alucinam APIs quando os contratos são implícitos. Torná-los explícitos no plano previne endpoints inventados e formatos de resposta errados.

Modelo de dados, contratos de API e migrações

Documente mudanças de esquema, novas tabelas ou campos, requisitos de índice e regras de compatibilidade reversa. Para APIs HTTP, escreva método, caminho, formato da solicitação, formato da resposta e códigos de erro. Para eventos, escreva nomes de tópicos, esquemas de payload e semânticas de entrega. Inclua etapas de migração e notas de rollback quando o modelo de dados mudar.

Segurança, observabilidade e estratégia de testes

As restrições de segurança pertencem ao plano, não como considerações tardias na revisão de código. Anote requisitos de autenticação, regras de autorização, fronteiras de validação de entrada e dados que não devem aparecer nos logs. A observabilidade deve cobrir métricas, logs ou rastros necessários para confirmar que o recurso funciona em produção.

A estratégia de testes conecta-se de volta aos critérios de aceitação. Identifique quais critérios precisam de testes unitários, quais precisam de testes de integração e quais precisam de verificação manual. Se você usa testes unitários em Go ou testes unitários em Python, nomeie os pacotes e arquivos de teste que você espera adicionar. Um plano sem estratégia de testes é um plano que será lançado com lacunas que você descobre em produção.

Fase 3 — Dividir as Tarefas de Implementação

A fase de tarefas decompõe o plano em fatias pequenas o suficiente para serem implementadas, revisadas e validadas independentemente. É isso que torna o desenvolvimento assistido por agentes revisável. Em vez de um diff enorme, você obtém uma sequência de mudanças focadas que cada uma se mapeia de volta para um requisito nomeado.

Dimensionamento de tarefas e dependências

Uma boa tarefa toca em um conjunto limitado de arquivos, é concluída em uma sessão de agente e termina com uma etapa de verificação. As tarefas devem declarar dependências explicitamente. Tarefas de migração são executadas antes do código que lê o novo esquema. Alterações em bibliotecas compartilhadas são executadas antes dos consumidores. Alterações no middleware de autenticação são executadas antes de endpoints que dependem do novo comportamento.

Arquivos, validação e pontos de verificação de revisão

Cada tarefa deve listar os arquivos que provavelmente mudarão, os critérios de aceitação que satisfaz e como validar a conclusão. A validação pode ser um comando de teste, um exemplo de curl ou uma verificação manual descrita em etapas que podem ser copiadas e coladas. Cada tarefa termina em um ponto de verificação de revisão humana. O revisor confirma se o diff corresponde à descrição da tarefa antes que a próxima tarefa comece.

Uma entrada de tarefa mínima:

### Task 3 -- Add rate-limit middleware

**Depends on:** Task 1 (schema), Task 2 (repository)
**Files:** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**Satisfies:** AC-2 (429 over limit), AC-3 (limit headers in response)
**Validate:** `go test ./middleware/...` passes; curl over limit returns 429 with Retry-After
**Review checkpoint:** Confirm middleware runs after auth, before handler

Fique atento a explosões de tarefas geradas. Agentes de IA podem produzir planos de cinquenta tarefas em segundos. A maioria dessas tarefas será redundante ou muito granular para ser revisada eficientemente. Uma lista de tarefas útil para um recurso médio geralmente tem de cinco a quinze itens, não cinquenta.

Fase 4 — Implementar Uma Tarefa de Cada Vez

A implementação é deliberadamente estreita. Escolha uma tarefa, dê ao agente apenas o contexto de que ele precisa para essa tarefa e pare quando a validação passar. Reinícios de contexto entre tarefas são um recurso, não um bug. Eles impedem que premissas anteriores contaminem o trabalho posterior e mantêm diffs revisáveis.

Aplicar restrições da pilha de especificações

O agente de implementação deve ler a especificação de requisitos, o plano de design, a descrição da tarefa atual e as restrições em nível de projeto. As restrições são a seção de maior ROI que a maioria das equipes ignora. Elas dizem ao agente o que não fazer — não refatore módulos não relacionados, não altere assinaturas de API pública fora deste recurso, não introduza novas dependências sem atualizar o plano.

Atualizar o plano quando a realidade difere

A implementação revelará surpresas. Uma biblioteca não suporta o comportamento assumido. Uma migração leva mais tempo do que o esperado. Um caso extremo faltava nos critérios de aceitação. Quando isso acontece, atualize a especificação antes de continuar. Corrija os requisitos ou o plano, obtenha uma revisão rápida e, em seguida, retome a implementação em relação ao artefato corrigido. Código que diverge silenciosamente da especificação é como o desvio se torna permanente.

Fase 5 — Validar em Relação à Especificação

A validação é onde o SDD justifica seu custo. Sem ela, a especificação é um exercício de planejamento. Com ela, a especificação é um contrato que você pode verificar contra o código lançado.

Verificações automatizadas

Execute a suíte completa de testes, lint e verificações de tipo no CI. Conecte esses elementos ao seu pipeline usando padrões da folha de dicas do GitHub Actions se você precisar de um ponto de partida prático. As verificações automatizadas capturam regressões. Elas não capturam recursos errados construídos corretamente, é por isso que a revisão de critérios de aceitação ainda importa.

Critérios de aceitação e revisão manual

Percorra cada critério de aceitação da especificação de requisitos. Marque cada um como satisfeito, falhou ou adiado com justificativa. A revisão manual captura problemas de UX, lacunas de segurança e comportamento errado que os testes perderam porque os testes foram escritos para corresponder a uma especificação defeituosa.

Diff de especificação para código

A etapa final de validação compara a implementação com o plano de design. Os arquivos que mudaram corresponderam aos arquivos que o plano previu? As decisões de arquitetura no código corresponderam às decisões registradas? Arquivos inesperados no diff são um sinal — ou o plano estava incompleto ou o agente se desviou. Ambos merecem atenção antes do merge. Mantendo Especificações, Testes e Código em Sincronia no Desenvolvimento com IA transforma essa revisão de diff pontual em uma tabela de rastreabilidade repetível e um conjunto de verificações de CI, de modo que o desvio seja capturado em cada PR e não apenas quando alguém se lembra de olhar.

Onde os Agentes de IA se Encaixam no Fluxo de Trabalho

Agentes de IA são aceleradores em cada fase, não substitutos para a revisão. O padrão produtivo é rascunhar, revisar, refinar e, em seguida, prosseguir. Peça a um agente que rascunhe a especificação de requisitos a partir de uma descrição do problema e, em seguida, edite a intenção até que objetivos, não objetivos e critérios de aceitação estejam corretos. Peça a um agente que rascunhe o plano de design a partir dos requisitos aprovados e, em seguida, revise as decisões de arquitetura antes que qualquer código exista. Peça a um agente que implemente uma fatia de tarefa de cada vez, com você aprovando cada diff antes que a próxima tarefa comece.

Agentes são especialmente úteis na produção de rascunhos iniciais e testes de boilerplate. Humanos são especialmente úteis na captura de objetivos errados, arquitetura insegura e expansão sutil de escopo. O fluxo de trabalho falha quando qualquer lado é ignorado — quando agentes implementam sem especificações, ou quando humanos escrevem especificações sem nunca validá-las contra o código.

Este artigo de fluxo de trabalho permanece neutro em relação às ferramentas de propósito. Guias de execução específicos de ferramenta — configuração do editor, comandos de barra, configuração de agentes — pertencem ao cluster Ferramentas de Desenvolvimento com IA. O pilar do processo vive aqui sob práticas de documentação porque os artefatos importam mais do que o fornecedor.

Erros Comuns que Matam o Desenvolvimento Orientado por Especificação

Especificações enormes antes de qualquer validação. Um documento de requisitos de trinta páginas escrito antes de um protótipo ou spike é burocracia de cascata, não SDD. Escreva a especificação mínima que remove a ambiguidade para a próxima fase e, em seguida, valide premissas cedo. Nem todo recurso precisa do loop completo de cinco fases — Desenvolvimento Orientado por Especificação vs Vibe Coding explica quando uma estrutura mais leve é suficiente.

Critérios de aceitação vagos. Adjetivos como “rápido”, “limpo” e “fácil de usar” não são critérios de aceitação. Substitua-os por comportamento mensurável. Se você não consegue testá-lo, você não consegue implementá-lo com segurança — especialmente com um agente de IA.

Não objetivos ausentes. Sem não objetivos, agentes expandem o escopo por padrão. Eles adicionam camadas de cache, refatoram módulos vizinhos e introduzem dependências que você não pediu. Não objetivos são como você diz não antecipadamente.

Sem plano de testes na fase de design. Testes escritos apenas após a implementação tendem a confirmar o que foi construído, não o que foi pretendido. O plano deve nomear quais critérios de aceitação se mapeiam para quais tipos de testes antes que o primeiro arquivo de produção mude.

Pular a revisão nas fronteiras de fase. A especificação revisada antes do plano. O plano revisado antes das tarefas. As tarefas revisadas antes da implementação. Cada portão é barato. Corrigir o desvio após um grande merge é caro.

Deixar as tarefas geradas explodirem. Trate uma lista de tarefas gerada por IA com cinquenta itens como um rascunho inicial, não como um cronograma. Merge itens redundantes, divida os que são grandes demais e exclua tarefas que não se mapeiam para um requisito.

O SDD funciona quando cada fase reduz a ambiguidade. Ele falha quando cria burocracia.

Modelos Reutilizáveis

Copie estes para seu repositório e adapte-os. Armazene especificações ao lado da branch do recurso, revise-as em pull requests e mantenha-as no controle de versão para que agentes e humanos leiam a mesma fonte.

Modelo de requisitos

# Feature -- [name]

## Problem
## Users
## Goals
## Non-goals
## Acceptance criteria
## Open questions

Modelo de design

# Design -- [feature name]

## Summary
## Affected modules
## Data model changes
## API contracts
## Migrations
## Security
## Observability
## Test strategy
## Risks and mitigations

Modelo de lista de tarefas

# Tasks -- [feature name]

## Task 1 -- [title]
Depends on:
Files:
Satisfies:
Validate:
Review checkpoint:

## Task 2 -- [title]
...

Checklist de validação

# Validation -- [feature name]

## Automated
- [ ] All tests pass
- [ ] Lint clean
- [ ] Type check clean

## Acceptance criteria
- [ ] AC-1 --
- [ ] AC-2 --

## Spec-to-code
- [ ] Changed files match plan
- [ ] No undocumented architectural changes
- [ ] Spec updated if implementation differed

Conclusão

O desenvolvimento orientado por especificação não é sobre escrever mais documentos. É sobre avançar por especificar, planejar, tarefa, implementar e validar com um portão de revisão em cada etapa. Cada fase deve deixar o próximo ator — humano ou agente — com menos suposições do que a fase anterior.

Comece pequeno. Execute o fluxo de trabalho completo em um recurso de tamanho médio. Mantenha artefatos em markdown no repositório. Atualize a especificação quando a realidade divergir. Valide antes do merge. Quando a cadeia funciona, você obtém menos desvio, diffs menores e revisáveis, e um registro durável de intenção que sobrevive a reinícios de sessão e transferências de equipe.

Quando a cadeia se torna burocracia, corte o escopo — não a revisão. Uma especificação de duas páginas que foi validada vence uma especificação de trinta páginas que ninguém leu.

Links Úteis

• Documentação do GitHub Spec Kit — toolkit de código aberto que implementa um loop semelhante de especificar-planejar-tarefas-implementar
• Superpowers Quickstart: Install, Workflow, and Tryout — um pacote de habilidades instalável que automatiza este mesmo loop de cinco fases com portões de revisão obrigatórios
• Martin Fowler sobre ferramentas de Desenvolvimento Orientado por Especificação — análise de Kiro, Spec Kit e Tessl