Um pre-flight de projeto e oito etapas que transformam uma frase em linguagem natural em código revisado em produção — com Refinamento quando a feature pede grooming, humanos assinando embaixo nos pontos que importam, e artefatos salvos em docs/<orquestracao> quando as integrações ainda não estão completas.
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.
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.
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.
Mapeia o codebase real antes da primeira feature brownfield: arquitetura, padrões, CI, comandos confiáveis e riscos recorrentes do projeto.
Classifica cada feature antes da Ideia virar plano. O risco decide Refinement, Agent Teams, reviewers, deploy checkpoint e evidências mínimas.
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.
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.
O EARS afirma a regra de forma rigorosa; o Gherkin dá o exemplo concreto que a prova. A mesma exigência, por dois ângulos:
# 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
# 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
O comportamento não fica numa etapa só — ele atravessa o pipeline inteiro, do nascimento da história até virar documentação viva.
As histórias de usuário são o ponto de partida do comportamento.
Gherkin/EARS no campo de Critérios de Aceite da story no Jira — apps como Xray e Zephyr guardam isso nativamente.
O Refinement consolida subtasks, DoD, estimativas e flags sem duplicar a Tech Spec.
O Bitbucket Pipelines roda os cenários. Verde = o comportamento bate com a spec.
A revisão compara código, testes e evidências com os critérios aprovados antes do merge.
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.
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.
docs/<orquestracao> é a fonte canônica.
O lar do que é texto rico: PRD, TechSpec, decision records. Versionamento, comentários, diagramas — tudo o que humanos leem e discutem.
O dono do estado: o épico que rastreia o PRD, as tasks decompostas, e o status que avança conforme o trabalho caminha.
Onde o código vive e a entrega acontece: branches, pull requests e os portões de qualidade via Pipelines (CI).
O mínimo obrigatório para qualquer projeto: uma pasta por orquestração com todos os artefatos aprovados/registrados e o mapa de rastreabilidade.
É 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.
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.
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.
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.
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.
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.
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.
O segredo de "autônomo com checkpoints" está aqui: o workflow durável precisa pausar e esperar um evento externo que pode demorar dias.
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.
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?".
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.
"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.
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: nenhumPRD → 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: altoLigue 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 isoladoPersista 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 compostosMova 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 largadaA 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.