Entendendo sua base de código

Uma das tarefas mais importantes de um engenheiro de software é criar um mapa mental da base de código e entender profundamente como o sistema funciona. À medida que um projeto cresce, fica cada vez mais difícil encontrar o código certo.

No passado, explorar uma grande base de código significava memorizar padrões de regex ou aprender ferramentas especializadas para pesquisar com eficiência. Com agentes de programação, você pode descrever o que procura em linguagem natural e deixar que o agente use ferramentas para encontrar o que você precisa.

O Cursor fornece aos agentes ferramentas específicas para pesquisar com eficiência, e entender como elas funcionam ajudará você a fazer perguntas melhores e obter resultados mais precisos.

Busca agêntica

A maneira mais precisa de encontrar um trecho de código é buscar uma correspondência exata, seja o nome de uma função, uma variável ou outra parte do código.

Os agentes podem usar o grep, uma ferramenta para encontrar strings exatas, e criar padrões de regex mais complexos ou correspondências em limites de palavras. Também há aprimoramentos do grep, como o ripgrep, que permitem buscas recursivas.

Ambas as ferramentas funcionam muito bem. No entanto, o Cursor aprimorou ainda mais o grep com o Grep Instantâneo, que pode acelerar significativamente as buscas agênticas em grandes bases de código em relação ao ripgrep.

Você não precisa configurar nada nem mudar a forma como trabalha para usar essas ferramentas. O Cursor as disponibiliza automaticamente e, quando você conversa com um agente, ele as usa nos bastidores.

Pesquisa por significado

Quando você não sabe o símbolo ou texto exato, o agente pode pesquisar na sua base de código por significado. Ele combina essa pesquisa com o grep para encontrar arquivos relevantes e rastrear referências exatas. Consulte como o agente pesquisa sua base de código para saber mais.

Fazendo boas perguntas

A forma como você formula as perguntas afeta quais ferramentas de busca o agente usa e a eficácia dos resultados. Isso varia de buscas específicas a amplas: você pode começar pedindo uma correspondência exata de texto, como o nome de uma função, e chegar a buscas amplas como "ajude-me a entender o que acontece quando um usuário faz um pagamento no nosso app."

Comece de forma específica quando souber o que procura. Amplie a busca quando estiver explorando território desconhecido. Vejamos alguns exemplos.

Neste primeiro exemplo, o agente começa com grep porque o prompt pede algo específico. Ele busca por import.*PaymentService para encontrar todos os arquivos que fazem referência ao serviço.

Quando estiver explorando território desconhecido, amplie a busca. Neste próximo exemplo, fazemos uma pergunta geral sobre como o app lida com pagamentos recusados. Observe como a primeira chamada de ferramenta é "Buscar na base de código". O agente encontra arquivos relevantes e, em seguida, usa grep para obter mais detalhes.

O subagente de exploração

O agente também pode criar subagentes para concluir tarefas com mais eficiência.

Há um subagente de exploração integrado que ajuda você a pesquisar na sua base de código. O subagente de exploração é executado em uma janela de contexto própria, separada do agente pai, e usa um modelo mais rápido, podendo realizar muitas pesquisas em paralelo sem sobrecarregar a conversa principal.

Você não precisa invocá-lo manualmente. O agente o usará quando considerar relevante. No entanto, se preferir, também pode pedir diretamente que o subagente seja usado.

Como vimos no curso de fundamentos, é importante entender e acompanhar o uso do contexto. Se você pesquisar em muitos arquivos da sua base de código, isso gerará muito contexto. Os subagentes podem melhorar significativamente o gerenciamento de contexto ao retornar apenas seus resultados e manter a conversa principal focada.

Diagramas de arquitetura

Para bases de código grandes ou pouco conhecidas, você pode pedir ao agente que gere diagramas de arquitetura, como diagramas Mermaid, para visualizar sua base de código.

Esses diagramas são úteis para onboarding, documentação e revisões de design. Eles também podem revelar problemas de arquitetura, como um serviço que depende de muitos outros serviços ou um fluxo de dados que segue um caminho inesperado.

Padrão comum de falha: alterar antes de entender

Um erro comum é pedir ao agente que altere o código sem antes entender o que já existe. O agente pode criar uma nova função utilitária quando já existe uma ou usar um padrão diferente do restante da sua base de código.

Antes de pedir alterações, peça primeiro ao agente para explorar:

Agentes de programação interpretam suas solicitações literalmente. Quando você não informa a intenção, eles usam o próprio julgamento. Às vezes, isso funciona bem. Mas, para alterações que precisam seguir padrões existentes, você terá melhores resultados se primeiro entender a base de código e souber exatamente o que pedir.

A seguir

Você já sabe encontrar e entender código. No próximo capítulo, aprenderá a transformar esse entendimento em entregas: planejar funcionalidades, escrever testes e transformar designs em código.