PulseFlow Tecnologia
← Insights
·7 min de leitura·guia-tecnico·spec-driven-development·coding-agents·code-review
PulseFlow Tecnologia

Como desenhar um coding agent workflow com especificação, branch, teste e review

Um coding agent workflow bem desenhado combina três peças que já existem separadamente em produtos reais: a estrutura de especificação do GitHub Spec Kit, o fluxo de PR do Copilot coding agent, e o modelo de execução isolada do Codex da OpenAI. Juntas, elas formam um workflow completo - da ideia ao merge.

Issue ou requisito vira especificação, não prompt solto

O Spec Kit do GitHub separa isso em quatro fases explícitas. A primeira, "Specify", descreve "user journeys, experiences, e o que significa sucesso" - não detalhes técnicos de implementação. Essa é a diferença fundamental entre spec-driven development e o que o próprio GitHub chama de "vibe coding": descrever um objetivo e receber um bloco de código, com resultado frequentemente impreciso, versus fornecer uma especificação clara que força "clareza sobre como deve interagir com sistemas existentes" antes de qualquer linha ser escrita.

Plano do agente antes da execução

A segunda fase do Spec Kit, "Plan", define stack tecnológico, arquitetura e restrições. A terceira, "Tasks", divide a especificação em "trabalhos pequenos e revisáveis que resolvem peças específicas" - o equivalente a quebrar um requisito grande em unidades que cabem num único PR revisável.

Branch isolada e execução

É aqui que o fluxo do Copilot coding agent se encaixa: o agente abre um pull request em rascunho, marcado como [WIP], num branch dedicado (copilot/*), isolado do branch principal. A execução em si segue o modelo que a OpenAI documentou com o Codex - rodando dentro de um ambiente isolado, lendo e editando arquivos, com acesso restrito ao necessário para a tarefa.

Testes automatizados como parte da execução, não como etapa posterior

Tanto o Copilot coding agent quanto o Codex rodam testes e linters como parte do próprio ciclo de execução - o agente "explora o repositório, faz as alterações, executa testes e lint" antes de considerar o PR pronto para revisão. Isso corresponde à quarta fase do Spec Kit, "Implement": o agente executa tarefas isoladas, o que "permite revisão focada" em vez de revisar um PR gigante e difícil de auditar.

Code review humano e security check

O PR chega para revisão só depois de passar pelo próprio crivo automatizado do agente - título, descrição e testes já preenchidos. O time revisa e pode iterar comentando diretamente no PR (@copilot, no caso do GitHub). Security check nesse ponto inclui detecção de segredos e alertas de varredura de código, já embutidos na camada de Remote MCP Server do Copilot.

Observabilidade e merge controlado

Cada etapa do processo - da abertura do PR ao comentário de revisão - fica registrada e visível para o time, não escondida numa caixa preta. O merge continua sendo uma decisão humana, gate final depois de specs, plano, execução, testes e revisão terem passado.

O workflow completo, em ordem

  1. Issue ou requisito
  2. Spec inicial ("Specify": jornada do usuário, critério de sucesso)
  3. Plano do agente ("Plan": stack, arquitetura, restrições)
  4. Divisão em tarefas ("Tasks": unidades pequenas e revisáveis)
  5. Branch isolada, dedicada ao agente
  6. Execução em ambiente isolado
  7. Testes automatizados e lint como parte da execução
  8. Code review humano
  9. Security check (segredos, varredura de código)
  10. Merge controlado

Fontes