Grandes codebases

Como trabalhar com grandes codebases no Cursor

Trabalhar com grandes codebases traz um conjunto diferente de desafios em comparação com projetos menores. Com base na nossa experiência escalando a própria codebase do Cursor e nos insights de clientes que gerenciam codebases enormes, a gente descobriu alguns padrões úteis para lidar com a complexidade crescente.

Neste guia, vamos passar por algumas dessas técnicas que a gente achou úteis para grandes codebases.

Usa o Chat para se atualizar rapidamente sobre um código desconhecido

Navegar por uma base de código grande, especialmente se ela é nova pra você, pode ser desafiador. Você costuma usar grep, pesquisar e sair clicando pra encontrar as partes específicas da base de código que tá procurando. Com o Chat, dá pra começar a fazer perguntas pra achar o que precisa e receber uma explicação detalhada de como isso funciona.

Aqui a gente tá recebendo ajuda pra encontrar detalhes de implementação da indexação da base de código no Cursor e até pedindo alguns exemplos pra facilitar o entendimento.

Escreve regras para conhecimento específico de domínio

Se você estivesse trazendo uma pessoa nova pro seu codebase, que contexto você daria pra garantir que ela consiga começar a fazer contribuições significativas?

Sua resposta a essa pergunta provavelmente é informação valiosa pro Cursor também. Em toda organização ou projeto, existe conhecimento latente que pode não estar totalmente capturado na sua documentação. Usar regras de forma eficaz é a melhor maneira de garantir que o Cursor tenha a visão completa.

Por exemplo, se você tá escrevendo instruções de como implementar um novo recurso ou serviço, considera escrever uma regra curta pra documentar isso pra posteridade.

Boilerplate

---
description: Adicionar um novo serviço de frontend do VSCode
---

1. **Definição da interface:**
   - Define uma nova interface de serviço usando `createDecorator` e garante que `_serviceBrand` esteja incluído pra evitar erros.

2. **Implementação do serviço:**
   - Implementa o serviço em um novo arquivo TypeScript, estendendo `Disposable`, e registra como singleton com `registerSingleton`.

3. **Contribuição do serviço:**
   - Cria um arquivo de contribuição pra importar e carregar o serviço, e registra ele no ponto de entrada principal.

4. **Integração ao contexto:**
   - Atualiza o contexto pra incluir o novo serviço, permitindo acesso em toda a aplicação.

Se existirem padrões de formatação comuns que você quer que o Cursor siga, considera anexar automaticamente regras com base em padrões glob.

Formatting

---
globs: *.ts
---
- Usa bun como gerenciador de pacotes. Veja o [package.json](mdc:backend/reddit-eval-tool/package.json) para os scripts
- Usa kebab-case para nomes de arquivos
- Usa camelCase para nomes de funções e variáveis
- Usa UPPERCASE_SNAKE_CASE para constantes hardcoded
- Prefere `function foo()` em vez de `const foo = () =>`
- Usa `Array<T>` em vez de `T[]`
- Usa exports nomeados em vez de export default, ex.: (`export const variable ...`, `export function `)

Fica perto do processo de criação de planos

Para mudanças maiores, dedicar um tempo acima da média para criar um plano preciso e bem delimitado pode melhorar significativamente o output do Cursor.

Se você perceber que não está conseguindo o resultado que quer depois de algumas variações do mesmo prompt, considera dar um passo atrás e criar um plano mais detalhado do zero, como se estivesse criando um PRD para uma pessoa do time. Muitas vezes, a parte difícil é descobrir qual mudança deve ser feita — uma tarefa que combina bem com humanos. Com as instruções certas, dá pra delegar algumas partes da implementação ao Cursor.

Uma maneira de usar IA para potencializar o processo de criação de planos é usar o Ask mode. Para criar um plano, ativa o Ask mode no Cursor e despeja qualquer contexto que você tiver dos seus sistemas de gestão de projetos, docs internos ou ideias soltas. Pensa nos arquivos e dependências que você tem na base de código e que já sabe que quer incluir. Pode ser um arquivo com trechos de código com os quais você quer integrar ou até uma pasta inteira.

Aqui vai um prompt de exemplo:

Planning prompt

- create a plan for how we shoud create a new feature (just like @existingfeature.ts)
- ask me questions (max 3) if anything is unclear
- make sure to search the codebase

@Past Chats (my earlier exploration prompts)

here's some more context from [project management tool]:
[pasted ticket description]

Estamos pedindo pro modelo criar um plano e reunir contexto fazendo perguntas pra pessoa, referenciando quaisquer prompts de exploração anteriores e também as descrições dos tickets. Usar um modelo de raciocínio como claude-3.7-sonnet, gemini-2.5-pro ou o3 é recomendado, porque eles entendem melhor a intenção da mudança e conseguem sintetizar um plano superior.

A partir disso, dá pra formular o plano de forma iterativa com a ajuda do Cursor antes de começar a implementação.

Escolhe a ferramenta certa para a tarefa

Uma das habilidades mais importantes para usar o Cursor de forma eficaz é escolher a ferramenta certa para a tarefa. Pensa no que você tá tentando fazer e escolhe a abordagem que vai te manter em flow.

Tool	Use case	Strength	Limitation
Tab	Mudanças rápidas e manuais	Controle total, velocidade	Arquivo único
Inline Edit	Mudanças com escopo em um arquivo	Edições focadas	Arquivo único
Chat	Mudanças maiores, multiarquivo	Reúne contexto automaticamente, edições profundas	Mais lento, dependente de contexto

Cada ferramenta tem seu ponto ideal:

• Tab é teu go-to para edições rápidas em que você quer estar no comando
• Inline Edit brilha quando você precisa fazer mudanças focadas em uma seção específica do código
• Chat é perfeito para aquelas mudanças maiores em que você precisa que o Cursor entenda o contexto mais amplo

Quando você estiver usando o modo Chat (que pode parecer um pouco mais lento, mas é incrivelmente poderoso), ajuda ele a te ajudar fornecendo um bom contexto. Usa @files pra apontar código parecido que você quer emular, ou @folder pra dar a ele um entendimento melhor da estrutura do teu projeto. E não tem problema dividir mudanças maiores em partes menores — começar chats novos ajuda a manter tudo focado e eficiente.

Principais lições

• Reduz o escopo das mudanças e não tenta fazer tudo de uma vez
• Inclui contexto relevante sempre que der
• Usa Chat, Inline Edit e Tab para o que cada um faz melhor
• Cria novos chats com frequência
• Planeja com o Ask mode, implementa com o Agent mode