Cursor Composer: Edição Multi-Arquivo que Realmente Funciona

A maioria dos usuários do Cursor fica no chat regular. Eles pedem uma função, copiam a saída, colam em um arquivo, repetem. Funciona para coisas pequenas. Mas quando você precisa mudar cinco arquivos para adicionar um recurso, esse fluxo de trabalho desmorona.

O Composer é a resposta do Cursor para isso. É um painel separado onde você descreve o que quer alterado, e o Cursor propõe edições em vários arquivos de uma vez. Você revisa, aceita ou rejeita cada mudança e segue em frente. Sem copiar e colar. Sem troca de contexto.

Este guia cobre fluxos de trabalho reais do fórum do Cursor. Sem linguagem de marketing. Apenas o que funciona.

Composer vs Chat Regular: A Diferença Real

O chat regular é Q&A. Você pergunta, o Cursor responde. Você ainda é quem move o código para os arquivos.

O Composer é ação. Você descreve o objetivo, o Cursor descobre quais arquivos tocar e o que mudar. Ele apresenta um diff. Você decide o que entra.

Recurso	Chat Regular	Composer
Sugere código	Sim	Sim
Edita arquivos diretamente	Não	Sim
Mudanças multi-arquivo	Não	Sim
Mostra diff antes de aplicar	Não	Sim
Checkpoint/rollback	Não	Sim
Melhor para	Perguntas, trechos únicos	Refatoração, recursos, atualizações em lote

O recurso principal é os checkpoints. O Composer salva um snapshot antes de fazer mudanças. Se a edição der errado, você reverte para o checkpoint em um clique. O chat regular não tem rede de segurança.

Como Abrir o Composer

Pressione Cmd/Ctrl + I ou clique no ícone do Composer na barra lateral esquerda. É um painel separado do chat — não confunda os dois.

Quando Usar o Composer

O Composer brilha quando uma tarefa toca mais de um arquivo. Cenários comuns:

• Refatoração — renomear uma prop entre componentes, extrair um utilitário compartilhado
• Trabalho de recurso — adicionar um novo endpoint de API precisa de arquivos de rota, controlador, serviço e teste
• Atualizações de padrão — mudar de fetch para um apiClient customizado em todos os lugares
• Mudanças de tipo — atualizar uma interface que se propaga por dez arquivos
• Limpeza de imports — reorganizar uma estrutura de módulos

Se você está copiando e colando código do chat em mais de dois arquivos, pare. Use o Composer em vez disso.

O Composer Não é para Tudo

Perguntas rápidas, one-liners, ou "explique esta regex" — o chat regular é mais rápido. O Composer tem overhead. Reserve-o para trabalho multi-arquivo.

Fluxo de Trabalho Real 1: Refatoração Cross-Arquivo

Você tem um tipo User em types.ts. Você quer renomear name para fullName porque está adicionando um campo displayName e a nomenclatura agora está confusa.

Isso toca:

• src/types.ts — a definição do tipo
• src/components/UserCard.tsx — exibe o nome
• src/components/UserProfile.tsx — também exibe
• src/api/users.ts — chamadas de API que recebem/enviam o campo
• src/lib/validators.ts — schema Zod para validação de usuário

Passo 1: Abra o Composer (Cmd/Ctrl + I).

Passo 2: Descreva a mudança:

Renomeie o campo `name` para `fullName` no tipo User e atualize todos os usos em toda a base de código. Não mude nenhum comportamento — isso é uma renomeação pura.

Passo 3: Revise o diff proposto. O Composer mostra cada arquivo com mudanças destacadas. Verifique que:

• Apenas name relacionado a usuários é renomeado (não outras props name)
• A camada de API ainda envia/recebe os dados corretos
• Nenhuma mudança de lógica se infiltrou

Passo 4: Aceite ou rejeite por arquivo. Se um arquivo parecer errado, rejeite apenas aquele e corrija manualmente.

Verifique o Diff com Cuidado

O Composer às vezes exagera. Ele pode renomear uma prop name em um componente não relacionado se o contexto parecer similar. Sempre escaneie o diff antes de aceitar.

Fluxo de Trabalho Real 2: Adicionando um Recurso em Vários Arquivos

Você quer adicionar "papéis de usuário" ao seu app. Usuários admin veem elementos de UI extras e podem acessar endpoints de API extras.

Arquivos envolvidos:

• src/types.ts — adicionar role: 'user' | 'admin' ao User
• src/api/auth.ts — incluir role no payload JWT
• src/components/Navbar.tsx — mostrar link de admin apenas para admins
• src/components/AdminPanel.tsx — novo componente
• src/hooks/useAuth.ts — expor flag isAdmin
• src/middleware/auth.ts — novo middleware para verificar papel de admin

Passo 1: Abra o Composer.

Passo 2: Dê um plano, não apenas um desejo:

Adicione papéis de usuário ao app:

1. Adicione `role: 'user' | 'admin'` ao tipo User em src/types.ts
2. Atualize a resposta de login em src/api/auth.ts para incluir role no payload JWT
3. Adicione um valor computado `isAdmin` em src/hooks/useAuth.ts
4. Atualize Navbar.tsx para mostrar condicionalmente um link "Admin" quando isAdmin for true
5. Crie src/components/AdminPanel.tsx com um dashboard admin placeholder
6. Crie src/middleware/auth.ts com um middleware requireAdmin que verifica o papel do JWT

Use os padrões existentes na base de código. Siga o mesmo estilo de tratamento de erros dos outros arquivos de API.

Passo 3: O Composer gera um diff multi-arquivo. Revise cada arquivo.

Passo 4: Se o novo AdminPanel.tsx parecer errado, rejeite-o e mantenha o resto. As edições do Composer são granulares.

Peça um Plano Primeiro

Antes de deixar o Composer codificar, peça para ele esboçar o plano. Adicione "Liste os arquivos que você vai mudar e por quê antes de fazer edições." Isso pega mal-entendidos cedo e não custa nada.

Fluxo de Trabalho Real 3: Atualização em Lote de Chamadas de API

Você começou com chamadas fetch brutas espalhadas pelo frontend. Agora você tem um apiClient customizado com headers de auth, tratamento de erros e URL base configurada. Você precisa migrar tudo.

Arquivos: potencialmente dezenas de locais de chamada de API.

Passo 1: Certifique-se de que apiClient existe e está importado corretamente em um arquivo primeiro. O Composer funciona melhor quando tem uma implementação de referência.

Passo 2: Abra o Composer e delimite a tarefa:

Substitua todas as chamadas `fetch` brutas em src/ pelo `apiClient` de src/lib/apiClient.ts.

Regras:
- Use os métodos existentes `apiClient.get`, `.post`, `.put`, `.delete`
- Remova o tratamento manual de JSON.stringify e response.json() — o apiClient faz isso
- Mantenha os mesmos caminhos de endpoint
- Preserve quaisquer headers customizados que já não estejam no apiClient

Comece com o diretório src/api/, depois src/hooks/ se necessário.

Passo 3: Revise em lotes. Não aceite 20 arquivos de uma vez sem olhar. O Composer é bom, mas não perfeito.

Passo 4: Execute sua suíte de testes após aceitar. Erros de tipo e comportamento em runtime podem divergir mesmo quando o diff parece limpo.

Não Migre Tudo de Uma Vez

Se você tem 50+ arquivos, divida em pedaços. "Migre src/api/ primeiro." Depois "Migre src/hooks/ em seguida." Lotes grandes são mais difíceis de revisar e mais fáceis de estragar.

Composer + Modo Agente: A Combinação Poderosa

O Composer e o modo Agente resolvem problemas diferentes. O Composer é para edições multi-arquivo direcionadas onde você sabe o que quer. O modo Agente é para tarefas abertas onde a IA precisa explorar, executar comandos e descobrir as coisas.

Mas eles trabalham juntos.

Padrão: Agente Planeja, Composer Executa

Use o modo Agente para descobrir o escopo de uma mudança:

Quero migrar de React Context para Zustand para gerenciamento de estado. Liste todos os arquivos que usam AuthContext e quais mudanças cada um precisa.

O modo Agente busca na base de código e te dá a análise. Depois você abre o Composer e executa as mudanças arquivo por arquivo, com revisão completa de diff.

Padrão: Composer para Refatoração, Agente para Verificação

Após uma grande refatoração no Composer, mude para o modo Agente:

Execute a suíte de testes e corrija quaisquer imports quebrados ou erros de tipo causados pela refatoração recente.

O modo Agente lida com a limpeza enquanto você revisa as mudanças do Composer.

Modo Agente Pode Usar o Composer

No modo Agente, o Cursor às vezes abre o Composer internamente para edições multi-arquivo. Você não controla isso diretamente, mas verá diffs no estilo do Composer aparecerem durante sessões de Agente. Revise-os da mesma forma.

Erros Comuns e Como Evitá-los

1. Prompts Vagos

Ruim: "Melhore a autenticação."

Bom: "Adicione um campo role ao tipo User, atualize a API de login para incluí-lo no JWT, e mostre um link de admin na Navbar para usuários admin."

Especificidade reduz surpresas.

2. Aceitar Sem Revisar

Os diffs do Composer parecem limpos, mas ele pode:

• Deletar um comentário que você queria manter
• Mudar a formatação em linhas não relacionadas
• Perder um caso extremo em um arquivo

Sempre escaneie o diff. Leva 30 segundos e evita retrabalho.

3. Muitos Arquivos de Uma Vez

O Composer lida bem com 10-15 arquivos. Além disso, a janela de contexto fica sobrecarregada e a qualidade cai. Divida tarefas grandes em pedaços lógicos.

4. Não Usar Checkpoints

Antes de começar uma grande sessão no Composer, aperte o botão de checkpoint. É um clique. Se a sessão der errado, a reversão é um clique de volta. Não há desculpa para pular isso.

Checkpoints Não São Commits do Git

Os checkpoints do Composer vivem dentro do Cursor. Eles não substituem o git. Faça commit no git antes de grandes trabalhos no Composer também. Use ambas as redes de segurança.

5. Ignorar Erros de Tipo Após Mudanças

As edições do Composer compilam talvez 90% das vezes. Os outros 10% introduzem incompatibilidades sutis de tipo, especialmente ao renomear ou mudar interfaces. Execute tsc ou seu linter após aceitar mudanças.

Referência Rápida

Ação	Atalho
Abrir Composer	Cmd/Ctrl + I
Aceitar mudança	Cmd/Ctrl + Y
Rejeitar mudança	Cmd/Ctrl + N
Criar checkpoint	Clique no ícone de checkpoint no painel do Composer
Reverter para checkpoint	Clique no ícone de reverter ao lado do checkpoint

Resumo

• Use o Composer para edições multi-arquivo. Use o chat regular para perguntas.
• Descreva exatamente o que você quer. Inclua caminhos de arquivo e restrições.
• Revise cada diff antes de aceitar.
• Crie checkpoints antes de sessões grandes.
• Divida tarefas grandes em pedaços.
• Combine Composer com modo Agente: Agente explora, Composer executa.

O Composer não é mágica. É uma ferramenta que remove o imposto de copiar e colar do trabalho multi-arquivo. Usado corretamente, economiza horas. Usado descuidadamente, cria trabalho de limpeza. A diferença está na etapa de revisão — não a pule.