Planeamento, raciocínio e execução separados

Nesta unidade, irá aprender:

• Porque é que separar planeamento, execução e validação melhora a fiabilidade

• Compreender a diferença entre fluxos de trabalho plano-primeiro e plano e execução

• Como fazer cumprir limites de planeamento usando limites de capacidade e bloqueios de ferramentas

Porque a separação melhora a fiabilidade

Sistemas de agentes fiáveis separam:

• Planeamento: o que será feito e porquê.

• Execução: as alterações concretas feitas ao repositório.

• Validação: evidência de que o resultado cumpre os critérios de sucesso.

Quando planeamento e execução se misturam, os revisores veem apenas a diferença final. Perdem a capacidade de validar a intenção precocemente, detetar rapidamente mal-entendidos e controlar o âmbito antes do impacto.

Como a separação é aplicada no GitHub

O GitHub suporta naturalmente esta separação:

• O planeamento aparece numa descrição de relações públicas, num comentário de emissão ou num artefacto do Github/pull_request_template.md.

• A execução aparece como commits num branch.

• A validação aparece sob a forma de verificações, digitalizações, artefactos e resultados de revisão.

Compreender a diferença entre um fluxo de trabalho orientado por plano e um fluxo de trabalho de plano e execução

Ao trabalhar com agentes, as equipas têm de decidir quando um plano se torna visível e quando as alterações no código podem começar. No GitHub, o planeamento e a execução podem começar a partir de diferentes pontos de entrada — como um problema no GitHub (por exemplo, atribuir um Copilot Cloud Agent), ou através do separador Agents, onde um plano é gerado de forma interativa.

Estas são formas separadas de interagir com o agente, mas convergem para o mesmo modelo de governação: todo o trabalho é, em última análise, apresentado e revisto num pull request (PR)

A escolha chave de design não é, portanto, onde o plano começa, mas sim quando é necessária validação humana relativamente às alterações no código.

Opção A: Pedido de Consulta Plane-First

Nesta abordagem, o planeamento é concluído e aprovado antes de quaisquer alterações ao código serem introduzidas.

Como funciona na prática:

• É gerado um plano (por exemplo, atribuindo um agente a um problema do GitHub ou criando-o no separador Agents).

• O agente abre um pull request que contém apenas o plano (ainda sem alterações ao código).

• Os revisores discutem, refinam e aprovam o plano diretamente na PR.

• Após a aprovação, o agente procede à implementação do plano em commits de seguimento ou num novo PR.

Isto cria uma separação clara entre intenção (plano) e execução (código).

Opção B: Plano + execução no mesmo pull request

Nesta abordagem, planeamento e execução são combinados numa única PR.

Como funciona na prática:

• O agente abre um pull request que inclui ambos:

  • um plano estruturado (na descrição)

  • Alterações iniciais ao código (commits)

• O agente pode continuar a atualizar o PR à medida que o plano evolui.

• Os controlos padrão do GitHub para verificações obrigatórias, juntamente com as revisões do CODEOWNERS e a proteção de branches, impedem a fusão até que todos os requisitos sejam cumpridos.

Aqui, o plano ainda é visível, mas é apresentado juntamente com as mudanças ativas em vez de antes delas.

Diferença chave: Momento da validação

Ambas as opções usam os mesmos controlos do GitHub. A diferença está quando esses controlos são aplicados relativamente à execução:

• Opção A (Planear primeiro): A validação humana acontece antes de qualquer código ser escrito.

• Opção B (Plano + execução): O código é gerado imediatamente, mas a validação continua a ser necessária antes da fusão.

Considerações de risco

Ambas as abordagens podem ser seguras quando as proteções do GitHub estão corretamente configuradas. A diferença reside no momento em que o risco é introduzido no sistema:

• A opção A reduz a exposição precoce. Como não é gerado código antes da aprovação, os revisores validam primeiro a intenção. Isto minimiza alterações desnecessárias ou inseguras e é preferido em ambientes de alto risco (por exemplo, sistemas de produção ou áreas sensíveis à segurança).

• A Opção B introduz uma exposição mais precoce à mudança. O código aparece na PR antes de o plano ser totalmente validado. Embora este código não possa ser fundido sem aprovação, pode:

  • introduzir alterações desnecessárias ou incorretas que devem ser revistas e rejeitadas

  • aumentar o esforço dos revisores

  • criar um desalinhamento temporário entre o plano e a implementação

Importa referir que este risco existe durante a fase de proposta, não após a fusão. Os mecanismos de fiscalização do GitHub continuam a impedir a implementação de código inseguro.

Quando usar cada opção

• Utilize o fluxo de trabalho Plan-first quando:

  • As alterações são de alto risco ou difíceis de reverter

  • O alinhamento com a intenção é crítico antes da execução

  • Queres uma separação rigorosa entre planeamento e implementação

• Use o fluxo de trabalho de planeamento e execução quando:

  • Velocidade e iteração são mais importantes

  • As alterações são de baixo risco ou facilmente reversíveis

  • Os revisores sentem-se confortáveis a avaliar o plano e o código em conjunto

Principal conclusão

A escolha não é se o trabalho é revisto — é sempre. A escolha é quando o sistema permite gerar código em relação à validação humana, e quão cedo se quer introduzir a mudança no fluxo de trabalho.

Aplicação de fronteiras de planeamento utilizando limites de capacidade e restrição de ferramentas

1. Limite de capacidade (os agentes de planeamento são apenas de leitura) Um agente de planeamento deve estar limitado a ferramentas apenas de leitura, para não poder modificar ficheiros durante o planeamento.
2. Transição explícita (ou transferência) para um agente de implementação. A execução só deve ocorrer após a aprovação do plano, utilizando uma transferência deliberada.
3. Com o "tool gating" em sistemas de orquestração, em orquestrações automatizadas, pode-se forçar o planeamento a correr sem a execução de ferramentas e, em seguida, ativar as ferramentas apenas depois de o plano ser aceite.
4. Fluxos de trabalho em "modo de planeamento" - Algumas interfaces suportam uma experiência orientada pelo planeamento que gera um artefacto de plano de trabalho e pausa antes que qualquer alteração seja feita.

Orientação para a decisão

• Use o plane-first para trabalhos de alto risco (fluxos de trabalho, infraestrutura, autenticação, produçã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 as listas de permissões e os limites da ferramenta como aplicação.

Conclusão principal: A separação cria uma oportunidade para rever a intenção antes de aceitar o impacto.

De seguida, irá impor visibilidade e validação do plano através de portas de aprovação de pull requests.