RPI com IA: Uma Introdução ao Research-Plan-Implement

O desenvolvimento de software auxiliado por Inteligência Artificial exige processos mais robustos do que a simples geração direta de código.

O padrão RPI (Research, Plan, Implement) organiza essa interação em etapas bem definidas, garantindo previsibilidade e alta qualidade técnica.

O que é o Padrão RPI (Research-Plan-Implement)?

Tradicionalmente, os desenvolvedores falham ao solicitar que a IA planeje e escreva código de forma simultânea.

Esse comportamento polui o contexto do modelo de linguagem e causa alucinações.

O RPI resolve esse problema isolando o processo de engenharia de software em três etapas sequenciais.

Como Funcionam as Etapas do Padrão RPI

Cada etapa possui responsabilidades únicas e saídas bem delimitadas.

1. Research (Pesquisa)

Nesta etapa, o agente de IA explora o codebase atual para estabelecer fatos sobre o estado do sistema.

É expressamente proibido propor soluções, sugerir melhorias ou escrever códigos.

A saída desta fase é um documento detalhado que registra apenas as dependências e arquivos que serão afetados pela mudança.

2. Plan (Planejamento)

Com base nas informações consolidadas da pesquisa, o agente projeta a arquitetura técnica da solução.

O planejamento divide a implementação em fases lógicas.

Cada fase deve conter tarefas de escopo estritamente atômico.

3. Implement (Implementação)

Nesta fase, a IA executa mecanicamente e passo a passo as tarefas especificadas no plano.

O agente de IA atualiza as caixas de seleção do plano para rastrear o progresso.

A validação por meio de testes ou compilação é mandatória antes de avançar para a tarefa seguinte.

Escalas de Validação do RPI

O RPI utiliza duas escalas de validação rigorosas para garantir a qualidade de cada fase.

A Escala FAR (Research)

A escala FAR (Factual, Actionable, Relevant) é utilizada para qualificar o resultado da fase de pesquisa.

O critério Factual exige que a análise seja baseada em código real, não em suposições.
O critério Actionable garante que a IA saiba exatamente quais caminhos seguir no planejamento.
O critério Relevant atesta que a pesquisa foca na resolução direta da necessidade do usuário.

A Escala FACTS (Plan)

A escala FACTS (Feasible, Atomic, Clear, Testable, Scoped) qualifica o plano antes de iniciar o código.

O plano deve ser Feasible (executável com as ferramentas disponíveis), Atomic (tarefas pequenas) e Clear (sem ambiguidades).
O plano também deve ser Testable (com critérios claros de sucesso) e Scoped (devidamente limitado para evitar dispersão de foco).

A tabela abaixo compara o objetivo de cada uma das escalas no fluxo de engenharia:

Escala	Fase Relacionada	Principais Critérios	Objetivo Principal
FAR	Research	Factual, Actionable, Relevant	Garantir mapeamento fiel da base de código existente.
FACTS	Plan	Feasible, Atomic, Clear, Testable, Scoped	Criar tarefas atômicas e testáveis para execução.

Como Implementar o RPI no seu Projeto

Você pode adotar o padrão RPI de maneira conceitual no seu fluxo de desenvolvimento do dia a dia.

Passo 1: Estrutura Física de Diretórios

Primeiro, crie uma estrutura dedicada de diretórios no seu repositório para guardar os históricos de cada ciclo.

# Estrutura de diretórios para o RPI
thoughts/
├── research/
└── plans/

Passo 2: O Documento de Pesquisa

Toda nova tarefa ou correção deve iniciar com um arquivo Markdown salvo em thoughts/research/.

Nesse documento, a IA registra os arquivos afetados, as dependências e as regras de negócio vigentes.

Passo 3: O Plano e Checklist

Após a validação humana da pesquisa, a IA lê este documento em uma nova sessão limpa de contexto.

O plano de ação é salvo em thoughts/plans/ contendo a arquitetura da solução e caixas de seleção de progresso.

Passo 4: Execução com Rastreamento de Progresso

Durante a fase de implementação, a IA atualiza diretamente o arquivo de plano marcando as caixas de seleção concluídas.

Caso o contexto do modelo estoure, ele pode recuperar o estado lendo as tarefas pendentes do arquivo de plano.

Implementação Avançada do RPI com OpenSpec

O OpenSpec é um framework de Spec-Driven Development que atua como o motor ideal para executar o RPI de forma automatizada e padronizada.

Ele substitui as anotações informais do RPI por artefatos estruturados e integrados via linha de comando.

Fluxo RPI com o CLI do OpenSpec

Para iniciar uma mudança, você utiliza a linha de comando para inicializar o contexto da tarefa.

# Inicializa o contexto da alteração no projeto
openspec new change "refactor-session-auth"

A ferramenta cria a pasta correspondente e define os artefatos necessários antes da codificação.

# Exibe a lista de especificações pendentes para autorizar a implementação
openspec status --change "refactor-session-auth" --json

O agente de IA consome as regras fornecidas pela ferramenta para elaborar a proposta e o design técnico.

# Obtém o template e regras específicas para cada artefato
openspec instructions proposal --change "refactor-session-auth" --json

Usando as Skills do OpenSpec

O OpenSpec encapsula as operações feitas através da CLI em Skills com o objetivo de facilitar a adesão dos agentes de IA.

Logo abaixo estão algumas dessas skills:

openspec-explore

Para a fase de Research, a skill openspec-explore auxilia a explorar o codebase, pensar em alternativas e resolver problemas em andamento sem alterar código.

openspec-propose

A skill openspec-propose é focada no planejamento (fase de Plan), gerando o arquivo proposal.md (o que e porquê), design.md (como) e tasks.md (tarefas de implementação).

Durante a execução da skill, a IA solicita informações adicionais para alinhar o escopo e evitar pressupostos errados.

openspec-apply-change

A skill openspec-apply-change foca exclusivamente na fase de Implement.

Ao ser ativada, a skill lê todos os arquivos de contexto técnico gerados e executa as tarefas listadas em tasks.md passo a passo.

Ela garante que a IA atualize o checkbox do arquivo de tarefas logo após cada alteração ser concluída e testada.

openspec-archive-change

Finalmente, a skill openspec-archive-change encerra o ciclo de vida, arquivando a especificação e sincronizando as delta specs com as especificações gerais já construídas que servem como a única fonte da verdade (source of truth).

Outras Ferramentas no RPI

Embora o OpenSpec seja a abordagem mais madura e focada em especificações, outras ferramentas podem ser citadas como alternativas.

O Goose da Block oferece comandos integrados no terminal como /research, /plan e /implement para estruturar sessões de chat.

Além disso, editores e assistentes como Cursor, Claude Code e GitHub Copilot podem ser instruídos a simular o RPI por meio de prompts customizados do usuário.

Conclusão

Adotar o RPI transforma o desenvolvimento com IA de um processo baseado em tentativa e erro para engenharia previsível.

Com o uso das skills nativas do OpenSpec, essa divisão entre pesquisa, planejamento e implementação atinge seu nível máximo de conformidade e automação.