Workflow de Agente de Modo Duplo Plan vs Act no Cursor

Um dos maiores desafios com agentes de codificação IA é impedir que eles façam alterações não autorizadas. O workflow dual-mode Plan vs Act resolve isso exigindo que o agente proponha mudanças no "modo Plan" antes de executá-las no "modo Act". Este guia mostra como implementar esse poderoso padrão de segurança no Cursor.

O que é Plan vs Act?

Modo Plan (Somente leitura)

No modo Plan, o agente:

• Lê e analisa o código
• Propõe alterações em um formato estruturado
• Não pode modificar nenhum arquivo
• Apresenta um plano detalhado para revisão do usuário

Modo Act (Leitura-escrita)

No modo Act, o agente:

• Executa apenas as alterações aprovadas
• Tem acesso completo de leitura e escrita
• Segue o plano exato fornecido
• Reporta o que foi feito

Por que usar este padrão?

Sem Plan/Act	Com Plan/Act
A IA altera arquivos inesperadamente	Todas as alterações exigem aprovação
Difícil revisar o que mudou	Um plano claro é apresentado primeiro
Rollbacks são difíceis	As alterações são rastreáveis e reversíveis
Deriva de contexto em sessões longas	Execução focada por tarefa

Método de implementação 1: Regras do Cursor

Crie .cursor/rules/plan-act-workflow.mdc:

---
description: 'Workflow dual-mode Plan vs Act'
globs: ['**/*']
alwaysApply: true
---

# Workflow Plan vs Act

## REGRA CRÍTICA
Você NÃO DEVE modificar arquivos sem aprovação explícita do usuário.

## Modo Plan (Padrão)
Quando uma tarefa é dada:
1. LER e analisar os arquivos relevantes
2. CRIAR um plano detalhado com alterações específicas
3. APRESENTAR o plano neste formato:

### Plano: [Nome da tarefa]

#### Arquivos a modificar
- `file/path/one.ts` - O que mudar
- `file/path/two.ts` - O que mudar

#### Resumo das alterações
1. Descrição da alteração 1
2. Descrição da alteração 2

#### Novos arquivos (se houver)
- `new/file/path.ts` - Propósito

#### Plano de teste
- Como verificar se as alterações funcionam

4. AGUARDAR o usuário digitar "PROCEED" ou "ACT"

## Modo Act (Após aprovação)
Somente depois que o usuário disser "PROCEED":
1. Implementar as alterações do plano
2. Fazer APENAS as alterações aprovadas
3. Reportar conclusão com a lista de arquivos
4. Sugerir etapas de teste

## NUNCA
- Pular a fase de planejamento
- Adicionar alterações não planejadas
- Modificar arquivos durante o modo Plan
- Pedir aprovação mais de uma vez por plano

Método de implementação 2: Modo personalizado

Crie um modo personalizado nas configurações do Cursor:

1. Abra as configurações do Cursor (Cmd/Ctrl + ,)
2. Navegue até "Modes" ou "AI Features"
3. Clique em "Add Custom Mode"
4. Configure:

{
  "name": "Planner",
  "description": "Modo de planejamento - análise somente leitura",
  "systemPrompt": "Você está no modo PLANEJAMENTO. Você pode LER arquivos mas NUNCA modificá-los. Analise a base de código, entenda os requisitos e apresente um plano detalhado. Aguarde aprovação do usuário antes de fazer qualquer alteração.",
  "tools": ["read", "grep", "search"],
  "fileWrite": false
}

{
  "name": "Executor",
  "description": "Modo de execução - implementar alterações aprovadas",
  "systemPrompt": "Você está no modo EXECUÇÃO. Implemente APENAS as alterações que foram aprovadas no plano. Não desvie do escopo aprovado. Reporte cada alteração à medida que a faz.",
  "tools": ["read", "write", "edit"],
  "fileWrite": true
}

Método de implementação 3: Workflow baseado em chat

Passo 1: Começar no modo Plan

[PLAN MODE] Preciso adicionar autenticação de usuário a este app.
Por favor, analise a base de código e crie um plano.
Não faça NENHUMA alteração ainda.

Passo 2: O agente apresenta o plano

## Plano: Adicionar autenticação de usuário

### Arquivos a modificar
1. `src/app.ts` - Adicionar middleware de auth
2. `src/routes/users.ts` - Adicionar endpoints de login/register
3. `src/models/user.ts` - Adicionar hash de senha

### Novos arquivos
1. `src/middleware/auth.ts` - Verificação JWT
2. `src/services/auth.ts` - Lógica de auth
3. `tests/auth.test.ts` - Testes unitários

### Detalhes de implementação
- Usar bcrypt para hash de senha
- Tokens JWT com expiração de 15min
- Rotação de refresh tokens

### Testes
- Testar login com credenciais válidas/inválidas
- Testar refresh de token
- Testar rotas protegidas

Passo 3: Revisar e aprovar

Você revisa o plano e:

• Digita PROCEED para aprovar
• Solicita modificações
• Rejeita e recomeça

Passo 4: Executar

[ACT MODE] PROCEED com o plano de autenticação.
Implemente exatamente o que foi aprovado.

Passo 5: Verificação

Após a execução:

Verifique se todas as alterações foram feitas corretamente:
1. Verificar se o middleware de auth está aplicado
2. Testar o endpoint de login
3. Executar os testes de auth

Avançado: Parsing automático do plano

Para projetos complexos, use um formato de plano estruturado:

## Plano ID: AUTH-001
## Status: AGUARDANDO_APROVAÇÃO
## Prioridade: ALTA
## Tempo estimado: 30 minutos

### Escopo
- Adicionar autenticação baseada em JWT
- Implementar login/logout/register
- Adicionar fluxo de redefinição de senha

### Alterações

#### Arquivo: src/middleware/auth.ts (NOVO)
```typescript
import jwt from 'jsonwebtoken';

export const verifyToken = (req, res, next) => {
  // Implementação
};

Arquivo: src/routes/auth.ts (NOVO)

// Endpoints de login, register, logout

Arquivo: src/app.ts (MODIFICAR)

• Linha 15: Adicionar app.use('/auth', authRoutes)

Rollback

• Excluir: src/middleware/auth.ts
• Excluir: src/routes/auth.ts
• Restaurar: src/app.ts linha 15

Testes

• Login com credenciais válidas
• Login com credenciais inválidas
• Acessar rota protegida sem token
• Acessar rota protegida com token válido

## Integração com controle de versão

### Checkpoint pré-execução

Antes de executar um plano:

```bash
# Criar branch de checkpoint
git checkout -b plan/auth-implementation

# Commitar o estado atual
git add -A && git commit -m "checkpoint: antes da implementação de auth"

Verificação pós-execução

# Revisar as alterações
git diff

# Se algo estiver errado, reverter
git checkout -- .

# Ou voltar ao checkpoint
git reset --hard HEAD~1

Workflow de equipe

Para revisões de código

1. O desenvolvedor cria um plano no Cursor
2. O desenvolvedor cola o plano na descrição da PR
3. O revisor aprova o plano antes da execução
4. O desenvolvedor executa com o workflow Plan vs Act
5. O revisor verifica se a execução corresponde ao plano

Template de PR

## Plano
[Cole o plano gerado pela IA aqui]

## Execução
- [ ] Todas as alterações planejadas implementadas
- [ ] Nenhuma modificação não planejada
- [ ] Testes passam
- [ ] Plano corresponde à execução

## Verificação
[Descrever os testes executados]

Armadilhas comuns

Armadilha	Solução
O agente pula o planejamento	Impor com regras e restrições de modo
Os planos são muito vagos	Exigir caminhos de arquivo e números de linha específicos
Fadiga de aprovação do usuário	Agrupar alterações relacionadas em planos únicos
A execução desvia do plano	Comparar o diff com o plano após a execução
Muita ida e volta	Permitir desvios menores, sinalizar desvios maiores

Lista de verificação de início rápido

• Criar .cursor/rules/plan-act-workflow.mdc
• Testar com uma tarefa pequena e segura
• Verificar se o agente respeita o modo somente leitura
• Praticar aprovação e rejeição de planos
• Configurar checkpoints git antes da execução
• Documentar o workflow para sua equipe

Recursos relacionados

• Cursor Agent Mode Masterclass
• Usando regras do Cursor efetivamente
• Guia de hooks de auto-revisão do Cursor