Pipeline Spec-Driven · Da Ideia à Produção

Isto não é "uma sequência de chamadas de IA". É uma máquina de estados durável — onde a unidade que percorre o pipeline é uma feature, e cada etapa a transforma de um artefato no próximo.

Por que essa distinção decide tudo? Porque você pediu checkpoints em pontos críticos. Quando o agente gera o PRD e espera a aprovação de um PM, esse PM pode levar três dias para responder. Um script comum estoura, perde o estado e obriga a refazer tudo. Uma máquina de estados durável persiste o estado da feature, pausa indefinidamente no portão e só retoma quando recebe o sinal de aprovação. É a diferença entre o que funciona na demo e o que sobrevive ao mundo real.

00 · Antes da primeira feature

## Adapte a pipeline ao projeto

Para funcionar bem em qualquer repositório, a pipeline começa entendendo onde está: stack, comandos, CI, paths, sistemas, riscos e regras de quando aumentar o rigor.

Config

### sdd.config.yaml

Declara stack, sistemas, paths, comandos, adapters, artifact store e políticas de qualidade. É o contrato local que evita o agente inventar como o projeto funciona.

- Paths de código, testes, docs e migrations
- Comandos de lint, typecheck, test e build
- Fallback em docs/<orquestracao>
- Políticas de risco e checkpoints

Discovery

### Project Discovery

Mapeia o codebase real antes da primeira feature brownfield: arquitetura, padrões, CI, comandos confiáveis e riscos recorrentes do projeto.

- Onboarding técnico do repositório
- Memória inicial para próximos agentes
- Regras locais de execução e review

Risco

### Risk Classification

Classifica cada feature antes da Ideia virar plano. O risco decide Refinement, Agent Teams, reviewers, deploy checkpoint e evidências mínimas.

- Low, medium, high ou critical
- Security, data, migration, infra e performance
- Gates proporcionais ao impacto

01 · O fluxo

## As oito etapas

Clique em qualquer etapa para abrir seu dossiê: o que ela faz, qual sistema é o dono do artefato, qual agente atua, qual arquivo local é salvo e se existe um portão humano. O Refinamento é opcional, mas aparece formalmente no trilho para não sumir do planejamento.

02 · O contrato executável

## O BDD vive dentro do SDD

BDD e SDD não competem. O SDD é o continente; o BDD é a camada de comportamento da spec — a parte que diz, de forma testável, o que conta como "certo". É ela que dá dentes ao Review.

### As camadas de uma spec

A spec · o contrato
História de usuário
por quê — As a… I want…
camada BDD
Comportamento + critérios de aceite
o quê, testável · executa como portão de validação
Arquitetura (TechSpec)
como — decisões e riscos
Testes + código gerados
a saída, validável pela camada de cima

### Duas notações, complementares

O EARS afirma a regra de forma rigorosa; o Gherkin dá o exemplo concreto que a prova. A mesma exigência, por dois ângulos:

GHERKIN o exemplo executável

    # roda no CI via Cucumber e família
    Funcionalidade: Bloqueio por tentativas
      Cenário: Conta bloqueia após 3 erros
        Dado um usuário com login válido
        Quando ele erra a senha 3 vezes
        Então a conta é bloqueada por 15 min
        E um e-mail de alerta é enviado

EARS a regra rigorosa

    # requisito inequívoco na spec
    Quando o usuário erra a senha 3
    vezes consecutivas, o sistema
    DEVE bloquear a conta por 15 min
    e DEVE enviar um e-mail de
    alerta ao titular.

EARS diz a regra ⇄ Gherkin prova com o exemplo

### A espinha de comportamento, etapa por etapa

O comportamento não fica numa etapa só — ele atravessa o pipeline inteiro, do nascimento da história até virar documentação viva.

01 02 03 04 05 06 07 08
ETAPA 02

#### Histórias nascem

As histórias de usuário são o ponto de partida do comportamento.

ETAPA 04

#### Critérios escritos

Gherkin/EARS no campo de Critérios de Aceite da story no Jira — apps como Xray e Zephyr guardam isso nativamente.

ETAPA 05

#### Pronto para engenharia

O Refinement consolida subtasks, DoD, estimativas e flags sem duplicar a Tech Spec.

ETAPA 06 · o ganho

#### Portão executável

O Bitbucket Pipelines roda os cenários. Verde = o comportamento bate com a spec.

ETAPA 07

#### Review contra spec

A revisão compara código, testes e evidências com os critérios aprovados antes do merge.

ETAPA 08

#### Documentação viva

Cenários executáveis e decisões aprovadas alimentam a memória comportamental.

A IA gera código vulnerável em 10% a 42% dos casos. O que pega isso de forma determinística não é mais IA revisando IA — são critérios de aceite executáveis.

Sem eles, o Review é uma revisão mole e infinita, sem critério objetivo de "pronto". Com Gherkin/EARS, ele ganha um portão binário de passa/não-passa ancorado em comportamento definido pelo negócio — e o checkpoint humano do merge passa a decidir com evidência, não com opinião.

A regra que torna isso seguro O comportamento precisa cruzar um checkpoint humano antes de o agente codar. Senão a mesma IA escreve o cenário, escreve o código e confere a própria prova — e o "verde" não significa nada. O antídoto vem do próprio BDD, dos Três Amigos (negócio, dev e QA): humanos aprovam o comportamento a montante, o agente implementa a jusante. Autoria do comportamento separada da autoria do código.
03 · Onde cada coisa mora

## Divida por artefato, não por etapa

O instinto é dividir por etapa ("1 a 4 é Jira"). O jeito mais limpo é dividir por tipo de artefato e deixar cada um no sistema onde os humanos naturalmente colaboram com ele — mantendo um fallback local no repositório.

Regra de ouro Mantenha cada artefato no sistema onde os humanos colaboram com ele — e nunca duplique entre sistemas externos, apenas conecte com links. Se a integração ainda não existe, o arquivo em `docs/<orquestracao>` é a fonte canônica.

### Confluence

Conteúdo · documentos vivos

O lar do que é texto rico: PRD, TechSpec, decision records. Versionamento, comentários, diagramas — tudo o que humanos leem e discutem.

- O documento do PRD
- A TechSpec e seus diagramas
- A memória legível por humanos

### Jira

Estado · itens de trabalho

O dono do estado: o épico que rastreia o PRD, as tasks decompostas, e o status que avança conforme o trabalho caminha.

- O épico (rastreia o PRD)
- Uma issue por task
- O status: To Do → In Review → Done

### Bitbucket

Código · execução e review

Onde o código vive e a entrega acontece: branches, pull requests e os portões de qualidade via Pipelines (CI).

- Branch e Pull Request
- Code review e merge
- CI / Pipelines como gate

### docs/<orquestração>

Fallback · artefatos locais

O mínimo obrigatório para qualquer projeto: uma pasta por orquestração com todos os artefatos aprovados/registrados e o mapa de rastreabilidade.

- 00 a 08 por etapa
- traceability-map.yaml
- Fonte canônica quando não há Jira/Confluence

É por isso que o PRD e a TechSpec tocam dois sistemas cada um: o documento mora no Confluence, o item que o rastreia mora no Jira, ligados por um link. O store local guarda a cópia mínima auditável quando essa cadeia ainda não está completa.

04 · A anatomia

## Seis componentes

Pense numa linha de montagem: o produto avança de estação em estação sendo transformado, inspetores assinam embaixo, e algo controla a esteira e lembra onde cada peça está. Seu sistema tem seis peças análogas. Clique para abrir cada uma.

05 · O plano de controle

## Subagents, Agent Teams e automações

A pipeline não precisa escolher entre “um agente faz tudo” e “vários agentes brigam pelo mesmo arquivo”. O controle define quando delegar, quando paralelizar e quando pausar para um evento externo.

Subagents

### O caminho padrão

Cada etapa continua tendo um dono claro: PRD, TechSpec, Tasks, Refinement, Execution, Review e Memory. Subagents são o encaixe natural para papéis especializados com contexto e saída previsíveis.

- Um artefato principal por etapa
- Prompts e skills específicos por papel
- Menor risco de conflito entre agentes

Agent Teams

### Paralelo quando há separação real

Use equipes quando a tarefa admite lanes independentes: arquitetura, segurança, contratos, testes, frontend, backend e performance. O agente principal sintetiza, não delega a decisão final.

- TechSpec com revisores especialistas
- Execução por ownership de arquivos
- Review paralelo antes do gate de merge

Automations

### Eventos, hooks e tarefas agendadas

Automação não é uma nona etapa. É o plano de fundo que acorda a pipeline, aplica guardrails locais, registra trilha de auditoria e retoma workflows quando Jira, Slack ou Bitbucket emitem sinais.

- Webhooks e Channels para eventos reais
- Hooks para validação determinística local
- Scheduled tasks só para varreduras temporárias

Regra de roteamento

Subagent por padrão. Agent Team apenas quando houver trabalho realmente paralelo, ownership explícito e contrato de saída por lane. Hooks bloqueiam violações locais; checkpoints humanos continuam decidindo PRD, TechSpec, Refinement de risco, merge e deploy.

architecture security data contracts QA frontend backend tests performance
06 · O ponto crítico

## Como um checkpoint funciona, por dentro

O segredo de "autônomo com checkpoints" está aqui: o workflow durável precisa pausar e esperar um evento externo que pode demorar dias.

1
Chega ao gate
O workflow termina a etapa e alcança um portão crítico.
2
Persiste o estado
Salva tudo em docs/<orquestracao> e no sistema externo quando existir.
3
Posta o artefato
Manda o PRD/PR para revisão com o link local e externo.
4
Aguarda o sinal
Pausa indefinidamente. Sem timeout, sem desperdício.
5
Sinal chega
Um webhook (transição no Jira ou clique no Slack) avisa.
6
Retoma
O workflow continua exatamente de onde parou.

Os portões que eu marcaria como críticos: depois do PRD ("é isto que queremos construir?"), depois do TechSpec ("a arquitetura faz sentido?"), depois do Refinement quando houver risco, flags, migração ou dependência externa, sempre antes do merge (a aprovação do review) e antes do deploy. A decomposição em tasks pode rodar automática, com conferência por amostragem.

07 · Honestidade de engenharia

## Construir versus montar

Para uso interno, uma fração enorme disto já existe pronta. A pergunta certa não é "como construo as 8 etapas do zero?", e sim "qual é a cola que eu preciso construir?".

### JÁ EXISTE Monte a partir disto

- Rovo gera PRDs no Confluencee os quebra em épicos e issues no Jira
- Rovo Dev transforma issues em códigoo agente de execução nativo da plataforma
- Bitbucket: code review + Pipelinesos portões de CI já estão prontos
- GitHub Spec Kit dá o scaffoldingmodel-agnostic, funciona com o Claude Code

### A COLA Isto você constrói

- O orquestrador durávelo cérebro com os portões — o calcanhar de Aquiles de quem improvisa
- A camada de memóriao que torna os agentes bons no seu codebase específico
- O artifact store localdocs/<orquestracao> como fallback universal de artefatos aprovados
- A lógica de rastreabilidadeos links que ligam código ↔ task ↔ spec ↔ PRD ↔ ideia

Reinventar um agente gerador de PRD, quando o Rovo já faz isso dentro do seu próprio Confluence, seria desperdício. Monte o que existe; construa só o que é seu.

08 · O caminho

## Em fases, sem ferver o oceano

"Da ideia à produção" é um escopo gigante. Você quer autonomia com checkpoints como destino, não como ponto de partida — então construa em fases que vão conquistando confiança.

Fase 0 · fundação

### Conexões de leitura

Prove o básico via MCP/API: consigo ler uma issue do Jira, um repositório do Bitbucket e uma página do Confluence? Nada mais.

risco: nenhum
Fase 1 · planejamento

### Copiloto de planejamento (etapas 2–5)

PRD → TechSpec → Tasks → Refinement, com aprovação humana nos gates críticos. Nenhum código é escrito, nenhuma produção é tocada — risco zero e valor imediato no dia um.

risco: baixo · valor: alto
Fase 2 · execução

### Execução + Review (etapas 6–7) em sandbox

Ligue os agentes de código num repositório de testes, com tasks pequenas e bem-escopadas. Aprove todo PR no começo — aqui é onde o risco real entra.

risco: médio · ambiente isolado
Fase 3 · loop fechado

### Memória (etapa 8)

Persista o contexto, as decisões e os learnings para que o próximo ciclo já nasça mais inteligente. É o que fecha o ciclo e melhora tudo o que veio antes.

habilita ganhos compostos
Fase 4 · autonomia conquistada

### Relaxe os checkpoints

Mova os portões de "todo passo" para "só os críticos", conforme a confiança se acumula. É assim que você conquista a autonomia em vez de declará-la no dia um.

o destino, não a largada
o princípio que amarra tudo

A spec é o contrato.
A rastreabilidade é o produto.

Quando o código diverge da spec, isso é um defeito a ser pego no review — não um detalhe. E quando cada artefato aponta de volta para sua origem, você ganha um sistema auditável que alimenta a própria memória.