Limitar a primeira tarefa do agente na nuvem do Cursor a uma correção verificável

Entregar ao Cursor um pequeno erro reproduzível e esperar que devolva um PR para revisão humana é uma boa primeira forma de experimentar um agente em segundo plano. Uma tarefa adequada para delegação deve cumprir três condições ao mesmo tempo: o comportamento esperado está claro, pode ser verificado no ambiente remoto e uma pessoa responsável consegue compreender o alcance das alterações. Se faltar alguma dessas condições, é mais útil resolvê-la primeiro do que continuar a ampliar o prompt.

O Cursor chama atualmente este produto de Cloud Agents; antes, o nome era Background Agents. Ele trabalha numa máquina virtual isolada na nuvem, em vez de assumir o controlo do diretório de trabalho local atual. Nas tarefas de repositório, altera e entrega o código numa ramificação separada. A análise a seguir sobre a escolha de tarefas baseia-se na documentação oficial; o exemplo não foi executado.

Suponha que um projeto tenha um endpoint de listagem: uma consulta vazia válida deveria devolver um array vazio, mas provoca uma exceção. A equipa já confirmou o comportamento correto e há testes relevantes. Essa tarefa é mais adequada para delegação do que «melhorar a pesquisa», porque o agente pode investigar a causa, alterar a implementação e acrescentar um teste de regressão com base num resultado observável. Quem faz a revisão também consegue avaliar se a correção está certa.

O mesmo critério aplica-se à adição de testes para casos-limite conhecidos, à correção de exemplos na documentação que não correspondem à interface existente e à eliminação de código duplicado dentro de um âmbito bem definido. No entanto, a refatoração também exige testes existentes para proteger o comportamento observável externamente. Se não houver testes, deve-se pedir primeiro a identificação dos componentes que chamam o código e a criação de testes, sem solicitar ao mesmo tempo grandes alterações estruturais.

A correção acima poderia ser delegada com estas instruções:

• Reproduzir a exceção do endpoint de listagem ao processar uma consulta vazia válida. Primeiro, acrescentar um teste de regressão que falhe com a implementação antiga.
• Corrigir o resultado dessa entrada para devolver uma resposta de sucesso e um array vazio. Preservar o tratamento atual de entradas inválidas, sem alterar os parâmetros da interface nem a estrutura da resposta.
• Alterar apenas a implementação e os testes relacionados. Não atualizar dependências nem alterar a autorização, o esquema da base de dados ou a configuração de implantação. Se for necessário ultrapassar esse âmbito, explicar primeiro o motivo e parar.
• Executar os testes relevantes e as verificações existentes do projeto. Registar os comandos, os resultados e as verificações que não foi possível executar. Entregar um PR em rascunho que explique a causa raiz, os ficheiros alterados, as evidências de verificação e os riscos restantes. Não fazer a integração do PR.

Este é um exemplo de tarefa para análise, não um script diretamente executável que afirme que esses ficheiros ou comandos existem. Numa delegação real, também é necessário indicar o repositório, o commit de referência, a entrada concreta que reproduz o problema e os comandos de teste do projeto. Na aceitação, deve-se confirmar que o novo teste cobre realmente o erro original, em vez de olhar apenas para «testes aprovados». Se o agente removeu as asserções ou alterou o teste para tornar o comportamento incorreto no resultado esperado, um indicador verde continua sem significar nada.

A documentação de ambientes do Cursor explica que os agentes alojados na nuvem são executados em Ubuntu e podem ser configurados com a orientação do agente ou através de um Dockerfile. As ferramentas já instaladas localmente, os ficheiros ainda não incluídos num commit ou as ligações a serviços privados não podem, por isso, ser considerados disponíveis no ambiente remoto. Antes de colocar a correção na fila, é preciso verificar se as dependências podem ser instaladas, se os testes podem ser iniciados e se os serviços necessários estão acessíveis.

O repositório, os repositórios dos quais depende e os submódulos precisam das permissões de leitura e escrita correspondentes. Se a tarefa depender de componentes disponíveis apenas no computador de um programador, ou se os testes precisarem de aceder a um serviço da rede interna cujo acesso ainda não foi autorizado, é necessário resolver primeiro o ambiente e as permissões. Não se devem apresentar falhas de instalação ou tempos de espera de rede excedidos como código já verificado. É possível reduzir a tarefa à entrega de uma análise da causa e de sugestões de alteração, ou adotar um modo de trabalho local e interativo com acesso ao ambiente necessário.

Para a primeira tarefa, é preferível escolher uma correção que não exija dados nem credenciais de produção e usar exemplos sem informações sensíveis ou duplos de teste. Se não for possível estabelecer um ambiente de verificação fiável, a tarefa ainda não é adequada para avançar sem supervisão até ficar pronta para integração.

A documentação do Cursor indica que Cloud Agents tem acesso à Internet por predefinição e executa automaticamente os comandos do terminal. Pode continuar a executar testes, mas também pode ser afetado por uma injeção de prompt depois de ler conteúdo malicioso. Uma ramificação separada pode isolar alterações de código, mas não pode recuperar dados já enviados para o exterior. Usar «alguém vai rever o PR no final» como limite de segurança durante a execução não é suficiente.

Antes de iniciar, devem-se limitar os destinos externos permitidos e fornecer apenas as permissões e credenciais necessárias à tarefa. O Cursor oferece Runtime Secrets, que oculta valores nas saídas das ferramentas, nos históricos de conversas e nos commits. Contudo, esses valores continuam disponíveis para os programas como variáveis de ambiente e permanecem visíveis aos utilizadores que interagem com o ambiente através do terminal. Ocultar os valores na saída não impede a utilização das credenciais nem substitui a limitação do alcance das suas permissões.

Por isso, migrações de bases de dados de produção, alterações às regras de pagamento ou autorização e grandes mudanças que dependam de decisões de produto ainda não definidas não são boas escolhas para uma primeira tarefa sem supervisão. Esta é uma recomendação de seleção de tarefas baseada no alcance do impacto, não uma afirmação de que o produto não consegue alterar esse código. Primeiro, as pessoas devem definir as restrições do negócio e os riscos; depois, dividir o trabalho em pequenas alterações que possam ser verificadas de forma independente.

O processo de entrega descrito oficialmente consiste em enviar a ramificação para o repositório remoto e abrir um PR para revisão humana; também é possível pedir um rascunho. A equipa deve usar esse processo para esclarecer responsabilidades: o agente fornece as alterações e as evidências, enquanto a pessoa responsável decide se os requisitos foram cumpridos, se os riscos são aceitáveis e se deve fazer a integração. A mensagem de conclusão do agente não deve ser entendida como autorização para integrar o código.

Durante a revisão, primeiro é preciso confirmar que as diferenças permanecem dentro do âmbito original e, depois, voltar a executar os principais testes de regressão e as verificações de integração necessárias. Devem-se examinar os ramos de tratamento de erros, os componentes que chamam o código, as alterações de dependências e a eventual exposição de dados nos registos. As verificações que não puderam ser executadas devem ficar documentadas no PR, indicando claramente quem as irá completar. Se as alterações continuarem a alargar-se, os testes com falhas forem repetidamente contornados ou forem necessárias novas decisões de negócio, deve-se regressar a uma discussão interativa e dividir novamente a tarefa.

O benefício de um agente em segundo plano depende da qualidade da entrega. Comece por uma pequena correção que possa ser reproduzida sem permissões de produção, tenha um resultado claro e possa ser revista na íntegra. Só depois de o ambiente e o processo de revisão passarem por esta primeira experiência deve ser ampliado o âmbito da delegação.