Cursor Agent em projetos grandes: 7 formas de evitar arquivos perdidos e alterações erradas

A terceira mensagem de erro apareceu na tela.

Eu tinha acabado de pedir ao Cursor Agent que refatorasse o módulo de login. Esse módulo envolvia cinco arquivos: o componente de formulário no frontend, a rota da API, o middleware de autenticação, o modelo de usuário e a camada de cache do Redis. Depois de receber a tarefa, o Agent trabalhou por dois minutos e declarou, cheio de confiança, que tinha terminado. Executei o código e… tudo quebrou.

Depois de investigar, descobri que o Agent encontrou quatro arquivos, mas alterou apenas três. Pior: ele também “otimizou” a lógica do middleware que já estava correta, fazendo com que todas as tentativas de login retornassem 401. Passei meia hora revertendo o código manualmente, reorganizei as dependências e terminei o trabalho que faltava por conta própria.

Naquele momento, fiquei me perguntando: assistentes de programação com IA conseguem mesmo lidar com projetos grandes?

Passei as duas semanas seguintes estudando como o Cursor Agent funciona, lendo mais de dez blogs técnicos e experimentando em projetos reais. Aos poucos, desenvolvi um método que tornou o Agent muito mais confiável em bases de código grandes. Hoje, minha taxa de sucesso em refatorações com o Agent passou de menos de 50% para mais de 90%.

Este artigo reúne sete técnicas práticas em três áreas: gestão de contexto, divisão de tarefas e revisão de código. Não são hipóteses teóricas, mas lições aprendidas com erros em projetos reais.

Por que o Agent costuma falhar em projetos grandes

Antes das técnicas, precisamos entender por que o Agent erra. Não é porque ele seja “burro”, mas porque enfrenta três limitações objetivas.

O limite de contexto é o maior gargalo

Mesmo um modelo que anuncia 200 mil tokens não dá conta de um projeto real inteiro. Um sistema de porte médio, com frontend e backend separados, pode ter centenas de arquivos principais, cada um com centenas ou milhares de linhas. Some package.json, configurações e testes, e o limite de tokens é ultrapassado com facilidade.

O Agent não consegue “enxergar” o projeto todo. Ele vê apenas os arquivos mencionados na conversa atual e parte das dependências que o sistema de indexação automática do Cursor consegue relacionar. É como pedir a alguém com um campo de visão de cinco metros que encontre algo em um estádio de futebol: deixar algo passar é inevitável.

Fiz um teste em um projeto React + Node.js: para o mesmo requisito, o Agent acertava de primeira em 85% dos casos num projeto pequeno, com 20 arquivos. Em um projeto médio, com 50 arquivos, a taxa caía para 60%. Num projeto grande, com mais de 100 arquivos, despencava para 35%. A diferença é bastante clara.

O problema da “miopia” do Agent

Há outro fenômeno curioso: o Agent tende a não enxergar arquivos que participam apenas de dependências indiretas.

Se você pedir uma alteração numa rota de API, ele provavelmente modificará a rota e o Controller correspondente. O problema é que esse Controller pode chamar uma função utilitária, que por sua vez depende de um módulo de configuração. O Agent costuma seguir essa cadeia oculta até a segunda camada e parar por ali.

O pior é o viés de recência: o Agent prioriza arquivos abertos recentemente e arquivos mencionados explicitamente na conversa. Se o histórico anterior citou um arquivo que não tem relação com a tarefa atual, o Agent pode incluí-lo e alterá-lo sem necessidade. Ao mesmo tempo, se você não mencionar um arquivo realmente essencial, ele pode simplesmente ignorá-lo.

Falta de uma visão global

Essa é a limitação mais perigosa.

Antes de alterar o código, uma pessoa desenvolvedora costuma reconstruir mentalmente a arquitetura: quais módulos a funcionalidade envolve? Como eles se comunicam? Alterar A afeta B? O Agent não faz isso da mesma forma. Cada tarefa vira uma “otimização local”: ele olha para o código ao alcance, escolhe a solução que parece mais razoável e começa a editar.

O caso mais absurdo que vi aconteceu quando pedi ao Agent para melhorar o desempenho de consultas ao banco. Ele adicionou índices e ajustou as instruções SQL com bastante cuidado. A consulta ficou muito mais rápida. Três dias depois, porém, o sistema ficou sem memória. Para “otimizar”, ele havia incluído na camada de cache uma rotina que pré-carregava todos os dados e acabou lotando o Redis.

O Agent não compreende automaticamente o “projeto da arquitetura como um todo”. Ao encontrar um problema de desempenho, otimiza desempenho; ao ver código duplicado, extrai uma função. Ele não avalia necessariamente se isso destrói a intenção original do projeto.

Três técnicas essenciais de gestão de contexto

Depois de entender o problema, fica mais fácil agir sobre a causa. A gestão de contexto é a prioridade: controle bem o que o Agent consegue “ver” e muitos erros desaparecem.

Técnica 1: otimize a configuração das Project Rules

Por praticidade, muita gente coloca todas as regras do projeto no modo always. Esse é o maior equívoco.

O modo always significa que as regras serão carregadas em toda conversa. Parece conveniente, mas consome tokens em excesso. Seu projeto pode ter módulos de frontend, backend, testes e documentação, cada um com padrões de código diferentes. Se tudo for carregado sempre, um terço dos tokens acaba antes mesmo de o Agent começar a trabalhar.

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

Ganhar 15% off →Anúncio

A abordagem certa: use Auto Attached com correspondência glob

Por exemplo, configuro assim um projeto com frontend e backend separados que mantenho atualmente:

# .cursorrules (raiz do projeto)

# Regras gerais (mantenha apenas as essenciais)
- type: always
  rules:
    - Use TypeScript
    - Siga a configuração do ESLint
    - Todas as operações assíncronas devem tratar erros

# Regras de frontend (carregadas apenas ao alterar o frontend)
- type: auto
  glob: "src/frontend/**/*.{ts,tsx}"
  rules:
    - Use React Hooks
    - Os componentes devem ter PropTypes ou tipos TypeScript
    - Use Tailwind CSS; não escreva estilos inline

# Regras de backend (carregadas apenas ao alterar o backend)
- type: auto
  glob: "src/backend/**/*.ts"
  rules:
    - As rotas da API devem validar as entradas
    - As operações de banco de dados devem usar transações
    - Informações sensíveis não podem ser registradas nos logs

# Regras de testes
- type: auto
  glob: "**/*.test.ts"
  rules:
    - Cada caso de teste deve ter uma descrição clara
    - Use a estrutura describe/it do Jest

Com essa configuração, o Agent só carrega cada regra quando ela é realmente necessária. Nos meus testes, o consumo de tokens caiu 70%, e regras irrelevantes deixaram de interferir no trabalho.

Uma dica: acrescente ao final de cada regra algo como “se não tiver certeza, pergunte antes”. Percebi que isso faz o Agent pedir esclarecimentos nos casos-limite, em vez de adivinhar.

Técnica 2: use bem o Long Context e o Summarized Composers

O Cursor tem dois recursos muito úteis que costumam passar despercebidos.

Long Context

É uma opção que vale a pena ativar em tarefas complexas. Quando ligada, o Agent utiliza uma janela de contexto maior e consegue analisar mais código.

Não a deixe sempre ativa: ela consome tokens rapidamente e aumenta o tempo de raciocínio do Agent. Minha regra é:

• Tarefa comum, como alterar uma função ou corrigir um bug: desativado
• Tarefa complexa, como refatorar um módulo ou adicionar uma funcionalidade: ativado
• Tarefa muito complexa, como uma refatoração entre módulos: ativado e com referências manuais aos arquivos essenciais

Summarized Composers

Esse recurso permite que o Agent acesse resumos de conversas anteriores em vez do histórico completo. É especialmente útil em projetos de longa duração.

Imagine que ontem o Agent ajudou a criar uma função utilitária e hoje você quer ampliá-la. Dizer apenas “use aquela função de ontem” pode não ser suficiente para encontrá-la. Com o Summarized Composers ativo, o Agent pesquisa automaticamente os resumos das conversas anteriores e localiza o conteúdo relacionado.

Meu fluxo atual é criar uma nova janela de Chat sempre que concluo um módulo grande e começar com uma frase como: “Este projeto já implementou a funcionalidade XX, cujo código está no diretório XX”. Assim, consigo aproveitar o contexto anterior sem carregar detalhes demais.

Técnica 3: gerencie ativamente o escopo do contexto

Essa é a técnica mais importante e também uma das mais esquecidas.

Não espere que o Agent encontre todos os arquivos sozinho. Diga explicitamente o que ele deve e não deve analisar.

Use @ para referenciar arquivos essenciais

Ao descrever a tarefa, marque os arquivos importantes com @nome-do-arquivo:

Refatore o fluxo de autenticação de usuários. A tarefa envolve estes arquivos:
@src/routes/auth.ts (rota de autenticação)
@src/middleware/jwt.ts (middleware JWT)
@src/models/User.ts (modelo de usuário)
@src/utils/password.ts (utilitário de hash de senha)

Não altere outros arquivos.

A última frase é fundamental. Nos meus testes, incluí-la reduziu a chance de o Agent alterar código irrelevante de 30% para menos de 5%.

Delimite o escopo das alterações

Se a tarefa envolve apenas um subdiretório, deixe isso claro:

Adicione um componente de recuperação de senha no diretório
src/frontend/components/auth/.
Não altere código em outros diretórios.

Há também uma técnica mais avançada: combine uma lista de permissões com outra de bloqueios.

Pode alterar: todos os arquivos em src/api/**
Não altere: src/api/legacy/** (este é código legado que será desativado)

Assim, o Agent recebe liberdade suficiente sem tocar no que deve permanecer intacto.

Criei o hábito de, antes de cada tarefa, pensar: “quantos arquivos esta tarefa deveria alterar, no máximo? Quais diretórios estão envolvidos?”. Depois, explicito esse escopo para o Agent. Parece trabalhoso, mas economiza muito tempo de correção mais tarde.

Duas regras de ouro para dividir tarefas

A gestão de contexto resolve o problema de o Agent não enxergar tudo. Ainda assim, mesmo com todos os arquivos necessários, uma tarefa complexa demais pode dar errado. É aí que a divisão de tarefas entra em cena.

Técnica 4: divida por responsabilidade, não por arquivo

Esse foi o erro que mais me custou tempo.

No começo, eu achava que bastava separar a tarefa por arquivo. Para criar um cadastro de usuários, por exemplo, eu fazia assim:

1. Primeiro, escrever o componente do formulário no frontend
2. Depois, criar a rota da API no backend
3. Por fim, criar o modelo no banco de dados

Parece razoável, certo? Na prática, cada etapa trazia um novo problema:

• Ao criar o frontend, eu ainda não sabia como seria a interface do backend e precisava adivinhar.
• Ao criar o backend, descobria que os parâmetros enviados pelo frontend não correspondiam ao esperado e precisava voltar para corrigir.
• Ao criar o modelo do banco, percebia que o tipo de algum campo estava errado e precisava alterar frontend e backend de novo.

Todo esse vai e volta tornava o trabalho mais lento.

A abordagem certa: dividir por responsabilidade funcional

Ainda no exemplo do cadastro, agora faço assim:

Etapa 1: implementar o fluxo básico de cadastro, como produto mínimo viável

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

Começar →Anúncio

Tarefa 1: implementar o cadastro básico de usuários
- Frontend: formulário apenas com nome de usuário e senha
- Backend: API de cadastro e validação básica
- Banco de dados: modelo User com o mínimo de campos
Objetivo: executar o fluxo completo e cadastrar um usuário com sucesso

Etapa 2: reforçar a validação e a segurança

Tarefa 2: adicionar validação e mecanismos de segurança ao cadastro
- Validar o formato do e-mail
- Verificar a força da senha
- Impedir cadastros duplicados
- Armazenar a senha com hash

Etapa 3: melhorar a experiência do usuário

Tarefa 3: melhorar a experiência de cadastro
- Exibir validação do formulário em tempo real
- Fazer login automaticamente após o cadastro
- Enviar um e-mail de boas-vindas

Percebe a diferença? Cada tarefa é “vertical”: atravessa frontend, backend e banco de dados para entregar uma funcionalidade independente e completa.

Essa divisão tem três vantagens:

1. Cada tarefa pode ser testada isoladamente: a tarefa 1 já pode ser executada sem esperar todas as funcionalidades.
2. Menos retrabalho: como frontend e backend avançam juntos, problemas de interface aparecem na hora.
3. Maior clareza para o Agent: o objetivo é específico e reduz confusões.

Nos meus testes, dividir por responsabilidade elevou a taxa de sucesso do Agent na primeira tentativa de 60% para 85%.

Técnica 5: defina checkpoints claros

Essa técnica já me salvou inúmeras vezes.

Um risco fatal em projetos grandes é trabalhar por muito tempo e só então perceber que a direção estava errada, quando já não é fácil voltar. Com o Agent, isso é ainda mais comum: ele não pergunta se deve salvar o estado; simplesmente começa a alterar. Quando você percebe o problema, mais de dez arquivos podem ter sido modificados.

Use o recurso Checkpoint

O Cursor tem um recurso útil e muito subestimado: o Checkpoint.

Antes de começar a tarefa, crie um checkpoint:

# No Cursor, pressione Cmd/Ctrl + Shift + P
# Digite "Create Checkpoint"
# Adicione a observação: antes de refatorar o módulo de login

Depois, deixe o Agent trabalhar. Se algo der errado, você pode voltar ao checkpoint com um clique e desfazer todas as alterações.

Minha prática é:

• Ao iniciar uma tarefa grande: criar um checkpoint.
• Quando o Agent terminar: se os testes passarem, excluir o checkpoint; se falharem, voltar ao checkpoint.
• Em uma sequência de tarefas pequenas: criar um checkpoint a cada duas ou três tarefas concluídas.

Assim, mesmo que o Agent estrague algo, você perde no máximo o trabalho de uma pequena tarefa.

Desenvolvimento orientado a testes (TDD)

Há uma técnica mais avançada: escreva os testes antes e peça ao Agent que implemente a funcionalidade depois.

Parece trabalhoso, mas é muito útil em projetos grandes. O fluxo pode ser este:

1. Escreva manualmente os casos de teste que definem o comportamento esperado.
2. Execute os testes e confirme que falham, pois a funcionalidade ainda não existe.
3. Peça ao Agent que implemente a funcionalidade até os testes passarem.
4. Se eles continuarem falhando, o Agent entendeu a tarefa de forma errada: interrompa imediatamente.

A força desse método é que os testes dão ao Agent uma condição de término explícita. Ele não fica se dispersando; concentra-se no objetivo de fazer os testes passarem.

Usei esse método para refatorar todo o módulo de autenticação de um projeto Node.js. O Agent concluiu o trabalho em sete tentativas sem sair do rumo. Antes, sem testes, a mesma tarefa ainda apresentava bugs depois de mais de dez tentativas.

Duas práticas essenciais de revisão e monitoramento

Até aqui, vimos como fazer o Agent errar menos. Mesmo com cuidado, porém, não existe taxa de erro zero. A última linha de defesa é revisar e monitorar o código para detectar problemas cedo e limitar os danos.

Técnica 6: adote uma revisão em vários níveis

Um equívoco comum é achar que a IA elimina a necessidade de Code Review.

É justamente o contrário: com IA, o Code Review se torna ainda mais importante. Os erros do Agent costumam ser sutis. A sintaxe está certa, a lógica parece plausível, mas alguma coisa simplesmente não se encaixa. Uma pessoa percebe de imediato o que o Agent talvez não note.

Configure regras de revisão nas Cursor Rules

O Cursor permite definir regras de Code Review no .cursorrules. Esta é a minha configuração:

# .cursorrules (seção de regras de revisão)
code_review_rules:
  # Nível crítico (correção obrigatória)
  critical:
    - "Não codifique senhas, chaves de API ou outras informações sensíveis diretamente no código"
    - "Operações de banco de dados devem usar consultas parametrizadas para impedir injeção de SQL"
    - "Toda entrada externa deve ser validada e sanitizada"

  # Nível de alerta (correção altamente recomendada)
  warning:
    - "Funções não devem ultrapassar 50 linhas; considere dividi-las"
    - "Evite o tipo any e prefira tipos explícitos"
    - "Operações assíncronas devem tratar erros com try-catch ou .catch()"

  # Nível informativo (otimização opcional)
  info:
    - "Considere adicionar testes unitários"
    - "Adicione comentários à lógica complexa"
    - "Considere extrair código repetido para uma função compartilhada"

Depois de configurar, peço ao Agent que faça uma autorrevisão sempre que concluir uma tarefa:

A tarefa terminou. Agora, revise o código conforme code_review_rules no .cursorrules
e liste todos os problemas dos níveis critical e warning.

O Agent lista os problemas que encontra. Curiosamente, muitas vezes ele consegue identificar falhas no próprio código durante a revisão. É como fazê-lo olhar para o trabalho de outro ângulo.

Estratégia de revisão combinando pessoas e IA

Confiar apenas na revisão do Agent não é seguro; revisar tudo manualmente é cansativo. Minha solução é trabalhar em níveis:

1. Revisão inicial pelo Agent, automática: procura erros claros de sintaxe e violações de padrões.
2. Revisão humana concentrada: examina principalmente:
   • Se a lógica de negócio está correta, a área em que o Agent mais erra.
   • Se todos os casos-limite foram tratados.
   • O impacto no desempenho, como o risco de consultas N+1.
   • Riscos de segurança, como injeção de SQL e XSS.
3. Validação por testes: executa os testes para garantir que funcionalidades existentes não foram afetadas.

O importante é não revisar cada linha. Concentre-se na lógica central e nos pontos de risco; deixe os demais detalhes para as ferramentas e os testes.

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

Ver preços →Anúncio

Em projetos grandes, estimei que cerca de 15% a 20% do código alterado pelo Agent tinha algum problema:

• 5% eram bugs graves, como erros de lógica e problemas de segurança.
• 10% eram problemas de qualidade, como desempenho e manutenção.
• 5% funcionavam, mas não seguiam os padrões do projeto.

Sem revisão, esses problemas aparecem aos poucos nas semanas seguintes, quando o custo da investigação é muito maior.

Técnica 7: o Git é seu último seguro

Parece básico, mas muita gente não dá a devida importância.

Use bem o git diff

Depois que o Agent alterar o código, a primeira ação não deve ser executar os testes, mas sim:

git diff

Confira quais arquivos foram alterados e o que mudou em cada um. Eu sempre faço uma leitura rápida, com atenção especial a:

• Se o volume de mudanças corresponde ao esperado. Se dezenas de arquivos foram alterados, desconfie.
• Se algum arquivo irrelevante foi modificado.
• Se alguma lógica crítica foi alterada.

Uma dica é executar primeiro git diff --stat para ver o resumo e decidir se precisa examinar o diff completo:

git diff --stat

# Exemplo de saída:
# src/api/auth.ts          | 25 +++++---
# src/models/User.ts       | 12 ++--
# src/utils/password.ts    |  3 +-
# src/config/database.ts   | 150 ++++++++++++++++++++++++++++++++++++++++++++++

Se um arquivo ganhou 150 linhas e a tarefa nem sequer pedia uma mudança nele, descubra imediatamente o que aconteceu.

Combine Checkpoint e Git

Use o Checkpoint e o Git em conjunto para ter duas camadas de segurança:

1. Antes de começar a tarefa:
   - git checkout -b feature/xxx  (criar uma branch para isolar as alterações)
   - Criar um Cursor Checkpoint

2. Depois que o Agent terminar:
   - git diff (inspecionar as alterações)
   - Executar os testes
   - Se estiver tudo certo: git commit
   - Se houver problemas:
     - Problema pequeno: corrigir manualmente ou pedir uma correção ao Agent
     - Problema grande: voltar ao Checkpoint ou usar git reset --hard

3. Depois de confirmar que está tudo certo:
   - git push
   - Criar um Pull Request

Esse fluxo oferece:

• Checkpoint: rollback rápido sem lidar com o histórico do Git.
• Branch do Git: mudanças isoladas, sem afetar a branch principal.
• Histórico de commits: registro de cada etapa da alteração.

Também tenho o hábito de identificar no commit quando o Agent participou:

git commit -m "feat: adicionar cadastro de usuários (by AI Agent)"

Assim, se surgir um problema no futuro, basta olhar o commit para saber que o código foi produzido pelo Agent e merece atenção especial durante a investigação.

Conclusão

Voltemos ao cenário da uma da manhã que abriu este artigo.

Se eu fosse usar o Cursor Agent hoje para refatorar o módulo de login, faria o seguinte:

1. Gestão de contexto: criaria um .cursorrules específico para o módulo de autenticação, carregando apenas as regras relacionadas; usaria @ para referenciar os cinco arquivos essenciais e diria explicitamente ao Agent que alterasse somente esses cinco.
2. Divisão de tarefas: em vez de refatorar tudo de uma vez, implementaria primeiro o fluxo básico de login, depois acrescentaria a validação e, por último, otimizaria o cache.
3. Revisão de código: ao fim de cada pequena tarefa, usaria git diff, executaria os testes e só avançaria depois de confirmar o resultado.

Com esse processo, a chance de o Agent não encontrar um arquivo caiu de 50% para menos de 10%, e a chance de alterar código incorretamente caiu de 30% para menos de 5%. O custo adicional foi de apenas cinco a dez minutos por tarefa.

Sendo sincero, ferramentas de programação com IA não resolvem tudo. Elas não substituem o projeto de arquitetura, a compreensão da lógica de negócio nem a responsabilidade pela qualidade do código. Quando são bem utilizadas, porém, podem dobrar sua produtividade — desde que você saiba “gerenciá-las”.

Gestão de contexto, divisão de tarefas e revisão de código: as três dimensões são indispensáveis. A gestão de contexto faz o Agent “enxergar com precisão”, a divisão de tarefas o ajuda a “fazer a coisa certa” e a revisão de código permite que você “durma tranquilo”.

Uma última sugestão: se você usa o Cursor Agent em um projeto grande, reserve dez minutos hoje para revisar suas Project Rules. Trocar o modo always por auto com glob reduz bastante o consumo de tokens e melhora imediatamente o desempenho do Agent.

A tecnologia evolui e as ferramentas mudam, mas alguns princípios permanecem: defina os requisitos com clareza, divida as tarefas e valide continuamente. Esse método serve não apenas para programação com IA, mas para qualquer projeto complexo.

E você? Que dificuldades já encontrou ao usar o Cursor Agent? Compartilhe sua experiência nos comentários.