Agentes de código estão mudando a forma como o software é desenvolvido.

Modelos agora podem ser executados por horas, concluir refatorações ambiciosas envolvendo vários arquivos e iterar até que os testes passem. Mas tirar o máximo proveito dos agentes exige entender como eles funcionam e desenvolver novos padrões de uso.

Este guia apresenta técnicas para trabalhar com o Agente do Cursor. Seja você iniciante em programação com agentes ou alguém querendo aprender como nossa equipe usa o Cursor, vamos abordar as melhores práticas para programar com agentes.

#Entendendo os agent harnesses

Um agent harness é composto por três componentes:

1. Instructions: O system prompt e as regras que orientam o comportamento do agente
2. Tools: Edição de arquivos, busca na base de código, execução de comandos no terminal e mais
3. User messages: Suas mensagens — prompts e acompanhamentos — que direcionam o trabalho

O agent harness do Cursor orquestra esses componentes para cada modelo que suportamos. Nós ajustamos as instructions e tools especificamente para cada frontier model com base em avaliações internas e benchmarks externos.

O harness é importante porque modelos diferentes respondem de maneiras diferentes aos mesmos prompts. Um modelo treinado predominantemente em fluxos de trabalho orientados a shell pode preferir grep em vez de uma ferramenta de busca dedicada. Outro pode precisar de instructions explícitas para chamar ferramentas de linter após edições. O agente do Cursor cuida disso para você, então, à medida que novos modelos são lançados, você pode se concentrar em desenvolver software.

#Comece com planejamento

A mudança de maior impacto que você pode fazer é planejar antes de escrever código.

Um estudo da Universidade de Chicago constatou que desenvolvedores experientes são mais propensos a planejar antes de gerar código. Planejar obriga você a pensar com clareza sobre o que está construindo e dá ao agente objetivos concretos para alcançar.

#Usando o Modo de Planejamento

Pressione Shift+Tab no campo de entrada do Agente para alternar o Modo de Planejamento. Em vez de escrever código imediatamente, o agente vai:

1. Pesquisar sua base de código para encontrar arquivos relevantes
2. Fazer perguntas para esclarecer melhor seus requisitos
3. Criar um plano de implementação detalhado com caminhos de arquivos e referências de código
4. Aguardar sua aprovação antes de começar a implementar

Os planos são abertos como arquivos Markdown que você pode editar diretamente para remover etapas desnecessárias, ajustar a abordagem ou adicionar contexto que o agente possa ter deixado passar.

Dica: Clique em "Save to workspace" para salvar os planos em .cursor/plans/. Isso gera documentação para sua equipe, facilita retomar trabalhos interrompidos e fornece contexto para futuros agentes trabalhando na mesma funcionalidade.

Nem toda tarefa precisa de um plano detalhado. Para mudanças rápidas ou tarefas que você já fez muitas vezes, ir direto para o Agente é suficiente.

#Recomeçando a partir de um plano

Às vezes, o agente constrói algo que não corresponde ao que você queria. Em vez de tentar corrigir isso com prompts subsequentes, volte ao plano.

Desfaça as alterações, deixe o plano mais específico sobre o que você precisa e execute-o novamente. Isso costuma ser mais rápido do que consertar um agente em execução e produz resultados mais limpos.

#Gerenciando o contexto

À medida que você se familiariza com agentes que escrevem código, seu trabalho passa a ser fornecer a cada agente o contexto de que ele precisa para concluir sua tarefa.

#Deixe o agente encontrar o contexto

Você não precisa marcar manualmente cada arquivo no seu prompt.

O agente do Cursor tem poderosas ferramentas de busca e obtém contexto sob demanda. Quando você pergunta sobre "o fluxo de autenticação", o agente encontra arquivos relevantes usando grep e busca semântica, mesmo que seu prompt não contenha exatamente essas palavras.

Simplifique: se você souber o arquivo exato, marque-o. Caso contrário, o agente vai encontrá-lo. Incluir arquivos irrelevantes pode confundir o agente sobre o que é importante.

O agente do Cursor também tem ferramentas úteis, como @Branch, que permitem dar ao agente contexto sobre o que você está trabalhando. "Revise as alterações neste branch" ou "No que estou trabalhando?" passam a ser maneiras naturais de orientar o agente para a sua tarefa atual.

#Quando iniciar uma nova conversa

Uma das dúvidas mais comuns: devo continuar esta conversa ou começar uma nova?

Comece uma nova conversa quando:

• Você estiver mudando para outra tarefa ou funcionalidade
• O agente parecer confuso ou continuar cometendo os mesmos erros
• Você tiver concluído uma unidade lógica de trabalho

Continue a conversa quando:

• Você estiver iterando na mesma funcionalidade
• O agente precisar de contexto da parte anterior da conversa
• Você estiver debugando algo que ele acabou de construir

Conversas longas podem fazer o agente perder o foco. Após muitas interações e resumos, o contexto acumula ruído e o agente pode se distrair ou mudar para tarefas não relacionadas. Se você notar que a eficácia do agente está diminuindo, é hora de iniciar uma nova conversa.

#Consultar trabalhos anteriores

Quando você iniciar uma nova conversa, use @Past Chats para consultar trabalhos anteriores em vez de copiar e colar toda a conversa. O agente pode ler seletivamente o histórico do chat para puxar apenas o contexto de que precisa.

Isso é mais eficiente do que duplicar conversas inteiras.

#Estendendo o agente

Cursor oferece duas principais maneiras de personalizar o comportamento do agente: Rules para definir contexto estático que se aplica a todas as conversas e Skills para capacidades dinâmicas que o agente pode usar quando relevante.

#Regras: contexto estático para o seu projeto

As regras fornecem instruções persistentes que definem como o agente trabalha com o seu código. Pense nelas como um contexto sempre disponível que o agente vê no início de cada conversa.

Crie regras como arquivos Markdown em .cursor/rules/:

# Commands

- `npm run build`: Build the project
- `npm run typecheck`: Run the typechecker
- `npm run test`: Run tests (prefer single test files for speed)

# Code style

- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible: `import { foo } from 'bar'`
- See `components/Button.tsx` for canonical component structure

# Workflow

- Always typecheck after making a series of code changes
- API routes go in `app/api/` following existing patterns

Mantenha as regras focadas no essencial: os comandos a serem executados, os padrões a serem seguidos e referências a exemplos canônicos na sua base de código. Faça referência a arquivos em vez de copiar seu conteúdo; isso mantém as regras curtas e evita que fiquem desatualizadas conforme o código muda.

O que evitar nas regras:

• Copiar guias de estilo inteiros (use um linter em vez disso)
• Documentar todos os comandos possíveis (o agente conhece as ferramentas comuns)
• Adicionar instruções para casos de borda que raramente se aplicam

Dica: Comece simples. Adicione regras apenas quando perceber que o agente está cometendo o mesmo erro repetidamente. Não tente otimizar demais antes de entender seus padrões.

Coloque suas regras sob controle de versão com Git para que todo o seu time se beneficie. Quando você vir o agente cometer um erro, atualize a regra. Você pode até marcar @cursor em uma issue ou PR do GitHub para que o agente atualize a regra para você.

#Skills: capacidades e fluxos de trabalho dinâmicos

Skills do Agente ampliam o que os agentes podem fazer. As Skills agrupam conhecimento específico de domínio, fluxos de trabalho e scripts que os agentes podem invocar quando forem relevantes.

As Skills são definidas em arquivos SKILL.md e podem incluir:

• Comandos personalizados: fluxos de trabalho reutilizáveis acionados com / no campo de entrada do agente
• Hooks: scripts que são executados antes ou depois das ações do agente
• Conhecimento de domínio: instruções para tarefas específicas que o agente pode incorporar sob demanda

Diferente das Regras, que são sempre incluídas, as Skills são carregadas dinamicamente quando o agente decide que elas são relevantes. Isso mantém sua janela de contexto limpa enquanto dá ao agente acesso a capacidades especializadas.

#Exemplo: loop de agente de longa duração

Um padrão poderoso é usar skills para criar agentes que são executados por longos períodos, iterando até alcançar uma meta. Veja como você pode criar um hook que mantém um agente trabalhando até que todos os testes passem.

Primeiro, configure o hook em .cursor/hooks.json:

{
  "version": 1,
  "hooks": {
    "stop": [{ "command": "bun run .cursor/hooks/grind.ts" }]
  }
}

O script de hook (.cursor/hooks/grind.ts) recebe o contexto pela entrada padrão (stdin) e retorna uma followup_message para continuar o loop:

import { readFileSync, existsSync } from "fs";

interface StopHookInput {
  conversation_id: string;
  status: "completed" | "aborted" | "error";
  loop_count: number;
}

const input: StopHookInput = await Bun.stdin.json();
const MAX_ITERATIONS = 5;

if (input.status !== "completed" || input.loop_count >= MAX_ITERATIONS) {
  console.log(JSON.stringify({}));
  process.exit(0);
}

const scratchpad = existsSync(".cursor/scratchpad.md")
  ? readFileSync(".cursor/scratchpad.md", "utf-8")
  : "";

if (scratchpad.includes("DONE")) {
  console.log(JSON.stringify({}));
} else {
  console.log(JSON.stringify({
    followup_message: `[Iteration ${input.loop_count + 1}/${MAX_ITERATIONS}] Continue working. Update .cursor/scratchpad.md with DONE when complete.`
  }));
}

Esse padrão é útil para:

• Rodar (e corrigir) os testes até que todos passem
• Iterar na interface de usuário até que ela corresponda a um mockup de design
• Qualquer tarefa orientada a metas em que o sucesso seja verificável

Dica: Skills com hooks podem se integrar a ferramentas de segurança, gerenciadores de segredos e plataformas de observabilidade. Veja a documentação de hooks para integrações com parceiros.

Agent Skills estão atualmente disponíveis apenas no canal de versões Nightly. Abra as configurações do Cursor, selecione Beta e, em seguida, defina seu canal de atualização como Nightly e reinicie.

Além de programar, você pode conectar o agente a outras ferramentas que você usa diariamente. O MCP (Model Context Protocol) permite que o agente leia mensagens do Slack, investigue logs do Datadog, depure erros do Sentry, faça consultas a bancos de dados e muito mais.

#Incluindo imagens

O agente pode processar imagens diretamente nos seus prompts. Cole capturas de tela, arraste arquivos de design ou referencie caminhos de imagem.

#Do design para código

Cole um mockup de design e peça para o Agente implementá-lo. O Agente analisa a imagem e pode reproduzir layouts, cores e espaçamento. Você também pode usar o servidor MCP do Figma.

#Depuração visual

Faça uma captura de tela de um estado de erro ou de uma interface de usuário inesperada e peça para o agente investigar. Isso geralmente é mais rápido do que descrever o problema em palavras.

O agente também pode controlar um navegador para fazer suas próprias capturas de tela, testar aplicações e verificar alterações visuais. Consulte a documentação do Browser para mais detalhes.

#Fluxos de trabalho comuns

Aqui estão padrões de uso de agentes que funcionam bem para diferentes tipos de tarefas.

#Desenvolvimento orientado a testes

O agente pode escrever código, executar testes e iterar automaticamente:

1. Peça para o agente escrever testes com base em pares de entrada/saída esperados. Deixe claro que você está fazendo TDD para que ele evite criar implementações fictícias para funcionalidades que ainda não existem.
2. Diga ao agente para executar os testes e confirmar que eles falham. Deixe explícito que ele não deve escrever o código de implementação nesta etapa.
3. Faça o commit dos testes quando estiver satisfeito com eles.
4. Peça para o agente escrever o código que faz os testes passarem, instruindo-o a não modificar os testes. Diga para continuar iterando até que todos os testes passem.
5. Faça o commit da implementação quando estiver satisfeito com as mudanças.

Os agentes têm o melhor desempenho quando têm um objetivo claro em relação ao qual iterar. Os testes permitem que o agente faça mudanças, avalie resultados e melhore incrementalmente até conseguir.

#Entendimento da base de código

Ao começar a trabalhar em uma nova base de código, use o Agente para aprendizado e exploração. Faça as mesmas perguntas que você faria a um colega de equipe:

• "Como funciona o sistema de logs neste projeto?"
• "Como adiciono um novo endpoint de API?"
• "Quais casos de borda CustomerOnboardingFlow trata?"
• "Por que estamos chamando setUser() em vez de createUser() na linha 1738?"

O Agente usa tanto grep quanto busca semântica para examinar a base de código e encontrar respostas. Essa é uma das maneiras mais rápidas de se ambientar em um código desconhecido.

#Fluxos de trabalho Git

Os agentes podem pesquisar o histórico do Git, resolver conflitos de merge e automatizar seu fluxo de trabalho no Git.

Por exemplo, um comando /pr que cria um commit, faz push e abre uma PR (pull request):

Crie um pull request para as alterações atuais.

1. Veja as alterações staged e unstaged com `git diff`
2. Escreva uma mensagem de commit clara com base no que foi alterado
3. Faça o commit e o push para o branch atual
4. Use `gh pr create` para abrir um pull request com title/descrição
5. Retorne a URL do PR quando concluído

Comandos são ideais para fluxos de trabalho que você executa várias vezes por dia. Armazene-os como arquivos Markdown em .cursor/commands/ e faça commit no git para que todo o seu time possa usá-los.

Outros exemplos de comandos que usamos:

• /fix-issue [number]: Busca os detalhes da issue com gh issue view, encontra o código relevante, implementa uma correção e abre uma PR
• /review: Executa linters, verifica problemas comuns e resume o que pode precisar de atenção
• /update-deps: Verifica dependências desatualizadas e as atualiza uma a uma, executando testes após cada atualização

O Agente pode usar esses comandos de forma autônoma, para que você possa delegar fluxos de trabalho com várias etapas com uma única chamada usando /.

#Revisando código

O código gerado por IA precisa de revisão, e o Cursor oferece várias opções.

#Durante a geração

Veja o agente em ação. A visualização de diff mostra as alterações em tempo real. Se você perceber que o agente está seguindo na direção errada, pressione Escape para interromper e redirecionar.

#Revisão com o Agent

Depois que o agente terminar, clique em Review → Find Issues para executar uma revisão dedicada. O agente analisa as edições propostas linha por linha e sinaliza possíveis problemas.

Para todas as alterações locais, abra a guia Source Control e execute o Agent Review para comparar com a sua branch principal.

#Bugbot para PRs

Dê push no repositório para receber revisões automáticas em PRs. O Bugbot usa análise avançada para identificar problemas mais cedo e sugerir melhorias em cada PR.

#Diagramas de arquitetura

Para mudanças significativas, peça para o agente gerar diagramas de arquitetura. Experimente algo como: "Crie um diagrama em Mermaid mostrando o fluxo de dados do nosso sistema de autenticação, incluindo provedores OAuth, gerenciamento de sessão e renovação de tokens." Esses diagramas são úteis para documentação e podem revelar problemas de arquitetura antes da revisão de código.

#Executando agentes em paralelo

Cursor facilita executar vários agentes em paralelo, sem que eles interfiram entre si. Percebemos que fazer com que vários modelos tentem resolver o mesmo problema e escolher o melhor resultado melhora significativamente o resultado final, especialmente em tarefas mais difíceis.

#Suporte nativo a worktrees

O Cursor cria e gerencia automaticamente git worktrees para agentes em paralelo. Cada agente é executado em seu próprio worktree, com arquivos e alterações isolados, para que os agentes possam editar, compilar e testar código sem que um interfira no outro.

Para executar um agente em um worktree, selecione a opção de worktree na lista suspensa do agente. Quando o agente terminar, clique em Apply para mesclar as alterações dele de volta ao seu branch de trabalho.

#Executar vários modelos ao mesmo tempo

Um padrão poderoso é executar o mesmo prompt em vários modelos simultaneamente. Selecione vários modelos no menu suspenso, envie o prompt e compare os resultados lado a lado. O Cursor também sugerirá qual solução considera melhor.

Isso é especialmente útil para:

• Problemas difíceis em que modelos diferentes podem adotar abordagens distintas
• Comparar a qualidade do código entre famílias de modelos
• Encontrar casos extremos (edge cases) que um modelo pode não detectar

Ao executar muitos agentes em paralelo, configure notificações e sons para saber quando eles terminarem.

#Delegando para agentes em nuvem

Agentes em nuvem funcionam bem para tarefas que você normalmente colocaria em uma lista de tarefas:

• Correções de bugs que surgiram enquanto você trabalhava em outra coisa
• Refatorações de alterações recentes no código
• Geração de testes para código existente
• Atualizações de documentação

Você pode alternar entre agentes locais e em nuvem dependendo da tarefa. Inicie agentes em nuvem em cursor.com/agents, no editor do Cursor ou pelo celular. Acompanhe as sessões pela web ou pelo celular enquanto estiver longe da sua mesa. Agentes em nuvem são executados em sandboxes remotos, então você pode fechar o laptop e conferir os resultados depois.

Veja como os agentes em nuvem funcionam nos bastidores:

1. Descreva a tarefa e qualquer contexto relevante
2. O agente clona seu repositório e cria uma branch
3. Ele trabalha de forma autônoma, abrindo um pull request ao finalizar
4. Você é notificado quando terminar (via Slack, e-mail ou interface web)
5. Revise as alterações e faça o merge quando estiver tudo certo

Dica: Você pode acionar agentes a partir do Slack com "@Cursor". Saiba mais.

#Modo de Depuração para bugs complicados

Quando as interações padrão do agente têm dificuldade com um bug, o Modo de Depuração oferece uma abordagem diferente.

Em vez de adivinhar correções, o Modo de Depuração:

1. Gera várias hipóteses sobre o que pode estar errado
2. Instrumenta seu código com mensagens de log
3. Pede que você reproduza o bug enquanto coleta dados de execução
4. Analisa o comportamento real para identificar a causa principal
5. Faz correções pontuais com base em evidências

Ele funciona melhor para:

• Bugs que você consegue reproduzir, mas não consegue resolver
• Condições de corrida e problemas de temporização
• Problemas de desempenho e vazamentos de memória
• Regressões em que algo que funcionava parou de funcionar

O ponto principal é fornecer contexto detalhado sobre como reproduzir o problema. Quanto mais específico você for, mais instrumentação útil o agente consegue adicionar.

#Desenvolvendo seu fluxo de trabalho

Os desenvolvedores que mais se beneficiam de agentes têm algumas características em comum:

Eles escrevem prompts específicos. A taxa de sucesso do agente melhora significativamente com instruções específicas. Compare "add tests for auth.ts" com "Write a test case for auth.ts covering the logout edge case, using the patterns in __tests__/ and avoiding mocks."

Eles iteram na sua configuração. Comece simples. Adicione regras apenas quando perceber que o agente está cometendo o mesmo erro repetidamente. Adicione comandos somente depois de definir um fluxo de trabalho que você queira repetir. Não otimize demais antes de entender seus padrões.

Eles revisam com cuidado. Código gerado por IA pode parecer correto e ainda assim estar sutilmente errado. Leia os diffs e revise com atenção. Quanto mais rápido o agente trabalha, mais importante se torna o seu processo de revisão.

Eles definem objetivos verificáveis. Agentes não podem corrigir o que não conhecem. Use linguagens tipadas, configure linters e escreva testes. Dê ao agente sinais claros sobre se as mudanças estão corretas.

Eles tratam agentes como colaboradores capazes. Peça planos. Solicite explicações. Questione abordagens de que você não gosta.

Os agentes estão melhorando rapidamente. Embora os padrões evoluam com modelos mais novos, esperamos que isso ajude você a ser mais produtivo hoje ao trabalhar com agentes de código.

Comece com o agente do Cursor para experimentar essas técnicas.