Fluxo de Trabalho de Desenvolvimento Orientado por Especificações: Dos Requisitos ao Código

O Desenvolvimento Dirigido por Especificação (SDD) funciona quando a especificação é um fluxo de trabalho, não um documento que você arquiva após o início. O objetivo não é produzir um grande documento de requisitos do produto.

O objetivo é percorrer uma sequência de artefatos revisáveis que reduzem a ambiguidade antes que qualquer pessoa – humano ou agente de IA – altere o código de produção.

Se você não sabe o que é SDD conceitualmente, comece com O que é Desenvolvimento Dirigido 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 Aplicação é 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 em seu repositório hoje.

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

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

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 contra um alvo conhecido. A validação prova que a cadeia se manteve. Quando qualquer fase revela um erro, você corrige o artefato e reinicia a partir daquele ponto – não depois que três mil linhas de deriva tenham sido aplicadas 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, 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 ao problema que você está resolvendo e ao que “concluído” significa. 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 enuncia o problema em linguagem clara. 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 no nível gratuito podem enviar solicitações ilimitadas, o que causa picos de custo e impacto de vizinho barulhento em inquilinos pagos. 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 os 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, caso contrário, “ajudam” a expandir o escopo.

Os critérios de aceitação devem ser precisos o suficiente para que cada um mapeie 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 puder escrever um critério concreto, o requisito ainda é muito vago para ser implementado.

Questões em aberto

Liste todas as decisões que ainda não foram resolvidas. Questões não claras não são 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 no retrabalho de implementação.

Um modelo mínimo de requisitos:

## Problema
[Um parágrafo: quem sofre, por quê e o que desencadeia a dor.]

## Usuários
- [Papel do usuário principal]
- [Papel do usuário secundário]

## Objetivos
1. [Resultado mensurável]
2. [Resultado mensurável]

## Não-objetivos
- [Explicitamente fora do escopo]
- [Explicitamente fora do escopo]

## Critérios de aceitação
- [ ] [Comportamento verificável]
- [ ] [Comportamento verificável]

## Questões em aberto
- [ ] [Questão que bloqueia o planejamento]

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, juntamente com limites de módulos, alterações de esquema, contratos de API, etapas de migração, restrições de segurança e a estratégia de teste. O plano é derivado da especificação de requisitos mais as restrições existentes do seu projeto – escolhas de stack, 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 serão alterados e resuma o padrão de integração. Se o recurso cruzar um limite de serviço, documente o contrato em ambos os lados. Os agentes alucinam APIs quando os contratos são implícitos. Torná-los explícitos no plano impede endpoints inventados e formatos de resposta incorretos.

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

Documente alterações de esquema, novas tabelas ou campos, requisitos de índice e regras de compatibilidade retroativa. Para APIs HTTP, escreva método, caminho, formato de solicitação, formato de 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 teste

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

A estratégia de teste conecta-se 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ê usar testes unitários em Go ou testes unitários em Python, nomeie os pacotes e arquivos de teste que espera adicionar. Um plano sem estratégia de teste é um plano que será entregue com lacunas que você descobrirá em produção.

Fase 3 – Decompor 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 agente revisável. Em vez de uma diff enorme, você obtém uma sequência de mudanças focadas que mapeiam de volta a 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 dos endpoints que dependem do novo comportamento.

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

Cada tarefa deve listar os arquivos provavelmente alterados, 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 copiáveis. Cada tarefa termina em um ponto de verificação de revisão humana. O revisor confirma que a diff corresponde à descrição da tarefa antes que a próxima tarefa comece.

Uma entrada de tarefa mínima:

### Tarefa 3 -- Adicionar middleware de limitação de taxa

**Depende de:** Tarefa 1 (esquema), Tarefa 2 (repositório)
**Arquivos:** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**Satisfaz:** AC-2 (429 acima do limite), AC-3 (cabeçalhos de limite na resposta)
**Validar:** `go test ./middleware/...` passa; curl acima do limite retorna 429 com Retry-After
**Ponto de verificação de revisão:** Confirmar que o middleware é executado após a autenticação, antes do manipulador

Acompanhe 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 de tamanho médio geralmente tem 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 necessário para aquela tarefa e pare quando a validação passar. As reinicializações de contexto entre tarefas são uma funcionalidade, não um bug. Eles impedem que suposições anteriores contaminem o trabalho posterior e mantêm as diffs revisáveis.

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

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 de nível de projeto. As restrições são a seção de maior retorno sobre investimento 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 diferir

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 de borda estava ausente 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 contra o artefato corrigido. O código que se desvia silenciosamente da especificação é como a deriva se torna permanente.

Fase 5 – Validar Contra a 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 entregue.

Verificações automatizadas

Execute a suíte completa de testes, lint e verificações de tipo no CI. Conecte-os ao seu pipeline usando padrões do cheat sheet do GitHub Actions se precisar de um ponto de partida prático. As verificações automatizadas pegam regressões. Elas não pegam recursos errados construídos corretamente, é por isso que a revisão dos 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 incorreto que os testes perderam porque os testes foram escritos para corresponder a uma especificação falha.

Diff de especificação para código

A etapa final de validação compara a implementação contra o plano de design. Os arquivos alterados corresponderam aos arquivos que o plano previu? As decisões de arquitetura no código corresponderam às decisões registradas? Arquivos inesperados na diff são um sinal – ou o plano estava incompleto ou o agente vagueou. Ambos merecem atenção antes do merge.

Onde os Agentes de IA se Encaixam no Fluxo de Trabalho

Os agentes de IA são aceleradores em cada fase, não substitutos para revisão. O padrão produtivo é rascunho, revisão, refinamento e, em seguida, prosseguir. Peça a um agente para rascunhar a especificação de requisitos a partir de uma descrição do problema, edite a intenção até que os objetivos, não-objetivos e critérios de aceitação estejam corretos. Peça a um agente para rascunhar 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 para implementar uma fatia de tarefa de cada vez, com você aprovando cada diff antes que a próxima tarefa comece.

Os agentes são especialmente úteis na produção de rascunhos iniciais e testes de boilerplate. Os humanos são especialmente úteis na captura de objetivos errados, arquitetura insegura e expansão de escopo sutil. 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 propositadamente. Guias de execução específicos de ferramenta – configuração do editor, comandos slash, configuração do agente – pertencem ao cluster Ferramentas de Desenvolvimento de IA. O pilar do processo vive aqui nas práticas de documentação porque os artefatos importam mais do que o fornecedor.

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

Especificações gigantes antes de qualquer validação. Um documento de requisitos de trinta páginas escrito antes de um protótipo ou spike é burocracia em cascata, não SDD. Escreva a especificação mínima que remove a ambiguidade para a próxima fase e, em seguida, valide as suposições cedo. Nem todo recurso precisa do ciclo completo de cinco fases – Desenvolvimento Dirigido 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 “amigável ao usuário” não são critérios de aceitação. Substitua-os por comportamento mensurável. Se você não pode testá-lo, não pode implementá-lo de forma confiável – especialmente com um agente de IA.

Não-objetivos faltando. Sem não-objetivos, os 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. Os não-objetivos são como você diz não com antecedência.

Nenhum plano de teste 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 mapeiam para quais tipos de teste antes que o primeiro arquivo de produção seja alterado.

Pular a revisão nos limites de fase. A especificação revisada antes do plano. O plano revisado antes das tarefas. Tarefas revisadas antes da implementação. Cada porta é barata. Corrigir a deriva após um merge grande é caro.

Permitir que as tarefas geradas explodam. Trate uma lista de tarefas gerada por IA com cinquenta itens como um rascunho, não como um cronograma. Merge itens redundantes, divida os excessivamente grandes e exclua tarefas que não 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 de 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

# Recurso -- [nome]

## Problema
## Usuários
## Objetivos
## Não-objetivos
## Critérios de aceitação
## Questões em aberto

Modelo de design

# Design -- [nome do recurso]

## Resumo
## Módulos afetados
## Alterações no modelo de dados
## Contratos de API
## Migrações
## Segurança
## Observabilidade
## Estratégia de teste
## Riscos e mitigações

Modelo de lista de tarefas

# Tarefas -- [nome do recurso]

## Tarefa 1 -- [título]
Depende de:
Arquivos:
Satisfaz:
Validar:
Ponto de verificação de revisão:

## Tarefa 2 -- [título]
...

Checklist de validação

# Validação -- [nome do recurso]

## Automatizado
- [ ] Todos os testes passam
- [ ] Lint limpo
- [ ] Verificação de tipo limpa

## Critérios de aceitação
- [ ] AC-1 --
- [ ] AC-2 --

## Especificação para código
- [ ] Arquivos alterados correspondem ao plano
- [ ] Nenhuma alteração arquitetural não documentada
- [ ] Especificação atualizada se a implementação diferiu

Conclusão

O desenvolvimento dirigido por especificação não é sobre escrever mais documentos. É sobre percorrer especificar, planejar, tarefa, implementar e validar com um ponto de controle de revisão em cada etapa. Cada fase deve deixar o próximo ator – humano ou agente – com menos adivinhação 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 deriva, diffs revisáveis menores e um registro durável de intenção que sobrevive a reinicializações de sessão e trocas de equipe.

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

Links Úteis

• Documentação do GitHub Spec Kit – kit de ferramentas de código aberto que implementa um loop semelhante de especificar-planejar-tarefas-implementar
• Martin Fowler sobre ferramentas de Desenvolvimento Dirigido por Especificação – análise de Kiro, Spec Kit e Tessl