Modo Agent do Cursor na prática: 10 dicas que levei três meses para aprender

Eu estava olhando para o quinto arquivo incorreto que o Agent acabara de gerar. Era a terceira tentativa de refatorar aquela funcionalidade naquela noite. Comecei a me perguntar se esse modo Agent, anunciado como capaz de “concluir tarefas complexas automaticamente”, estava ali para ajudar ou para me torturar.

Três meses antes, quando vi pela primeira vez o botão do modo Agent no Cursor, fiquei empolgado como se tivesse descoberto um novo continente. A ideia parecia ótima: eu explicaria uma necessidade à IA, ela criaria arquivos, instalaria dependências, escreveria código e corrigiria bugs, enquanto eu só precisaria tomar café e esperar o resultado. A realidade foi bem menos bonita: ela realmente trabalha sozinha, mas também consegue estragar tudo sozinha com frequência.

Depois desses três meses de tentativas, minha relação com o Agent finalmente passou de uma mistura de amor e ódio para uma parceria afinada. Hoje ele é meu assistente mais útil — desde que eu saiba conduzi-lo. Neste artigo, compartilho as armadilhas em que caí e as lições que aprendi nesse período.

O que é o modo Agent: primeiro, entenda a diferença para o Chat comum

Ao abrir o Composer do Cursor, você verá um botão “Agent” no canto superior direito. Não subestime esse botão: ativá-lo é como dar braços e pernas à IA.

No modo comum, a IA só oferece sugestões, como “você deve adicionar uma função aqui” ou “este bug pode estar acontecendo porque…”, e espera que você faça tudo manualmente. E no modo Agent? Ele coloca a mão na massa: cria arquivos, altera código, instala pacotes npm e executa comandos de uma só vez.

Parece ótimo, não é? Mas aí também está o problema. Imagine pedir a um estagiário para alterar o código. Ele de fato faz a mudança, mas, quando você confere, pensa: como assim ele também alterou outros arquivos? Por que mexeu na lógica central? O Agent é exatamente esse estagiário dedicado, porém não muito confiável.

Por isso, hoje uso o Chat para tarefas pequenas, como “explique este trecho de código”, e o Agent para operações em vários arquivos, como “adicione tipos TypeScript a todos os componentes”. O segredo é saber quando dar liberdade e quando acompanhar de perto.

Dica 1: a arte de dividir tarefas — não deixe o Agent tentar engolir tudo de uma vez

Meu maior erro foi entregar uma tarefa enorme ao Agent de uma só vez.

Eu queria refatorar um projeto antigo e disse diretamente: “migre este projeto de JavaScript para TypeScript, aproveite para melhorar o desempenho e ainda adicione uma funcionalidade de login”. O resultado? Ele começou a criar arquivos sem parar, alterou tudo por um bom tempo e, no fim, o projeto nem iniciava mais. Passei um dia inteiro revertendo o código.

Depois disso, aprendi. Hoje divido assim:

1. Primeira rodada: “adicione tipos TypeScript aos arquivos do diretório src/components”
2. Segunda rodada: “cuide das definições de tipo em src/utils”
3. Terceira rodada: “configure o tsconfig.json e confirme que o projeto compila normalmente”

Ao concluir cada etapa, executo os testes e só continuo depois de confirmar que está tudo certo. Assim, mesmo que algo dê errado, fica fácil identificar em qual etapa surgiu o problema.

Uma dica: ao dividir uma tarefa, tente limitar o impacto de cada parte a 3–5 arquivos. Acima disso, o Agent começa a perder detalhes. Você também não pediria a um estagiário que alterasse 20 arquivos de uma vez, certo? A lógica é a mesma.

Dica 2: gerenciamento de contexto — diga ao Agent o que ele deve analisar

O Agent tem um problema: não sabe quais arquivos são importantes e quais deveria ignorar. Seu projeto pode ter milhares de arquivos, com node_modules ocupando boa parte deles. Se o Agent examinar tudo, além de ficar extremamente lento, pode acabar se confundindo.

Antes de iniciar qualquer tarefa com o Agent, faço duas coisas:

Primeira etapa: configuro o .cursorignore

Esse arquivo informa ao Cursor quais diretórios não precisam ser indexados. Meu modelo é assim:

node_modules/
dist/
build/
.next/
.git/
*.log
coverage/

Com isso, o tempo de resposta do Agent melhora em mais de 30%. Pode parecer pouco, mas, ao longo do dia, a economia é considerável.

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Segunda etapa: uso @ para fazer referências precisas

Quando quero que o Agent altere um arquivo específico, uso @nome-do-arquivo para indicar o contexto claramente. Por exemplo: “siga o padrão de @api.ts e adicione tratamento de erros a @user.ts”. Assim, ele não sai procurando arquivos pelo projeto inteiro.

Certa vez, não usei @ e apenas disse “siga o padrão do arquivo de API”. Ele encontrou um arquivo antigo, de dois anos antes, e refez tudo seguindo aquele padrão obsoleto. Foi uma experiência inesquecível — pelos piores motivos.

Dica 3: o controle de versão é sua tábua de salvação

Aprendi esta dica da pior maneira.

Numa sexta-feira à tarde, pedi ao Agent que refatorasse um módulo e saí para uma reunião. Quando voltei, ele havia alterado mais de 30 arquivos. Pensei: ótimo, que eficiência. À noite, porém, os testes mostraram que a funcionalidade de login havia quebrado.

O problema era que eu não lembrava quais arquivos ele tinha alterado.

Naquela noite, comparei os arquivos um por um e levei três horas para encontrar a causa. Desde então, adotei uma regra inegociável: antes de usar o Agent, sempre faço um commit.

Meu fluxo atual é este:

# Faça um commit antes de começar
git add .
git commit -m "Backup antes de usar o Agent"

# Depois, deixe o Agent trabalhar

# Ao terminar, verifique as alterações
git diff

Se o Agent fizer algo errado, uso git reset --hard para voltar e começo novamente. Isso já me salvou inúmeras vezes.

Mais uma dica: faça o Agent alterar apenas um módulo funcional por vez e crie um commit logo depois. Assim, mesmo que haja um problema, o custo da reversão será pequeno. É como salvar um jogo com frequência: quanto mais pontos seguros, melhor.

Dica 4: aprenda a interromper — se o Agent errar, não o deixe cavar um buraco ainda maior

O Agent tem uma característica: depois que começa, avança em alta velocidade até o fim. Mesmo que algo dê errado no meio, ele pode insistir e continuar, distanciando-se cada vez mais da solução.

O caso mais absurdo que já vi aconteceu quando o Agent não encontrou uma dependência, inventou uma e continuou escrevendo código com base nela. Quando percebi, ele já havia alterado mais de dez arquivos partindo daquela premissa falsa.

Hoje eu o supervisiono. Depois que o Agent começa, acompanho os logs de saída:

• Viu um erro em vermelho? Pressione ESC imediatamente
• Ele criou um arquivo estranho? Interrompa na hora
• Alterou uma lógica central que não deveria? Pare sem hesitar

Depois de interromper, primeiro verifico o que já foi feito e avalio:

• Se as alterações estiverem boas, preservo essa parte, ajusto a instrução e continuo
• Se ele já tiver saído do caminho, uso git reset e reformulo a instrução

Não tenha receio de interrompê-lo. O Agent não é uma pessoa e não ficará chateado. Se você esperar até ele implementar toda uma lógica equivocada, o trabalho de limpeza será muito maior.

Dica 5: nunca confie cegamente no código do Agent

Sinceramente, a qualidade do código gerado pelo Agent é como uma caixa-surpresa: às vezes impressiona; em outras, assusta.

Quando comecei a usá-lo, tive a ilusão de que, por a IA ser tão inteligente, o código produzido provavelmente estaria correto. Depois de derrubar o ambiente de testes duas vezes, entendi que não há como pular a revisão de código.

Hoje, sempre que o Agent conclui uma tarefa, faço o seguinte:

Primeira etapa: executo os testes

npm test

É o básico, mas muita gente esquece. O Agent não necessariamente executará os testes por iniciativa própria; para ele, terminar de escrever o código pode parecer suficiente.

Segunda etapa: uso uma lista de revisão de código
Preparei esta lista para mim:

• ✓ Correção da lógica: a funcionalidade se comporta como esperado?
• ✓ Casos-limite: valores vazios e situações de exceção foram tratados?
• ✓ Desempenho: há algum gargalo evidente?
• ✓ Estilo de código: segue os padrões do projeto?
• ✓ Segurança: há riscos de injeção de SQL, XSS ou problemas semelhantes?

Terceira etapa: verifico se ele tomou algum atalho
O Agent gosta de atalhos. Se você pedir para “otimizar uma consulta ao banco de dados”, por exemplo, ele pode apenas adicionar cache, sem melhorar o SQL. É preciso examinar com cuidado o que realmente foi alterado e confirmar se o problema foi de fato resolvido.

Certa vez, descobri que o Agent havia pulado uma lógica de negócio complexa com // TODO: implementar. Esperto: soube até deixar o buraco para eu preencher.

Dica 6: a maneira certa de usar o Agent em projetos grandes

Em projetos pequenos, o Agent costuma oferecer uma vantagem enorme. Em projetos grandes, a história muda: centenas de arquivos, dependências complexas e estilos de código de várias pessoas podem deixá-lo perdido.

Tenho um projeto Next.js com mais de 200 componentes. No início, pedi diretamente ao Agent que “otimizasse o desempenho de todos os componentes”. Ele levou dez minutos apenas procurando arquivos, alterou alguns trechos irrelevantes e não tocou em nenhum componente central.

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

Começar agora →Anúncio

Depois de testar bastante, cheguei a uma abordagem específica para projetos grandes:

Estratégia 1: trabalhe por módulos
Não faça o Agent lidar com o projeto inteiro; delimite o alcance. Por exemplo:

• “Processe apenas os arquivos do diretório src/components/auth”
• “Altere somente o código relacionado ao login do usuário”

Assim, a atenção do Agent fica concentrada e o código irrelevante não interfere tanto.

Estratégia 2: use .cursorrules para definir limites
Crie um arquivo .cursorrules na raiz do projeto e informe as regras ao Agent:

# Regras do projeto
- Todos os componentes devem usar TypeScript
- Todas as chamadas de API devem usar @/lib/api
- Não altere a lógica central no diretório @/lib/core
- Novos arquivos devem conter comentários JSDoc

Com essas regras, o Agent tem menos espaço para agir de forma aleatória. É como entregar um guia de desenvolvimento a um estagiário: não garante que ele seguirá tudo, mas ao menos fornece uma referência.

Estratégia 3: priorize módulos independentes
Projetos grandes sempre têm módulos relativamente independentes, como funções utilitárias e componentes genéricos. São bons lugares para o Agent atuar: se algo der errado, o impacto será limitado; se der certo, todo o projeto se beneficia.

Dica 7: a combinação ideal entre Agent e Composer

Muita gente não entende a relação entre Agent e Composer. Na verdade, eles foram feitos para trabalhar juntos; não é preciso escolher apenas um.

Em resumo: o Composer é a bancada de trabalho, e o Agent é o botão de automação.

Hoje uso assim:

Cenário 1: refatoração em vários arquivos = Composer + Agent ON
Quando preciso alterar vários arquivos relacionados ao mesmo tempo, ativo o modo Agent no Composer. Uma tarefa como “adicione tratamento de erros e mecanismo de repetição a todas as chamadas de API” envolve operações em lote e vários arquivos, e o Agent pode aumentar bastante a produtividade.

Cenário 2: alteração profunda em um arquivo = Composer + Agent OFF
Se preciso alterar apenas a lógica complexa de um componente, desligo o Agent e uso o Composer comum. Assim, a IA sugere o código e eu o aplico manualmente, mantendo maior controle sobre cada etapa.

Cenário 3: pergunta rápida = Chat
Se só quero perguntar “o que este erro significa?” ou “como otimizar este código?”, uso diretamente o Chat; nem vale a pena abrir o Composer.

Uma dica prática: no Composer, você pode alternar o Agent a qualquer momento. Pode começar com ele ligado, deixá-lo trabalhar e, se notar algo errado, desligá-lo para assumir o controle. Seja flexível, em vez de insistir em um único caminho até o fim.

Dica 8: armadilhas que você deve evitar

Depois de tanto tempo usando o Agent, reuni algumas armadilhas comuns. Não significa que essas ações sejam sempre proibidas, mas você deve pensar duas vezes antes de executá-las.

Armadilha 1: deixar o Agent operar diretamente no banco de dados
Certa vez, por comodidade, pedi ao Agent que “removesse os registros duplicados do banco de testes”. Ele removeu — inclusive os dados do ambiente de produção. Por quê? O arquivo .env continha a conexão do banco de produção, e ele não mudaria o ambiente por mim.

Lição: faça manualmente as tarefas que envolvem banco de dados ou, no mínimo, crie um backup antes.

Armadilha 2: alterar um padrão em todos os arquivos de uma vez
“Troque var por let em todos os arquivos” parece simples, certo? Mas o Agent pode alterar var em comentários, strings e até bibliotecas de terceiros. O código pode até continuar funcionando, mas acabará cheio de mudanças estranhas.

Uma abordagem mais segura é pedir que ele altere primeiro um diretório e só amplie o escopo depois de confirmar que está tudo correto.

Armadilha 3: dar liberdade total ao Agent em um projeto sem testes
Já passei por isso. Refatorei um projeto antigo sem testes com o Agent. A alteração parecia boa, mas, depois da implantação, três funcionalidades deixaram de funcionar. Sem testes como proteção, você não tem como saber quais problemas o Agent introduziu.

Portanto, escreva testes primeiro ou avance em etapas pequenas com verificação manual. Não aposte tudo de uma vez.

Armadilha 4: depender demais do Agent
A maior armadilha é a mentalidade. Depois de algum tempo, você pode se tornar dependente e reagir a qualquer problema pensando “vou pedir ao Agent”. Mas algumas questões realmente exigem que você raciocine. Já vi gente consultar o Agent até para escolher nomes de variáveis — aí é exagero.

O Agent é uma ferramenta, não uma babá. Ele aumenta a produtividade, mas não substitui o pensamento.

Dica 9: pequenos truques para acelerar o Agent

Às vezes, a lentidão do Agent é enlouquecedora. Você pede uma alteração em poucos arquivos e espera uma eternidade. Algumas otimizações, porém, podem torná-lo bem mais rápido.

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

Ver preços →Anúncio

Dica 1: reduza o escopo da indexação
O .cursorignore, citado antes, é o básico. Além dele, você pode ajustar nas configurações quais partes do Codebase serão indexadas. Em geral, indexo apenas diretórios centrais, como src/ e lib/, e excluo documentação, arquivos de configuração e outros itens semelhantes.

Dica 2: limpe o histórico do chat
O Agent consulta o contexto das conversas anteriores. Se o histórico estiver muito longo, ele precisará revisá-lo toda vez e ficará naturalmente mais lento. Criei o hábito de iniciar uma conversa nova depois de concluir uma tarefa grande. É como esvaziar o carrinho e seguir mais leve.

Dica 3: use um modelo mais rápido
Por padrão, o Cursor usa GPT-4, que oferece boa qualidade, mas é lento. Para tarefas simples, como renomear itens em lote ou formatar código, você pode mudar para Claude Sonnet ou GPT-3.5 e até dobrar a velocidade.

Minha regra é: para lógica complexa, uso GPT-4 em busca de estabilidade; para tarefas simples, escolho um modelo rápido.

Dica 4: processe em lotes, em vez de alterar tudo de uma vez
Se for preciso adicionar comentários a 100 arquivos, não peça ao Agent que faça tudo de uma vez. Divida em cinco lotes de 20 e faça uma verificação entre eles. Assim, você descobre problemas cedo, reduz o contexto de cada execução e ganha velocidade.

No fim das contas, o Agent também precisa de otimização. Você não deixaria uma consulta varrer uma tabela inteira sem necessidade, certo? Reduza a carga e ele trabalhará melhor.

Dica 10: minha lista de verificação para usar o Agent

Depois de todo esse tempo, criei uma lista de verificação. Sempre dou uma olhada antes de iniciar o Agent:

Antes da tarefa:

• ✓ O Git tem um commit recente e a árvore de trabalho está limpa
• ✓ O .cursorignore está configurado
• ✓ O escopo da tarefa está claro, incluindo os arquivos afetados
• ✓ A branch atual foi conferida; nada de alterar diretamente a main
• ✓ O ambiente de testes está pronto para uma validação rápida

Durante a execução do Agent:

• ✓ Acompanhar os logs de saída e interromper imediatamente ao notar algo anormal
• ✓ Observar as alterações de arquivos para impedir mudanças indevidas na lógica central
• ✓ Pressionar ESC sem hesitar se a execução sair da direção certa
• ✓ Dividir tarefas complexas em etapas, sem tentar fazer tudo de uma vez

Depois da tarefa:

• ✓ Conferir todas as alterações com git diff
• ✓ Executar os testes com npm test
• ✓ Revisar lógica, desempenho e segurança do código
• ✓ Fazer commit apenas depois que os testes locais passarem
• ✓ Limpar o histórico de chat desnecessário

A lista parece trabalhosa, mas pode realmente salvar seu projeto. É como a lista de verificação de um piloto antes da decolagem: mesmo sendo repetitiva, evita a maioria dos acidentes.

A regra mais importante: nunca peça ao Agent uma alteração grande na sexta-feira à tarde. Aprendi isso da pior maneira — passar o fim de semana corrigindo bugs não é nada agradável.

Conclusão

Voltando à cena das duas da manhã no início do artigo: hoje eu não deixaria o Agent sair do controle e gerar cinco arquivos errados. Sei quando dar liberdade e quando interromper, como dividir tarefas e definir limites. Mais importante, entendi que o Agent não é mágico; é apenas uma ferramenta que precisa ser conduzida.

Três meses de tentativas resultaram nestas dez dicas. Sinceramente, o modo Agent pode dobrar a produtividade no desenvolvimento — desde que você aprenda a trabalhar com ele. É como um estagiário cheio de energia e com pouca experiência: se receber a direção certa, ajuda muito; se for deixado sozinho, também consegue transformar o projeto em um caos.

Minha sugestão é não ter medo de errar, mas estar sempre pronto para reverter. Comece por tarefas pequenas e construa confiança aos poucos. Quando você e o Agent estiverem em sintonia, perceberá que ele realmente pode ser um excelente assistente.

Por fim, uma forma de pensar que considero importante: o Agent existe para ampliar sua capacidade, não para substituir seu raciocínio. Diante de um problema, primeiro pense em como resolvê-lo e só então decida se precisa da ajuda do Agent. Com essa postura, você não se torna refém da ferramenta.

E, se estiver começando a usar o Cursor Agent, configure o Git antes de qualquer coisa. Não é brincadeira: a segurança de poder reverter tudo dá muito mais liberdade para experimentar.

Boa parceria com o Agent. Se você também tiver alguma dica de uso ou história sobre uma armadilha em que caiu, compartilhe nos comentários. Afinal, evitar problemas em conjunto é melhor do que cada um aprender sozinho.