Plan-and-Solve Prompting

1. Visão Geral do Conceito e Problema Sistêmico

Quando um desenvolvedor atribui uma tarefa de engenharia complexa a uma IA (por exemplo, "reescrever o módulo de autenticação de JWT para sessões em banco de dados"), a reação impulsiva do agente é editar imediatamente o primeiro arquivo aleatório que encontra.

Essa abordagem puramente reativa causa falhas críticas:

1. Violação da ordem de dependências: O agente altera um componente de interface antes de atualizar o schema do banco de dados ou criar os tipos TypeScript necessários.
2. Edições circulares: O modelo corrige um erro, quebrando outro arquivo relacionado, e fica preso em um ciclo infinito de ajustes de sintaxe sem compreender o panorama geral.
3. Perda do objetivo primário: Após 10 passos de depuração, o contexto é saturado por mensagens do compilador, fazendo com que o modelo esqueça a tarefa original do usuário.

O padrão Plan-and-Solve elimina esse problema através de um princípio clássico de engenharia: Separação entre Design Estratégico (Planning) e Implementação Tática (Execution).

2. Taxonomia Arquitetural e Modelo Mental

O padrão é implementado através de três fases complementares:

• 1. Fase de Descoberta e Planejamento (Discovery & Planner Phase): O agente analisa a solicitação, lê previamente o sistema de arquivos (somente leitura/Read-Only) e gera um grafo de ações estruturado: um array de etapas com objetivos, critérios de sucesso e arquivos necessários claramente definidos.
• 2. Fase de Execução das Etapas (Solver / Execution Phase): Um executor especializado assume o primeiro item aberto do plano, invoca as ferramentas necessárias (edição de arquivos, execução de builds), confirma a conclusão da subtarefa e marca o item como concluído.
• 3. Fase de Replanejamento Dinâmico (Replanning & Feedback Phase): Se durante a execução de uma etapa surgir um erro que não pode ser resolvido com uma simples repetição (por exemplo, descobrindo-se a ausência de um módulo necessário no sistema), o replanner revisa os itens restantes do plano, adicionando uma etapa para instalação das dependências.

3. Pipeline Técnico e Mecânica Interna

O ciclo de vida da operação sob o padrão Plan-and-Solve:

1. Geração do Plano Estruturado (Plan Generation): O modelo formula um objeto JSON válido contendo um array de tarefas: tasks: [{ id: 1, title: "DB Schema", status: "pending" }, { id: 2, title: "API Route", status: "pending" }].
2. Injeção de Estado (State Injection): O plano é gravado no estado do agente. O usuário visualiza o progresso da execução na forma de um checklist interativo.
3. Loop de Execução (Execution Loop): O orquestrador seleciona a próxima tarefa com status pending. O contexto é limpo dos detalhes antigos de debug, focando exclusivamente na tarefa atual e no objetivo final.
4. Verificação de Invariantes e Transição de Status (Invariant Check & Status Transition): Após a conclusão da etapa, um linter ou teste unitário é executado. Se a verificação for bem-sucedida, o status muda para completed. Caso contrário, o método replan() é chamado para ajustar as etapas pendentes.

4. Cenários Práticos de Engenharia em Produção

01. Migração Complexa de Base de Código

Transição de um projeto do Next.js Pages Router para o App Router:

• Passo 1: Auditoria da estrutura da pasta pages/ e identificação de Layouts compartilhados.
• Passo 2: Criação do app/layout.tsx raiz e estilos base.
• Passo 3: Migração gradual das páginas estáticas.
• Passo 4: Reescrita das rotas dinâmicas e API Routes em route.ts.
• Passo 5: Build completo do projeto e remoção de arquivos obsoletos.

02. Desenvolvimento Orientado a Especificações (Spec-Driven Development)

O agente recebe um requisito de negócio. Primeiramente, ele redige a documentação e os schemas Zod, alinha-os com o usuário e, somente após obter aprovação, gera passo a passo o backend, os hooks do cliente e os componentes de UI.

03. Implantação de Infraestrutura de Servidores

Hardening progressivo de um Linux VPS:

• Geração de um plano com 6 etapas (chaves SSH, firewall UFW, fail2ban, atualização de pacotes, criação de usuário non-root, desativação de acesso por senha).
• Cada item é executado individualmente com verificação obrigatória do status da porta antes de desativar o método anterior de conexão.

5. Armadilhas, Erros Comuns e Segurança

• Planejamento Prematuro (Premature Planning): Criar um plano sem analisar previamente os arquivos do repositório. O modelo pode planejar o uso de bibliotecas que não existem no projeto. Solução: incluir uma etapa obrigatória de "Descoberta" (Discovery) antes de iniciar o planejador.
• Rigidez Excessiva do Plano (Plan Rigidity): O agente insiste em executar a Etapa 3 quando, na Etapa 1, descobre-se que a arquitetura exige uma abordagem fundamentalmente diferente. É imperativo implementar hooks de replanejamento dinâmico.
• Micromanagement em 30 Passos: Etapas excessivamente granulares (por exemplo, uma etapa separada para importar cada tipo) desperdiçam tempo e recursos financeiros. Mantenha o nível de abstração alinhado aos blocos funcionais lógicos.