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

O Desenvolvimento Orientado por Especificação funciona quando a especificação é um fluxo de trabalho, e não um documento que você arquivará após a reunião de abertura. 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 — modifique o código de produção.

Se você não sabe o que é SDD em termos conceituais, 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 de verdade. Este artigo no cluster de documentação de 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 o 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, armazena-o 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 da documentação, e é pior do que não ter especificação, porque cria uma confiança falsa.

Um fluxo de trabalho SDD funcional produz uma cadeia de artefatos, cada um revisado antes que a próxima fase comece. Requisitos reduzem a ambiguidade do produto. Design reduz a ambiguidade técnica. Tarefas reduzem a ambiguidade de execução. Implementação produz código contra um alvo conhecido. Validação prova que a cadeia se manteve. Quando qualquer fase revela um erro, você corrige o artefato e executa novamente a partir daquele ponto — não depois de três mil linhas de desvio terem entrado na main.

O fluxo de trabalho é agnóstico quanto à ferramenta. Você pode executá-lo com arquivos markdown em Git, com GitHub Spec Kit, com uma CLI centrada em mudanças mais leve como OpenSpec, com planos do Cursor, com um pacote de habilidades forçado como Superpowers, ou com um editor de texto simples e um revisor disciplinado. O que importa é a sequência e os portões de revisão, não a marca da ferramenta.

Fase 1 – Especificar os Requisitos

A fase de especificação responde ao problema que você está resolvendo e ao que significa “concluído”. Ela evita deliberadamente 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 fazer design 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 declara 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 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 requisições ilimitadas, o que causa picos de custo e impacto de vizinhos ruidosos nos inquilinos pagos. Operadores da plataforma precisam de um limite executável por chave sem intervenção manual.

Objetivos, não objetivos e critérios de aceite

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

Os critérios de aceite devem ser precisos o suficiente para que cada um se mapeie para pelo menos um teste. “O endpoint é seguro” não é um critério de aceite. “Requisições não autenticadas recebem HTTP 401” é. Se você não puder escrever um critério concreto, o requisito ainda é vago demais para implementar.

Questões em aberto

Liste toda decisão que ainda não foi resolvida. Questões não claras não são um sinal de falha. São a fase de especificação fazendo seu trabalho. Resolva-os antes de escrever o plano de design, ou você pagará pela ambiguidade no retrabalho da implementação.

Um modelo mínimo de requisitos:

## Problema
[Uma parágrafo: quem sofre, por quê, e o que causa 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 aceite
- [ ] [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 intenção em decisões técnicas. É aqui que 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 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 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, forma da requisição, forma da resposta e códigos de erro. Para eventos, escreva nomes de tópicos, esquemas de carga 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

Restrições de segurança pertencem no plano, não como pensamentos posteriores 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 em logs. Observabilidade deve cobrir métricas, logs ou traços necessários para confirmar que o recurso funciona em produção.

A estratégia de teste conecta de volta aos critérios de aceite. 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 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 implementar, revisar e validar independentemente. É isso que torna o desenvolvimento assistido por agente 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 executam antes do código que lê o novo esquema. Mudanças em bibliotecas compartilhadas executam antes dos consumidores. Mudanças em middleware de autenticação executam antes de endpoints que dependem do novo comportamento.

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

Cada tarefa deve listar os arquivos que provavelmente mudarão, os critérios de aceite 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 revisão humana. O revisor confirma que o diff corresponde à descrição da tarefa antes que a próxima tarefa comece.

Uma entrada mínima de tarefa:

### 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 revisão:** Confirmar que o middleware executa após a autenticação, antes do handler

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 granular demais para revisar eficientemente. Uma lista de tarefas útil para um recurso médio muitas vezes 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 que ele precisa para aquela tarefa, e pare quando a validação passar. Reinícios de contexto entre tarefas são um recurso, não um bug. Eles previnem que suposições anteriores poluam o trabalho posterior e mantêm 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 restrições de nível do projeto. Restrições são a seção de maior ROI que a maioria das equipes pule. Elas dizem ao agente o que não fazer – não refactorizar módulos não relacionados, não mudar assinaturas de API pública fora deste recurso, não introduzir 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 limite faltava nos critérios de aceite. Quando isso acontecer, atualize a especificação antes de continuar. Corrija os requisitos ou o plano, obtenha uma revisão rápida, então retome a implementação contra o artefato corrigido. Código que diverge silenciosamente da especificação é como o desvio se torna permanente.

Fase 5 – Validar Contra a Especificação

A validação é onde o SDD vale a pena. 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 tipos no CI. Conecte esses ao seu pipeline usando padrões da folha de dicas do GitHub Actions se você precisar de um ponto de partida prático. Verificações automatizadas capturam regressões. Elas não capturam recursos errados construídos corretamente, por isso a revisão de critérios de aceite ainda importa.

Critérios de aceite e revisão manual

Percorra cada critério de aceite 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 falha.

Diff da especificação para o 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 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 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, para que o desvio seja capturado em cada PR, e não apenas quando alguém se lembra de olhar.

Onde 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 então prosseguir. Peça a um agente para rascunhar a especificação de requisitos a partir de uma descrição do problema, então edite a intenção até que objetivos, não objetivos e critérios de aceite estejam corretos. Peça a um agente para rascunhar o plano de design a partir dos requisitos aprovados, então revise 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.

Agentes são especialmente úteis para produzir rascunhos iniciais e testes boilerplate. Humanos são especialmente úteis para capturar objetivos errados, arquitetura insegura e expansão sutil de escopo. 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 agnóstico quanto à ferramenta por propósito. Guias de execução específicos da ferramenta – configuração de editor, comandos slash, configuração de agente – pertencem sob o cluster de Ferramentas de Desenvolvimento de 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 waterfall, não SDD. Escreva a especificação mínima que remove a ambiguidade para a próxima fase, então valide suposições cedo. Nem todo recurso precisa do loop completo de cinco fases – Desenvolvimento Orientado por Especificação vs Coding Vibe explica quando uma estrutura mais leve é suficiente.

Critérios de aceite vagos. Adjetivos como “rápido”, “limpo” e “fácil de usar” não são critérios de aceite. Substitua-os por comportamento mensurável. Se você não puder testá-lo, você não pode implementá-lo confiavelmente – especialmente com um agente de IA.

Falta de não objetivos. Sem não objetivos, agentes expandem o escopo por padrão. Eles adicionam camadas de cache, refactorizam 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 aceite se mapeiam para quais tipos de testes antes que o primeiro arquivo de produção mude.

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

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

Deletando investigações rejeitadas em vez de registrar por quê. Quando a revisão da fase 2 conclui que uma direção não vale a pena construir, o reflexo é deletar a especificação e seguir em frente. Isso apaga o raciocínio, e a mesma ideia ressurge no próximo trimestre, investigada do zero por quem quer que — humano ou agente — a encontre novamente. Registrar a rejeição com o mesmo rigor que uma decisão aceita é barato por comparação; Propostas Rejeitadas no OpenSpec: Uma Convenção de Memória de Decisão percorre uma maneira concreta de fazer isso, incluindo a instrução que faz um agente buscar decisões anteriores antes de propor novamente.

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

Modelos Reutilizáveis

Copie esses para o seu repositório e adapte-os. Armazene especificações junto com a branch do recurso, revise-as em pull requests e mantenha-as em 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 aceite
## Questões em aberto

Modelo de design

# Design -- [nome do recurso]

## Resumo
## Módulos afetados
## Mudanças 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 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 aceite
- [ ] AC-1 --
- [ ] AC-2 --

## Especificação para código
- [ ] Arquivos alterados correspondem ao plano
- [ ] Sem mudanças arquiteturais não documentadas
- [ ] Especificação atualizada se a implementação diferiu

Conclusã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ção do que a fase anterior.

Comece pequeno. Execute o fluxo de trabalho completo em um recurso médio de tamanho. 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 revisáveis menores e um registro durável de intenção que sobrevive a reinícios de sessão e trocas 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 – kit de ferramentas de código aberto que implementa um loop similar de especificar-planejar-tarefas-implementar
• Início Rápido do OpenSpec: Instalação, Fluxo de Trabalho e Armadilhas Comuns – uma CLI mais leve, centrada em mudanças, que executa este mesmo loop como explorar-propor-aplicar-arquivar
• Propostas Rejeitadas no OpenSpec: Uma Convenção de Memória de Decisão – registrando uma decisão rejeitada da fase 2 para que não seja reinvestigada do zero
• Início Rápido do Superpowers: Instalação, Fluxo de Trabalho e Teste – 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