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

O Desenvolvimento Orientado 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 do projeto. 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 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 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 para seu repositório hoje.

O 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, 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 impulsiona nada. Isso é teatro da 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 foram aplicadas na branch principal.

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 da ferramenta.

Fase 1 – Especificar os Requisitos

A fase de especificação responde qual problema você está resolvendo e como fica definido o “pronto”. Ela evita deliberadamente o “como” construí-lo. No momento em que sua especificação de requisitos diz “use 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 estava 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 nos 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 atraentes 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” expandindo 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 estão resolvidas. Questões 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 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 primário]
- [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 pertencem os conjuntos ordenados do Redis, 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 previne 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 o método, caminho, formato da solicitação, formato da resposta e códigos de erro. Para eventos, escreva os nomes dos tópicos, esquemas de payload e semânticas de entrega. Inclua etapas de migração e notas de retorno 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 abranger métricas, logs ou rastreamentos necessários para confirmar que o recurso funciona em produção.

A estratégia de teste 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ê usar 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 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 diferença (diff) enorme, você obtém uma sequência de alterações focadas que cada uma 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 em 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 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 copiáveis. Cada tarefa termina em um ponto de verificação de revisão humana. O revisor confirma que a diferença 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

Cuidado com 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 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 um recurso, não um bug. Eles impedem que suposições anteriores contaminem o trabalho posterior e mantêm as diferenças 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 com o maior retorno sobre investimento que a maioria das equipes pula. 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 faltando 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 isso, a especificação é um exercício de planejamento. Com isso, a especificação é um contrato que você pode verificar contra o código entregue.

Verificações automatizadas

Execute o conjunto completo de testes, lint e verificações de tipo no CI. Conecte-os ao seu pipeline usando padrões do resumo de 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 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.

Diferença de especificação para código

A etapa final de validação compara a implementação contra o plano de design. Os arquivos que mudaram corresponderam aos arquivos que o plano previu? As decisões arquitetônicas no código corresponderam às decisões registradas? Arquivos inesperados na diferença são um sinal — ou o plano estava incompleto ou o agente vagueou. Ambos merecem atenção antes da mesclagem. Manter Especificações, Testes e Código Sincronizados no Desenvolvimento com IA transforma essa revisão de diferença única em uma tabela de rastreio repetível e um conjunto de verificações de CI, para que a deriva seja capturada em cada PR, em vez de apenas quando alguém se lembra de olhar.

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 a revisão. O padrão produtivo é rascunhar, revisar, refinar e, em seguida, prosseguir. Peça a um agente para rascunhar a especificação de requisitos a partir de uma descrição do problema, depois 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, depois 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 diferença antes que a próxima tarefa comece.

Os 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 de escopo sutil. O fluxo de trabalho falha quando qualquer lado é pulado — 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 propositalmente. Guias de execução específicos de ferramentas — configuração de editor, comandos de barra, configuração de agente — pertencem ao cluster Ferramentas de Desenvolvimento de IA. O pilar de 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 é papelada em cascata, não SDD. Escreva a especificação mínima que remove a ambiguidade para a próxima fase, depois valide as suposições 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 “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 antecipadamente.

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 mude.

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 uma mesclagem grande é caro.

Deixar as tarefas geradas explodirem. Trate uma lista de tarefas gerada por IA com cinquenta itens como um rascunho, não como uma agenda. Mesclar itens redundantes, dividir os excessivamente grandes e excluir tarefas que não mapeiam para um requisito.

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

Modelos Reutilizáveis

Copie estes para seu repositório e adapte-os. Armazene especificações ao lado da branch de funcionalidade, 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]
...

Lista de verificação 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 arquitetônica não documentada
- [ ] Especificação atualizada se a implementação diferiu

Conclusão

O desenvolvimento orientado por especificação não se trata de escrever mais documentos. Trata-se de avançar por especificar, planejar, tarefas, implementar e validar com um ponto de verificaçã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 da mesclagem. Quando a cadeia funciona, você obtém menos deriva, diferenças revisáveis menores e um registro durável de intenção que sobrevive a reinicializações de sessão e transferências de equipe.

Quando a cadeia se torna papelada, corte 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 – toolkit de código aberto que implementa um loop similar de especificar-planejar-tarefas-implementar
• Martin Fowler sobre ferramentas de Desenvolvimento Orientado por Especificação – análise de Kiro, Spec Kit e Tessl