Decomposing User Stories into Actionable Steps

1. Além da Reatividade: O Padrão "Plan-and-Execute"

Seu uso anterior de APIs de LLM, como Gemini, provavelmente seguiu um padrão de pergunta e resposta. No mundo dos agentes, essa abordagem reativa, conhecida como ReAct (Reasoning and Acting), tem limitações. O agente executa uma etapa, observa o resultado e decide a próxima, o que pode ser lento, caro e míope para tarefas complexas.

Uma estratégia mais robusta é o padrão Plan-and-Execute. Aqui, um agente "Planejador" primeiro cria um plano completo de etapas. Depois, um ou mais agentes "Executores" realizam essas etapas. Isso permite um pensamento mais estratégico e a otimização da execução.

O padrão Plan-and-Execute é a nossa estratégia fundamental. O JSON que nosso agente gera é a manifestação do "plano". As actions que definimos no módulo anterior serão usadas pelo "executor".

2. Decomposição Hierárquica de Processos: Uma Abordagem de Engenharia

Para tarefas de engenharia de software, um simples plano linear muitas vezes não é suficiente. Dada sua experiência em pesquisa e desenvolvimento, você sabe que a solução para um problema complexo raramente é uma lista simples de tarefas. A chave é a decomposição rigorosa.

A abordagem mais eficaz é a Decomposição Hierárquica de Processos. Em vez de pedir ao LLM para "implementar a funcionalidade X", nós o guiamos a quebrar essa tarefa em níveis sucessivos de granularidade até chegar a "micro-tarefas atômicas" — operações únicas, verificáveis e com um propósito específico.

Essa abordagem é a espinha dorsal da nossa estratégia de planejamento. O prompt que projetamos na última lição já orienta o agente a realizar uma forma de decomposição, produzindo uma lista de ações no campo "plan". A decomposição hierárquica nos dá um método para pensar sobre como tornar esse plano ainda mais detalhado e confiável.

3. Decomposição Através da Especialização: Arquitetura Multi-Agente

A decomposição hierárquica sugere naturalmente a especialização. Algumas micro-tarefas são de investigação (ler arquivos, analisar o código existente), outras são de implementação (escrever novo código) e outras de verificação (rodar testes). Isso nos leva a uma arquitetura de múltiplos agentes, onde cada agente é especialista em um tipo de tarefa.

Mesmo que estejamos construindo um único agente Rovo, podemos projetar seu processo de planejamento para imitar essa especialização.

Nosso agente atuará principalmente como o Orquestrador. Ele analisará o ticket do Jira e criará um plano. As etapas dentro do plano gerado seguirão o padrão Investigate → Implement → Verify, simulando a delegação para agentes especializados. Por exemplo, uma etapa pode ser "Analisar o arquivo X para entender a estrutura de dados atual" (tarefa de Explorador), seguida por "Modificar o arquivo X para adicionar o novo campo" (tarefa de Codificador).

4. Estratégias Práticas para Lidar com a Complexidade

A teoria da decomposição é sólida, mas a prática traz desafios, como ambiguidades nos requisitos ou tarefas tão grandes que excedem a janela de contexto do LLM.

5. Nossa Estratégia de Decomposição Sintetizada

Vamos unificar esses conceitos em uma estratégia coesa para o nosso agente de código:

1. Análise e Planejamento Inicial (Padrão Plan-and-Execute):

   • Acionado por um evento no Jira, o agente recebe o ticket.
   • Usando nosso "prompt mestre", ele atua como Orquestrador. Sua primeira tarefa é analisar o requisito e gerar o JSON do plano.

2. Decomposição Hierárquica e Especialização Simulada:

   • O prompt orienta o agente a pensar de forma estruturada. O plano resultante não será apenas uma lista de modificações de código. Ele seguirá uma lógica de Investigate -> Plan -> Implement -> Verify.
   • Exemplo de plano decomposto:
     • Fase 1: Investigação (Simulando o Explorador)
       • { "action": "SEARCH_FILES", "query": "user model definition" }
       • { "action": "READ_FILE", "file_path": "src/models/User.cs" }
     • Fase 2: Implementação (Simulando o Codificador)
       • { "action": "CREATE_BRANCH", "branch_name": "feature/JIRA-123" }
       • { "action": "MODIFY_FILE", "file_path": "src/models/User.cs", "description": "Add PhoneNumber property" }
       • ...outras modificações de código...
     • Fase 3: Verificação (Simulando o Explorador novamente)
       • { "action": "RUN_TESTS", "project": "backend-api.csproj" }

3. Gerenciamento da Complexidade e Ambiguidade:

   • Tratamento de Erros: Se, durante a análise, o agente encontrar ambiguidades (conforme definido no ERROR_HANDLING do nosso prompt), ele não gera o plano. Em vez disso, ele usa a action do Jira para adicionar um comentário ao ticket pedindo esclarecimentos.
   • Checkpoint Humano: Para planos que envolvem alterações críticas (como migrações de banco de dados), o JSON do plano inclui a chave "human_approval_required". O sistema de orquestração deve pausar e aguardar uma aprovação humana antes de prosseguir para a fase de execução.

Essa estratégia combina a teoria robusta da decomposição hierárquica com a praticidade de uma arquitetura de agente único, preparando o terreno para uma futura expansão para um sistema multi-agente mais complexo.

Conclusão

Nesta lição, você aprendeu a formular uma estratégia para que um agente decomponha tarefas complexas de software. Vimos que simplesmente pedir a um LLM para "fazer o trabalho" é ineficaz. Em vez disso, devemos projetar um processo de planejamento estruturado.

Principais Pontos:

• Plan-and-Execute: Separe o planejamento da execução para um comportamento mais estratégico e confiável.
• Decomposição Hierárquica: A chave para tarefas complexas é quebrar o trabalho em micro-tarefas atômicas e verificáveis. Esta é uma abordagem de engenharia para o design de agentes.
• Especialização e Delegação: Projetar o agente para pensar em termos de papéis especializados (Orquestrador, Explorador, Codificador) leva a planos mais robustos, mesmo em uma arquitetura de agente único. O "Padrão de Delegação Forçada" é um poderoso princípio de design para incentivar um bom planejamento.
• Estratégias Práticas: Para tarefas muito grandes, use planos multifásicos e externalize o plano (por exemplo, em um comentário do Jira) para gerenciar a janela de contexto e manter o estado.

Na Próxima Lição:

Agora que temos uma estratégia de planejamento, vamos começar a focar em como o agente executa as primeiras etapas desse plano. A próxima lição, "Implementar uma etapa de planejamento onde o agente determina quais arquivos precisam ser modificados em vários repositórios", nos levará da teoria do planejamento para a implementação prática da fase de investigação do nosso agente.