Guia completo do Cursor Composer: edição de vários arquivos e casos práticos

Usei o Cursor durante três meses até perceber que vinha “desperdiçando” a ferramenta.

Antes, quando uma funcionalidade exigia mudanças em cinco arquivos — componente, API, tipos, testes e configuração —, eu perguntava tudo no Chat, um arquivo por vez, e copiava e colava cada trecho de código. O mouse ia e voltava entre os arquivos, e meus dedos não saíam de Cmd+C e Cmd+V. Era cansativo.

Um dia, um colega passou por mim, viu o que eu estava fazendo, ficou três segundos olhando para a tela e perguntou: “Por que você não usa o Composer?”

“Como assim?”

“Aquela janela flutuante do Cmd+I. Você descreve o que quer em uma frase, a IA identifica os arquivos que precisam mudar e altera todos eles.”

Fiquei paralisado.

Ele fez uma demonstração: abriu o Composer, referenciou alguns arquivos relacionados com @ e digitou “altere esta lógica de login para oferecer verificação por e-mail”. Depois pressionou Enter. A IA pensou por alguns segundos e alterou de uma só vez o componente, a API e os tipos. Em dez minutos, estava pronto.

Eu levava uma hora.

Naquele momento, percebi que durante três meses eu havia usado apenas 20% do Cursor. Era como dirigir uma Ferrari sem sair da primeira marcha.

O que é o Composer e por que você precisa dele

A diferença essencial entre Composer e Chat

Vamos começar com uma analogia.

O Chat é como um consultor de IA sentado ao seu lado para responder perguntas. Você pergunta “como posso otimizar este código?”, recebe sugestões e faz a alteração por conta própria.

O Composer é uma equipe de execução com IA. Você diz “troque todas as janelas deste prédio por janelas do chão ao teto”; ele faz o trabalho e depois avisa: “Terminei. Pode revisar.”

Essa é a diferença essencial: um aconselha; o outro executa.

Veja a comparação:

Viu que o histórico de conversas não é salvo? Esse foi o maior problema que enfrentei. Mais adiante, explico como evitá-lo.

Três recursos principais do Composer

Recurso 1: compreensão entre arquivos

O Chat só enxerga o arquivo aberto no momento. O Composer consegue enxergar o projeto inteiro.

Por exemplo, se você disser “adicione uma funcionalidade de login”, o Chat perguntará “qual arquivo devo alterar?”. Já o Composer dirá: “Preciso alterar estes cinco arquivos: Login.tsx, auth.ts, user.types.ts, api/auth.ts e App.tsx”.

Ele sabe onde estão o componente, os tipos, a API e as rotas. E altera tudo para você.

Recurso 2: alterações em nível de projeto

Quando o Chat modifica código, você precisa copiar e colar manualmente. O Composer aplica as mudanças diretamente nos arquivos; você só precisa escolher Accept ou Reject.

É a diferença entre receber uma planta de reforma e receber a obra pronta para vistoria.

Recurso 3: raciocínio inteligente no modo Agent

Com o modo Agent ativado, o Composer pode:

• executar comandos shell, como npm install e git status;
• pesquisar o repositório inteiro e encontrar todos os usos de uma função;
• analisar dependências de forma autônoma;
• criar ou excluir arquivos.

O modo Agent é como colocar um encarregado à frente da equipe: ele toma decisões e procura as ferramentas necessárias. Mas também pode “reformar demais”. Veremos como controlar isso.

Três cenários em que você deve usar o Composer

Cenário 1: desenvolver uma funcionalidade que envolve vários arquivos

Tarefa: adicionar comentários.

Com o Chat:

1. Perguntar quais arquivos precisam mudar.
2. Receber uma lista de cinco arquivos.
3. Abrir cada arquivo.
4. Pedir no Chat: “Crie o componente Comments”.
5. Copiar e colar o código.
6. Pedir: “Crie a API de comentários”.
7. Copiar e colar.
8. Repetir cinco vezes.

Exaustivo.

Com o Composer:

1. Abra o Composer com Cmd+I.
2. Digite: “Adicione comentários para que usuários possam publicar, excluir e visualizar comentários”.
3. Pressione Enter.
4. A IA identifica os arquivos que precisam mudar e altera todos eles.
5. Você revisa o diff e usa Accept.

Tudo pronto em dez minutos.

Cenário 2: refatoração de código

Tarefa: migrar o gerenciamento de estado de Redux para Zustand.

Com o Chat, é quase impossível concluir: são mais de 20 arquivos para alterar manualmente, com grande risco de esquecer algo ou cometer erros.

Com o Composer:

@src/store
@src/components

Migre o store do Redux para Zustand:
1. Preserve a estrutura atual do state
2. Preserve a API atual
3. Remova a dependência do redux

Ative o modo Agent. A IA analisa as dependências, altera os arquivos e testa se o projeto funciona. Tudo pronto em 20 minutos.

Cenário 3: alterações em lote

Tarefa: padronizar o tratamento de erros e adicionar try-catch a todas as chamadas de API.

Com o Chat, você altera um arquivo por vez e pode esquecer algum deles. Precisa controlar por conta própria o que já foi alterado.

Com o Composer:

@src/api

Adicione tratamento de erros padronizado a todas as chamadas de API:
- Envolva-as com try-catch
- Padronize o formato das mensagens de erro
- Registre os erros em log

Quinze arquivos resolvidos de uma só vez.

Composer ou Chat: regra de decisão em 5 segundos

Agora você já conhece a diferença entre Composer e Chat. Mesmo assim, na hora de programar, pode surgir a dúvida: “Uso Cmd+L ou Cmd+I?”

Use este fluxo de três etapas para decidir em cinco segundos.

Fluxo de decisão

Etapa 1: quantos arquivos estão envolvidos?

• Um arquivo → continue avaliando.
• Dois ou mais → Composer.

É simples assim. Se a mudança atravessa arquivos, use o Composer.

Etapa 2: você quer fazer uma pergunta ou alterar código?

• Perguntar, aprender, entender ou depurar → Chat.
• Gerar, alterar ou refatorar código → Composer.

O Chat é um consultor. O Composer é uma equipe de execução. Lembre-se disso.

Etapa 3: a mudança é grande?

• Mudança pequena, de poucas linhas → Chat + Cmd+K.
• Mudança grande, em um módulo inteiro → Composer.

Para renomear uma variável ou adicionar um comentário, Cmd+K basta. Não é preciso abrir o Composer.

Quatro tipos de tarefa adequados ao Chat

Cenário 1: perguntas rápidas

Você: “Este código tem algum bug?”
Chat: “Sim. Na linha 12, há um acesso fora dos limites do array.”

A resposta vem na hora. Você não quer mudar o código, apenas confirmar. O Chat é perfeito.

Cenário 2: estudo e compreensão

Você: “Explique como este algoritmo funciona.”
Chat: “Este é um quicksort. A ideia central é...”

Aprender algo novo é um dos pontos fortes do Chat. Ele explica com paciência e também pode dar exemplos.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Cenário 3: depuração de um arquivo

Você: “Ajude a otimizar esta função.”
Chat: “Você pode usar memoization para armazenar o resultado...”

Você mesmo pode aplicar a alteração. Não é necessário automatizar tudo com o Composer.

Cenário 4: revisão de código

Você: “Quais problemas potenciais existem aqui?”
Chat: “A linha 15 não trata null e há risco de vazamento de memória na linha 28...”

O Chat consegue encontrar muitos problemas ao revisar código.

Quatro tipos de tarefa adequados ao Composer

Cenário 1: desenvolvimento de novas funcionalidades

Funcionalidades que atravessam vários arquivos. Já vimos isso acima.

Cenário 2: refatoração de código

Grandes mudanças estruturais, como:

• dividir arquivos grandes;
• juntar arquivos pequenos;
• reorganizar diretórios;
• padronizar nomes.

Essas tarefas estão além do que o Chat consegue executar sozinho.

Cenário 3: migração de dependências

Substituir uma biblioteca ou um framework, por exemplo:

• axios → fetch;
• moment.js → dayjs;
• styled-components → Tailwind CSS;
• Redux → Zustand.

Isso pode envolver dezenas de arquivos: é o terreno do Composer.

Cenário 4: alterações em lote

Aplicar a mesma mudança em vários trechos semelhantes, por exemplo:

• trocar todos os console.log por logger;
• trocar todos os var por const;
• converter componentes de classe em componentes funcionais.

Três casos comparativos

Caso 1: alterar a forma de chamar uma API

Tarefa: substituir todo o axios por fetch.
Arquivos envolvidos: 15.

Com o Chat, seria preciso operar arquivo por arquivo e haveria risco de esquecer algum. Você precisaria lembrar sozinho quais arquivos já foram alterados.

Com o Composer, basta uma instrução: @src/api substitua todo o axios por fetch. A IA faz a alteração em lote; você só revisa o diff.

Conclusão: Composer.

Caso 2: depurar uma função

Tarefa: encontrar o bug na função que calcula o preço total.
Arquivos envolvidos: um.

Com o Chat, basta colar o código para receber a resposta: “Na linha 12, o cálculo do imposto está errado; deve ser total * 0.1”.

Com o Composer, seria preciso abri-lo, esperar a análise, a alteração e a aplicação. É pesado demais e desperdiça tempo.

Conclusão: Chat.

Caso 3: adicionar um sistema de permissões

Tarefa: implementar controle de acesso RBAC.
Arquivos envolvidos: mais de dez, entre componentes, middleware, banco de dados e API.

Com o Chat, é quase impossível concluir. Você teria de perguntar e alterar tudo individualmente, além de garantir por conta própria a consistência da lógica.

Com o Composer no modo Agent, a IA entende a arquitetura geral, cria o middleware, altera a API, atualiza os componentes e adiciona as verificações de permissão. Você só precisa dizer: “Implemente um sistema de permissões baseado em papéis; administradores podem criar, excluir, alterar e consultar, enquanto usuários comuns só podem consultar”.

Conclusão: Composer no modo Agent.

Como abrir o Composer corretamente

Configuração inicial em três etapas

Depois de instalar o Cursor, não comece pelo Composer imediatamente. Faça primeiro alguns ajustes.

Etapa 1: escolha o modelo

Para o Composer, recomenda-se o Claude 3.7 Sonnet.

Por quê?

• Raciocínio forte: entende relações complexas entre arquivos.
• Baixa taxa de erros: tem menor probabilidade de alterar o código incorretamente.
• Boa compreensão de vários arquivos: sabe quais arquivos devem mudar em conjunto.

Evite o o1 e o o1-mini, pois eles não são compatíveis com o Composer. O Cursor trocará automaticamente para outro modelo, e o resultado poderá ficar abaixo do esperado.

Etapa 2: ative o modo Agent, se quiser

Abra Cursor Settings → Beta → Agent.

Depois de ativado, o Composer pode:

• executar comandos shell, como npm install e git status;
• pesquisar no repositório com Cmd+Enter e encontrar todos os usos de uma função;
• criar ou excluir arquivos;
• analisar a estrutura do projeto de forma autônoma.

O modo Agent é como entregar uma caixa de ferramentas à IA. Ela consegue trabalhar por conta própria, mas também tem mais chance de “exagerar na obra”. Veremos como controlar isso.

Etapa 3: conheça os planos

• Gratuito: o Composer tem uso limitado, com poucas solicitações por dia.
• Pro: 500 solicitações premium por mês, o suficiente para a maioria das pessoas.
• Business: sem limite.

Para quem usa a ferramenta intensamente, recomendo o plano Pro. Eu mesmo usava entre 300 e 400 solicitações por mês.

Entendendo a interface

A interface do Composer se parece com isto:

┌─────────────────────────────────┐
│  Composer  [Normal] [Agent]     │  ← troca de modo
├─────────────────────────────────┤
│  📝 campo de entrada             │
│  referências @ a arquivos       │
├─────────────────────────────────┤
│  💬 histórico da conversa        │
│  📄 prévia do diff               │
│  ✅ Accept  ❌ Reject            │
└─────────────────────────────────┘

No canto superior direito, é possível alternar entre os modos Normal e Agent.

A prévia do diff, na parte inferior, é muito importante: ela mostra o que mudou em cada arquivo. Nunca use Accept All diretamente. Falaremos sobre esse risco mais adiante.

Como aproveitar as referências @

O símbolo @ é um recurso central do Composer. Ele permite referenciar vários tipos de conteúdo.

@Files: referenciar arquivos específicos

@src/components/Header.tsx
Torne este componente responsivo

A IA entende que deve alterar apenas esse arquivo e não mexe em outros lugares.

@Folders: referenciar uma pasta inteira

@src/utils
Refatore esta biblioteca de utilitários e divida os arquivos por funcionalidade

A IA examina todos os arquivos da pasta, entende a estrutura geral e faz a refatoração.

@Code: referenciar um bloco de código

Selecione um trecho e pressione Cmd+I; ele será referenciado automaticamente:

@[código da função selecionada]
Otimize o desempenho desta função

Isso é especialmente útil para otimizações pequenas e bem delimitadas.

@Web: referenciar conteúdo da web

@https://docs.react.dev/reference/react/useEffect
Refatore este effect seguindo as boas práticas da documentação oficial do React

A IA lê a página e altera o código conforme a documentação. Eu usava muito esse recurso para fazer mudanças orientadas pela documentação oficial e reduzir erros.

@Docs: referenciar a documentação do projeto

@README.md
Implemente esta funcionalidade de acordo com a documentação

Se o projeto tiver uma especificação, faça referência a ela para que a IA siga as regras.

@Codebase: pesquisar o repositório inteiro

Pressione Cmd+Enter e digite:

Encontre todos os usos de localStorage e substitua-os por IndexedDB

No modo Agent, a IA pesquisa todo o projeto, encontra o código relacionado e altera tudo em conjunto.

Modos Normal e Agent

Qual é a diferença entre eles?

Modo Normal:

• adequado para tarefas explícitas;
• a IA altera apenas os arquivos indicados;
• mais controlável e com menos mudanças acidentais;
• mais rápido;
• consome menos tokens.

Modo Agent:

• adequado para tarefas complexas que exigem raciocínio;
• a IA pode pesquisar código, executar comandos e criar arquivos de forma autônoma;
• é mais inteligente, mas pode ultrapassar o escopo esperado;
• mais lento;
• consome mais tokens.

Como escolher:

Tarefa simples → Normal. Por exemplo: “altere o estilo deste componente” ou “adicione tratamento de erros”.

Refatoração complexa → Agent. Por exemplo: “migre o Redux para Zustand” ou “implemente um sistema de permissões”.

Está em dúvida → tente primeiro o Normal. Se não funcionar, use Agent.

Eu usava o Normal em 80% do tempo e o Agent em 20%. O Normal costuma bastar; o Agent é mais pesado.

Cinco regras de ouro para editar vários arquivos

Esta é a parte mais importante. Depois de enfrentar vários problemas, resumi cinco regras que evitam 90% deles.

Regra 1: divida a tarefa

❌ Exemplo incorreto:

“Refatore o projeto inteiro, migre para TypeScript, otimize o desempenho e adicione testes”

Uma instrução assim confunde o Composer. Ele não sabe por onde começar nem em que ordem trabalhar. O resultado tende a ser uma bagunça que pode exigir duas horas de reversão.

✅ Forma correta:

Divida em quatro conversas:

1ª: “Converta todos os arquivos da pasta src/utils para TypeScript”
2ª: “Adicione testes unitários para utils”
3ª: “Otimize o desempenho do componente Header”
4ª: “Refatore as chamadas de API e padronize o tratamento de erros”

Conclua um objetivo pequeno por vez e faça um git commit. O processo fica claro, controlável e fácil de reverter.

Por que dividir?

• Evita interpretações erradas da IA, que pode perder o foco com instruções demais.
• Facilita a revisão gradual, pois diffs pequenos deixam os problemas visíveis.
• Facilita a reversão, pois você desfaz apenas uma etapa.
• Reduz o consumo de tokens, porque tarefas menores exigem menos raciocínio.

Minha regra prática: uma conversa do Composer não deve envolver mais de dez arquivos. Acima disso, divida.

Regra 2: delimite o escopo

Use referências @ para especificar os arquivos.

Por exemplo, para mudar funcionalidades de usuário:

@src/components/User
@src/types/user.ts
@src/api/user.ts

Migre as APIs de usuário de RESTful para GraphQL

Assim, a IA sabe que deve alterar somente esses três lugares.

Sem um escopo claro, ela pode decidir mexer em outros arquivos. Se você disser apenas “padronize as chamadas de API”, por exemplo, ela pode alterar até APIs de bibliotecas de terceiros e quebrar o projeto.

Vantagens:

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

• a IA não altera outros arquivos por engano;
• as mudanças permanecem controladas;
• há menos surpresas.

Hoje, minha primeira ação ao usar o Composer é referenciar os arquivos relacionados com @. Transforme isso em hábito.

Regra 3: revise cada arquivo

Depois que o Composer terminar, nunca clique diretamente em Accept All.

Eu sei que é tentador. A IA mudou 20 arquivos; com um clique, você aplica tudo. Parece ótimo.

Mas há um problema.

Um caso real:

Certa vez, pedi ao Composer: “Substitua todos os console.log por um logger personalizado”.

Ele alterou 30 arquivos.

Sem olhar, usei Accept All.

Resultado:

• os console.log de bibliotecas de terceiros também foram removidos;
• parte do código de depuração foi excluída por engano;
• o projeto deixou de funcionar.

Levei uma hora para reverter, investigar e corrigir manualmente.

Fluxo correto:

1. Abra a prévia do diff de cada arquivo
2. Confira as mudanças linha por linha
3. Depois de confirmar, use Accept apenas nesse arquivo
4. Se encontrar um problema, use Reject e reformule a solicitação

Sim, é lento. Se 20 arquivos mudaram, você precisará conferir 20 diffs. Mas isso evita 90% dos acidentes.

Meu hábito passou a ser preparar um café depois que o Composer termina e revisar tudo com calma. Não adianta ter pressa.

Regra 4: faça commit imediatamente

Depois de cada tarefa pequena, faça um git commit.

# Depois de concluir uma alteração do Composer
git add .
git commit -m "feat: migrate user API to GraphQL"

Por que isso é importante?

O Composer não salva o histórico da conversa. Ao atualizar a tela, ele desaparece.

Se você mudou dez arquivos, não fez commit e a janela travou, a conversa será perdida. Você não lembrará exatamente o que mudou nem onde parou, e talvez precise começar de novo.

Com um commit a cada etapa:

• fica fácil reverter com git reset --hard HEAD;
• fica fácil rastrear cada mudança com git log;
• se a conversa do Composer desaparecer, o código continuará salvo.

Meu ritmo passou a ser: Composer termina → reviso o diff → Accept → git commit. Transforme isso em memória muscular.

Regra 5: preserve o contexto

O problema:

O Composer não salva o histórico. Ao atualizar a tela, as conversas anteriores desaparecem.

Se você disser “continue a refatoração anterior”, a IA responderá: “Qual refatoração? Não sei do que você está falando”.

Soluções:

Solução 1: faça capturas das conversas importantes

Antes de começar uma tarefa complexa, registre suas instruções ao Composer. Se a conexão cair no meio, você conseguirá lembrar o objetivo.

Solução 2: planeje tarefas complexas no Chat e execute-as no Composer

O histórico do Chat é salvo. Você pode discutir a solução com a IA e só depois usar o Composer.

Por exemplo:

Conversa no Chat:
Você: “Quero migrar o axios para fetch. O que devo observar?”
IA: “É preciso cuidar do tratamento de erros, interceptors e tipos...”
Você: “Certo. Crie um plano de migração.”
IA: “Primeiro... Segundo... Terceiro...”

Depois, siga o plano passo a passo no Composer. O plano continuará no Chat mesmo se o Composer perder o contexto.

Solução 3: registre a intenção da mudança no README do projeto

Eu mantinha uma seção “Registro de refatorações” no README:

## Registro de refatoração de 2026-01-10
- Tarefa: migrar axios para fetch
- Instrução ao Composer: “Substitua todas as chamadas do axios pela API fetch nativa, preservando a mesma lógica de tratamento de erros”
- Arquivos envolvidos: src/api/*.ts
- Resultado: 15 arquivos migrados com sucesso

Ao revisitar o projeto no futuro, você saberá por que a mudança foi feita.

Sete problemas comuns do Composer e como evitá-los

Nesta seção, reuni todos os problemas que enfrentei. Basta seguir as recomendações.

Problema 1: o histórico de conversas não é salvo

O problema:

A conversa do Composer desaparece quando a tela é atualizada.

Se a janela travar no meio de uma alteração, se você fechar a aba por engano ou se o Cursor encerrar, toda a conversa anterior será perdida.

Como evitar:

✅ Faça capturas das instruções importantes.
✅ Planeje no Chat e registre o raciocínio.
✅ Use a mensagem do git commit para registrar a intenção de cada mudança.
✅ Divida tarefas complexas em conversas pequenas, cada uma com no máximo dez arquivos.

Problema 2: a atualização de arquivos é interrompida

O problema:

O Composer pode travar no meio de uma mudança.

A causa pode ser uma oscilação da rede, uma falha do serviço de IA ou até o barulho da ventoinha do computador confundindo a IA — esta última é brincadeira.

O resultado é um projeto pela metade: alguns arquivos foram alterados, outros não.

Como evitar:

✅ Faça git commit antes da mudança para poder reverter.
✅ Verifique se a rede está estável, pois o Composer depende bastante da conexão.
✅ Divida a tarefa e reduza o número de arquivos por alteração; menos arquivos são atualizados mais rápido e têm menor chance de interrupção.
✅ Use git diff para conferir quais mudanças realmente foram feitas.

Passei por duas interrupções. Na primeira, sem commit, levei duas horas para corrigir manualmente. Na segunda, com commit, reverti em um segundo com git reset.

Problema 3: o modelo muda automaticamente

O problema:

Alguns modelos, como o o1, não são compatíveis com o Composer.

Se você selecionar o1, o Cursor trocará automaticamente para outro modelo. Você pensará que está usando o1, mas na verdade estará usando GPT-4o, e o resultado poderá ficar abaixo do esperado.

Como evitar:

✅ Use sempre o Claude 3.7 Sonnet, a melhor combinação com o Composer.
✅ Confira o nome do modelo no canto superior direito; não presuma que a seleção foi mantida.
✅ Defina o modelo padrão em Cursor Settings.

Eu usava apenas o Claude 3.7 Sonnet: estável, confiável e com baixa taxa de erros.

Problema 4: perda de contexto

O problema:

Você conversa várias vezes no Composer:

1ª: “Migre a API de usuários para GraphQL”
2ª: “Continue e migre também a API de comentários”

A IA responde: “Qual API de usuários? Não sei do que você está falando”.

O contexto foi perdido.

Como evitar:

✅ Referencie novamente os arquivos relacionados com @ em cada conversa.
✅ Diga claramente: “Com base na alteração anterior, continue…”
✅ Se necessário, abra uma conversa nova e explique todo o contexto outra vez.

Passei a tratar cada conversa como se fosse a primeira e sempre explicar o contexto.

Problema 5: falha na pesquisa de arquivos

O problema:

Você pressiona Cmd+Enter e digita: “@Codebase encontre todos os usos de axios”.

A IA responde: “Não encontrei”.

Mas há 15 arquivos usando axios.

Como evitar:

✅ Use @Files para indicar os arquivos explicitamente, sem depender da pesquisa.
✅ Confira .cursorrules e .gitignore, pois alguns arquivos podem estar excluídos.
✅ Em projetos grandes, divida por módulo em vez de pedir à IA que pesquise o projeto inteiro.

A pesquisa com @Codebase não era muito confiável em projetos grandes. Por isso, eu preferia @Files.

Problema 6: o modo Agent é agressivo demais

O problema:

Com o modo Agent ativado, a IA pode decidir por conta própria:

• criar arquivos desnecessários;
• excluir código que você considera importante;
• fazer mudanças além do esperado.

Por exemplo, você diz “refatore o módulo de usuários” e a IA apaga e recria toda a pasta src/user.

Como evitar:

✅ Em tarefas complexas, experimente primeiro o modo Normal.
✅ Reserve o modo Agent para refatorações bem definidas, como uma migração de dependência.
✅ Revise cada diff e use Reject assim que encontrar uma mudança inadequada.

O modo Agent é poderoso, mas também arriscado. Eu o usava apenas em tarefas muito claras, como migrações de dependências.

Problema 7: falta de espaço em disco

O problema:

O Composer cria arquivos temporários.

Se não houver espaço suficiente no disco, a atualização falhará no meio e aparecerá um erro de falta de espaço.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Como evitar:

✅ Limpe periodicamente diretórios temporários como node_modules e dist.
✅ Mantenha mais de 5 GB disponíveis.
✅ Use df -h para conferir o uso do disco.

Só enfrentei esse problema uma vez, mas ele é difícil de identificar. A mensagem não era clara, e levei bastante tempo para descobrir que o disco estava cheio.

Caso prático: migrar do axios para a API fetch

Depois de tanta teoria, vamos a um caso prático.

Contexto:

• Projeto: sistema de blog em Next.js.
• Tarefa: substituir todas as chamadas do axios pela API fetch nativa.
• Arquivos envolvidos: 15 arquivos de API.
• Tempo estimado: duas horas manualmente ou 20 minutos com o Composer.

Vou mostrar, etapa por etapa, como concluir a tarefa com o Composer.

Etapa 1: planeje no Chat

Não abra o Composer ainda. Primeiro, discuta a tarefa com a IA no Chat.

Eu: Quero substituir todo o axios do projeto pela API fetch. O que preciso observar?

Chat:
1. O tratamento de erros do fetch é diferente do axios; é preciso verificar response.ok manualmente
2. Por padrão, o fetch não rejeita respostas 4xx/5xx; é preciso tratá-las
3. É preciso definir Content-Type manualmente
4. Interceptors devem ser implementados com uma função personalizada

Recomendo criar primeiro uma função utilitária fetchWrapper.

Ótimo. O Chat sugeriu uma abordagem: criar a função utilitária e depois substituir as chamadas em lote.

Etapa 2: crie a ferramenta fetchWrapper

Abra o Composer com Cmd+I:

@src/utils

Crie um arquivo fetchWrapper.ts que ofereça uma API semelhante ao axios:
- Trate JSON automaticamente
- Padronize o tratamento de erros
- Ofereça suporte a interceptors
- Seja compatível com as chamadas atuais do axios

Pressione Enter.

O Composer pensou por alguns segundos e criou fetchWrapper.ts. O código estava bom.

Revisei:

• ✅ Tipos completos.
• ✅ Tratamento de erros correto.
• ✅ Design da API adequado.

Accept.

git commit -m "feat: add fetchWrapper utility"

Etapa 3: migre por módulo

Não altere todos os 15 arquivos de uma vez. Divida a tarefa.

Comece pelos módulos posts e comments:

@src/api/posts.ts
@src/api/comments.ts
@src/utils/fetchWrapper.ts

Migre as chamadas de API de posts e comments do axios para fetchWrapper, preservando as mesmas assinaturas de função e a lógica de tratamento de erros.

Pressione Enter.

O Composer começou a trabalhar e alterou três arquivos.

Etapa 4: revise o diff

Esta é a etapa mais importante.

Revisei cada arquivo:

posts.ts:

• import axios mudou para import { fetchWrapper } ✅
• axios.get() mudou para fetchWrapper.get() ✅
• A lógica de tratamento de erros foi preservada ✅
• As assinaturas das funções permaneceram iguais ✅

Accept.

comments.ts:

• Mudanças semelhantes, tudo correto ✅

Accept.

fetchWrapper.ts:

• A importação foi referenciada corretamente ✅

Etapa 5: teste

npm run dev

Abra o navegador e teste posts e comments:

• carregar a lista de artigos ✅
• abrir os detalhes de um artigo ✅
• publicar um comentário ✅
• excluir um comentário ✅

Tudo funciona.

git commit -m "feat: migrate posts and comments API to fetch"

Etapa 6: migre os outros módulos

Repita as etapas de três a cinco para:

• módulo users;
• módulo auth;
• módulo settings.

Depois de cada módulo, revise, teste e faça commit.

Em 25 minutos, os 15 arquivos estavam prontos.

Problemas encontrados

Problema 1: o Composer também alterou o axios de uma biblioteca de terceiros

Na primeira tentativa, não delimitei o escopo com @Files, e o código dentro de node_modules também foi alterado.

Solução: reformulei a instrução para “altere apenas o código dentro de src; não altere node_modules”.

Problema 2: a lógica de tratamento de erros desapareceu

O tratamento de erros do fetch é diferente do axios. Uma substituição direta deixou alguns erros sem captura.

Solução: especifiquei na instrução “preserve a mesma lógica de tratamento de erros e verifique response.ok manualmente”.

Problema 3: faltavam tipos

O TypeScript apresentou erros porque os tipos de fetchWrapper estavam incompletos.

Solução: usei o Chat separadamente para gerar os tipos e apliquei-os em fetchWrapper.ts com Cmd+K.

Resultado final

✅ Os 15 arquivos foram migrados.
✅ Todas as funcionalidades da API continuaram funcionando.
✅ Tempo total: 25 minutos, incluindo depuração.
✅ Code review: nenhum problema.
✅ O bundle ficou menor: axios ocupa 30 KB, enquanto fetch é uma API nativa.

Manualmente, eu levaria cerca de duas horas. Com o Composer, foram 25 minutos: uma produtividade cinco vezes maior.

Resumo do aprendizado

1. Planeje tarefas complexas no Chat.
2. Execute por etapas e faça git commit após cada uma.
3. Delimite os arquivos com referências @.
4. Revise cada diff para evitar mudanças inesperadas.
5. Teste antes de seguir para a próxima etapa.

Essas cinco práticas valem para qualquer tarefa no Composer. Guarde-as.

Conclusão

Sinceramente, depois de aprender a usar o Composer, minha produtividade no desenvolvimento pelo menos triplicou.

Antes, uma funcionalidade que atravessava vários arquivos exigia alternar entre eles, copiar e colar código, e ainda havia risco de erros e esquecimentos. Era cansativo.

Agora, uma única instrução faz a IA identificar e alterar os arquivos necessários. Eu só preciso revisar o diff e usar Accept. Tudo pronto em dez minutos.

Lembre-se de cinco princípios:

1. Vários arquivos → use o Composer
   Se a mudança atravessa arquivos, não desperdice tempo no Chat.

2. Divida a tarefa → não altere coisas demais de uma vez
   Não envolva mais de dez arquivos em uma conversa.

3. Revise cada arquivo → não use Accept All diretamente
   Mesmo que demore, é melhor do que lidar com um acidente.

4. Faça commit logo → um git commit após cada etapa
   O Composer não salva conversas; salve o código.

5. Preserve o contexto → registre conversas importantes
   Capturas, planejamento no Chat e registros no README formam uma proteção em três camadas.

Guarde estes dois atalhos:

• Cmd/Ctrl + L → Chat, para fazer perguntas.
• Cmd/Ctrl + I → Composer, para alterar código.

Regra de decisão em 5 segundos:

Quantos arquivos estão envolvidos?
 → 1 → É uma pergunta ou uma alteração de código?
    → Pergunta → Chat
    → Alteração → É uma mudança grande?
       → Pequena → Chat + Cmd+K
       → Grande → Composer
 → 2 ou mais → Composer

Não tenha medo do Composer.

No começo, ele pode parecer “inteligente demais e difícil de controlar”.

Mas, depois de usá-lo algumas vezes, você perceberá que, seguindo estas regras, o Composer é controlável e muito útil.

Sugestão prática:

Experimente agora:

1. Abra o Cursor e pressione Cmd+I.
2. Escolha uma tarefa pequena para praticar, como renomear variáveis em lote ou padronizar o estilo do código.
3. Guarde as cinco regras e as sete recomendações deste artigo.
4. Sempre que surgir uma mudança entre vários arquivos, pense primeiro no Composer.

Não se limite ao Chat.

O Composer é o principal recurso do Cursor.

Experimente para entender o quanto ele pode ajudar.