Planejamento, raciocínio e execução separados
Nesta unidade, você aprenderá:
Por que separar planejamento, execução e validação melhora a confiabilidade
Compreensão da diferença entre uma abordagem de planejamento primeiro e fluxos de trabalho de planejamento e execução
Como impor limites de planejamento usando limitações de capacidade e restrição de ferramentas
Por que a separação melhora a confiabilidade
Sistemas de agente confiáveis separados:
Planejamento: o que será feito e por quê.
Execução: as alterações concretas feitas no repositório.
Validação: evidência de que o resultado atende aos critérios de êxito.
Quando o planejamento e a execução são misturados, os revisores veem apenas a diferença final. Eles perdem a capacidade de validar a intenção antecipadamente, detectar mal-entendidos rapidamente e controlar o escopo antes do impacto.
Como a separação se aplica ao GitHub
GitHub naturalmente dá suporte a essa separação:
O planejamento aparece em uma descrição de PR, em um comentário de problema ou em um artefato github/pull_request_template.md.
A execução aparece como commits em um branch.
A validação aparece como verificações, exames, artefatos e resultados de revisão.
Compreendendo a diferença entre um fluxo de trabalho orientado ao planejamento e um fluxo de trabalho planejado e executado
Ao trabalhar com agentes, as equipes devem decidir quando um plano fica visível e quando as alterações de código têm permissão para começar. Em GitHub, o planejamento e a execução podem começar de diferentes pontos de entrada, como um problema de GitHub (por exemplo, atribuir um agente de nuvem Copilot) ou por meio da guia Agentes em que um plano é gerado interativamente.
Estas são maneiras separadas de interagir com o agente, mas convergem no mesmo modelo de governança: todo o trabalho é por fim exibido e revisado em um pull request (PR).
A principal escolha de design é, portanto, não onde o plano começa, mas quando a validação humana é necessária em relação às alterações de código.
Opção A: Pull request com planejamento prévio
Nessa abordagem, o planejamento é concluído e aprovado antes de qualquer alteração de código ser introduzida.
Como funciona na prática:
Um plano é gerado (por exemplo, atribuindo um agente a um GitHub problema ou criando-o na guia Agentes).
O agente abre uma solicitação de pull que contém apenas o plano (ainda sem alterações de código).
Os revisores discutem, refinam e aprovam o plano diretamente na PR.
Após a aprovação, o agente passa a implementar o plano em confirmações de acompanhamento ou em uma nova PR.
Isso cria uma separação clara entre intenção (plano) e execução (código).
Opção B: Planejar + execução na mesma solicitação de pull
Nessa abordagem, o planejamento e a execução são combinados em uma única PR.
Como funciona na prática:
O agente abre uma PR que inclui ambos os itens:
um plano estruturado (na descrição)
alterações iniciais de código (commits)
O agente pode continuar atualizando a PR conforme o plano evolui.
Revisões de CODEOWNERS, verificações padrão exigidas por controles do GitHub e proteção de ramificações impedem a mesclagem até que todos os requisitos sejam satisfeitos.
Aqui, o plano ainda está visível, mas é apresentado junto com as alterações ativas em vez de antes delas.
Principal diferença: tempo de validação
Ambas as opções usam os mesmos controles GitHub. A diferença é quando esses controles são aplicados em relação à execução:
Opção A (Planejar primeiro): A validação humana ocorre antes de qualquer código ser gravado.
Opção B (Planejar + execução): O código é gerado imediatamente, mas a validação ainda é necessária antes da mesclagem.
Considerações de risco
Ambas as abordagens podem ser seguras quando GitHub proteções estão configuradas corretamente. A diferença está em quando o risco é introduzido no sistema:
A opção A reduz a exposição precoce. Como nenhum código é gerado antes da aprovação, os revisores validam a intenção primeiro. Isso minimiza alterações desnecessárias ou não seguras e é preferencial em ambientes de alto risco (por exemplo, sistemas de produção ou áreas sensíveis à segurança).
A opção B apresenta a exposição antecipada à mudança. O código é exibido na PR antes que o plano seja totalmente validado. Embora esse código não possa ser mesclado sem aprovação, ele pode:
introduzir alterações desnecessárias ou incorretas que devem ser revisadas e rejeitadas
aumentar o esforço do revisor
criar desalinhamento temporário entre o plano e a implementação
É importante ressaltar que esse risco existe durante a fase de proposta, não após a mesclagem. os mecanismos de imposição do GitHub ainda impedem que o código não seguro seja implantado.
Quando usar cada opção
Use o Plan-first workflow quando:
as alterações são de alto risco ou difíceis de reverter
alinhamento de intenções é crítico antes da execução
você deseja uma separação estrita entre planejamento e implementação
Use Plano e execução o fluxo de trabalho quando:
velocidade e iteração são mais importantes
as alterações são de baixo risco ou facilmente reversíveis
revisores estão confortáveis avaliando o plano e o código juntos
Conclusão principal
A escolha não é se o trabalho é revisado - ele sempre é. A escolha é quando o sistema permite que o código seja gerado em relação à validação humana e quão cedo você deseja introduzir a alteração no fluxo de trabalho.
Impor fronteiras de planejamento usando limitações de capacidade e controle de ferramentas
- Limite de funcionalidade (agentes de planejamento são somente leitura) Um agente de planejamento deve ser limitado a ferramentas somente leitura para que ele não possa modificar arquivos durante o planejamento.
- Transição explícita (ou entrega) para um agente de implementação. A execução deve ocorrer somente após a aprovação do plano, usando uma entrega deliberada.
- Bloqueio de ferramentas em orquestradores: em orquestrações automatizadas, é possível forçar a execução do planejamento sem a execução de ferramentas e, em seguida, habilitar as ferramentas de software somente depois que o plano for aceito.
- Fluxos de trabalho de "modo de plano" – algumas interfaces dão suporte a uma experiência de planejamento em primeiro lugar que gera um artefato de planejamento e pausa antes que qualquer alteração seja aplicada.
Diretrizes de decisão
Priorize o planejamento para trabalhos de alto risco (infra, fluxos de trabalho, produção, autenticação).
Use plano + execução para trabalho de médio/baixo risco, mas mantenha as verificações/revisões necessárias.
Trate "instruções para não editar" como orientação; trate listas de permissões da ferramenta e portões como imposição.
Principal conclusão: A separação cria uma oportunidade para revisar a intenção antes de aceitar o impacto.
Em seguida, você imporá a visibilidade e a validação do plano por meio de portões de aprovação de solicitação de pull.