Fluxo de Trabalho SDD

O Desenvolvimento Orientado a Specs trata as specs como contratos de desenvolvimento vivos. Cada fase de implementação é controlada por critérios claramente definidos, validados automaticamente em cada transição.

O Ciclo de Vida

clarify → create_spec → DoR check → implement (PLAN.md) → validate → drift detection → done

Cada seta é um portão. Você não pode avançar sem satisfazer a Definição de Pronto da fase anterior.

Fase 1 — Esclarecer

Ferramentas: clarify_requirements, reality_check

Antes de escrever uma única linha de spec, traga as ambiguidades à tona.

Prompt: "Use o specforge para esclarecer requisitos para [funcionalidade] no projeto [id]"

clarify_requirements gera uma lista direcionada de perguntas — limites de escopo, casos extremos, requisitos não funcionais, dependências externas — para que a spec comece com uma intenção clara e sem ambiguidades.

reality_check avalia se os requisitos são viáveis dado o contexto atual do projeto. Ele detecta situações "impossível até sexta-feira" antes que se tornem dívida técnica.

Fase 2 — Criar a Spec

Ferramentas: create_spec, design_schema, define_ui_contract, generate_adr

Prompt: "Crie uma spec para [funcionalidade] no projeto [id]"

create_spec gera um HU.md estruturado com:

Seção	O que contém
User Story	Quem, o quê, por quê
Critérios de Aceitação	Critérios testáveis e sem ambiguidade
Checklist DoR	Portões de Definição de Pronto
Dicas de Schema de Banco de Dados	Tabelas, colunas, relações
Contratos de UI	Contratos de componentes, gerenciamento de estado
Dicas de ADR	Architecture Decision Records
PLAN.md	Plano de execução passo a passo

Quando o projeto tem arquitetura de IA nativa detectada, a spec também gera:

• Orçamentos de latência e cadeias de fallback
• Critérios de versionamento de prompts
• Requisitos de observabilidade de LLM

Fase 3 — Verificação DoR

Ferramentas: check_readiness, detect_contradictions

Antes de começar a implementação, verifique se a spec está realmente pronta.

Prompt: "Verifique se a spec SPEC-003 está pronta para implementação no projeto [id]"

check_readiness avalia:

• Completude dos critérios de aceitação
• Qualidade dos critérios (testável, sem ambiguidade)
• Status de dependências (specs bloqueantes resolvidas?)
• Conformidade com a Constituição

detect_contradictions varre todas as specs em busca de conflitos semânticos — detecta situações onde SPEC-A diz "usuários podem excluir sua conta" e SPEC-B diz "contas são imutáveis."

Fase 4 — Implementar

Ferramentas: generate_execution_plan, package_handoff, generate_tests

Prompt: "Gere um plano de execução para a spec SPEC-003 no projeto [id]"

generate_execution_plan produz um PLAN.md com:

• Etapas do ciclo RED/GREEN/VERIFY
• Etapas paralelizáveis identificadas
• Propriedade de arquivos por etapa
• Esforço estimado por etapa

package_handoff empacota a spec em um pacote estruturado para um agente de IA — objetivo, critérios, lista de arquivos, restrições — pronto para implementação autônoma.

generate_tests produz um plano de testes e stubs de arquivos de teste a partir dos critérios de aceitação da spec.

Fase 5 — Validar

Ferramentas: validate, audit, security_check

Após a implementação, verifique a cobertura:

Prompt: "Valide a spec SPEC-003 contra o código em /caminho/para/src"

validate verifica:

• Quais critérios de aceitação estão cobertos pelo código
• Quais estão faltando ou parcialmente implementados
• Percentual geral de cobertura da spec

audit pontua a implementação de 0 a 100 para:

• Princípios SOLID
• Código limpo
• Conformidade com a arquitetura
• Violações da Constituição

security_check analisa a spec contra o OWASP Top 10 e varre o código em busca de padrões inseguros, gerando uma pontuação de segurança (A–F).

Fase 6 — Detecção de Drift

Ferramentas: detect_drift, reconcile_spec

À medida que os requisitos evoluem, mantenha specs e código alinhados:

Prompt: "Detecte drift na spec SPEC-003 para o projeto [id]"

detect_drift reporta:

• Critérios que não correspondem mais ao código
• Violações da Constituição introduzidas desde a última verificação
• Impacto em cascata: quais outras specs são afetadas pelo drift

Quando o drift é intencional (a spec precisa ser atualizada):

Prompt: "Reconcilie a spec SPEC-003 com as mudanças de implementação no projeto [id]"

reconcile_spec apresenta cada mudança para aprovação individual e verifica a conformidade com a Constituição antes de salvar.

A Constituição do Projeto

A Constituição é um conjunto de princípios arquiteturais imutáveis extraídos do seu CLAUDE.md, .cursorrules ou outros arquivos de configuração de agentes de IA.

Prompt: "Inicialize a constituição para o projeto [id] a partir do CLAUDE.md"

Uma vez definida, a Constituição é automaticamente aplicada em create_spec, audit e detect_drift. Violações são sinalizadas antes de chegarem ao code review.

Transições de Status

Status	Descrição
draft	Spec criada, ainda não pronta
ready	Passou na verificação DoR
in_progress	Implementação iniciada
review	Implementação concluída, aguardando validação
done	Validada e aceita
blocked	Bloqueada por dependência

Prompt: "Atualize o status da spec SPEC-003 para in_progress no projeto [id]"

Cada transição executa a validação DoR/DoD. Você não pode marcar uma spec como done sem atender aos critérios DoD.