MÓDULO 1.5

🤖 Execução: subagentes e planos

Deixe o agente trabalhar por horas autonomamente sem desviar do plano — com subagentes e revisão em dois estágios.

📋6 tópicos ⏱️~35 min 🎯Intermediário 📖Teoria + Prática
1

📦 executing-plans: lotes com checkpoints humanos

A skill executing-plans organiza a execução do plano em lotes de tarefas — tipicamente 3-5 tarefas por lote. Após cada lote, o agente para e apresenta um resumo do que foi feito, o que verificou e o que planeja fazer no próximo lote. Você aprova antes de continuar.

Estrutura de um lote

Lote 1 (tarefas 1-3): Estrutura base do projeto
↓ checkpoint: você revisa e aprova
Lote 2 (tarefas 4-6): Lógica de negócio
↓ checkpoint: você revisa e aprova
Lote 3 (tarefas 7-9): Integração e testes

O tamanho do lote é configurável. Lotes menores = mais controle, mais interrupções. Lotes maiores = menos controle, mais autonomia. O padrão de 3-5 tarefas equilibra os dois.

2

🚀 subagent-driven-development: um agente por tarefa

No subagent-driven-development, cada tarefa do plano é delegada a um subagente com contexto isolado. O agente coordenador mantém o estado do plano e despacha cada tarefa para um subagente fresco, que executa e reporta o resultado sem acumular contexto de tarefas anteriores.

Agente coordenador

  • • Mantém o plano completo
  • • Decide qual tarefa vai para qual subagente
  • • Verifica o resultado de cada subagente
  • • Atualiza o estado do plano

Subagente por tarefa

  • • Recebe apenas a tarefa atual
  • • Contexto limpo, sem acúmulo
  • • Executa e reporta resultado
  • • Encerrado após a tarefa

Vantagem do contexto isolado

Um agente com contexto longo começa a "esquecer" instruções iniciais e a misturar informações de diferentes tarefas. Subagentes frescos mantêm foco e não acumulam confusão.

3

🔍 Revisão em 2 estágios: spec e qualidade

A revisão em dois estágios separa critérios que, se misturados, criam confusão. No primeiro estágio, o revisor verifica conformidade com a spec — se o comportamento implementado corresponde ao que foi especificado. No segundo, verifica qualidade técnica — código limpo, sem smells, com boas práticas.

Estágio 1: Conformidade com spec

  • • Todos os critérios de aceitação implementados?
  • • Casos de borda cobertos?
  • • Comportamento em erros definido na spec?
  • • Nada fora do escopo adicionado?

Estágio 2: Qualidade técnica

  • • Código legível e bem nomeado?
  • • Sem duplicação desnecessária?
  • • Testes cobrem casos relevantes?
  • • Performance adequada para o contexto?

Por que separar os dois estágios

Um código pode ser tecnicamente excelente mas não cumprir a spec — e deve ser rejeitado. Um código pode cumprir a spec mas ser de qualidade ruim — e deve ser refatorado antes do merge. Critérios diferentes, prioridades diferentes.

4

🧭 Quando usar executing-plans vs. subagents

Não existe uma resposta universal — a escolha depende do tipo de plano e do nível de autonomia desejado. Entender os trade-offs permite escolher o modo certo para cada situação.

Use executing-plans quando:

  • • Tarefas têm dependência sequencial forte
  • • Você quer revisar após cada lote
  • • O plano muda conforme você avança
  • • Feature crítica ou de alto risco

Use subagents quando:

  • • Tarefas são independentes entre si
  • • Você quer máxima velocidade
  • • O plano está bem definido e estável
  • • Feature de baixo risco e bem testada

Para projetos novos, comece com executing-plans até ganhar confiança no plano e no processo. Subagents são mais eficientes mas requerem planos mais maduros.

5

👁️ Monitorando e corrigindo subagentes

Subagentes trabalham autonomamente, mas isso não significa que devem ser ignorados. Monitoramento ativo permite detectar desvios cedo e intervir sem perder o contexto do plano maior. Os sinais de desvio são específicos e reconhecíveis.

Sinais de que um subagente está desviando

  • Relatório com "implementei algo similar ao que foi pedido"
  • Menção de arquivos que não estavam no plano original
  • Tempo de execução muito maior que o esperado (2-5 min)
  • Resultado que não inclui o critério de verificação passando

Como intervir sem perder contexto

Quando intervir, forneça o estado atual do plano (tarefa X de Y), o que foi feito até aqui e o que a tarefa específica deve entregar. O agente coordenador mantém esse estado e pode passá-lo para o subagente substituto.

6

🛠️ Prática: plano completo com subagentes

Use o plano aprovado do módulo anterior e execute-o com subagentes. O objetivo é ver o modo de execução mais poderoso do Superpowers em ação, com revisão em dois estágios ao final.

Roteiro do exercício

  1. 1.Passe o plano aprovado para o agente coordenador
  2. 2.Instrua: "Execute com subagents, uma tarefa por vez, reportando ao final de cada uma"
  3. 3.Monitore os relatórios de cada subagente — verifique os sinais de desvio
  4. 4.Ao final, execute a revisão estágio 1: conformidade com spec
  5. 5.Execute a revisão estágio 2: qualidade técnica
  6. 6.Corrija issues bloqueadoras antes de avançar para o Módulo 1.6

Critério de conclusão

Plano executado via subagentes, revisão em dois estágios concluída, issues bloqueadoras resolvidas. O código está pronto para entrar no módulo de debugging (se houver bugs) ou revisão final.

Resumo do Módulo 1.5

Entendi como executing-plans organiza lotes com checkpoints
Compreendi o padrão subagent-driven-development
Sei fazer revisão em 2 estágios: spec e qualidade
Conheço o critério para escolher entre os dois modos
Sei monitorar subagentes e identificar sinais de desvio
Executei o plano completo com subagentes e revisão
Próximo módulo: 1.6 — Debugging sistemático