Engenharia de Contexto para Agentes de Codificação em Background Lições da Spotify

Quando você tem um agente de codificação em background capaz de editar código, executar builds e abrir pull requests automaticamente, um desafio crítico surge: Como você diz efetivamente a ele o que fazer? Ir além de simplesmente executar o agente e produzir Pull Requests (PRs) confiáveis e mescláveis em codebases do mundo real requer uma Engenharia de Contexto meticulosa. Este post compartilha insights valiosos da experiência da Spotify automatizando milhares de PRs em centenas de repositórios, mergulhando na criação eficaz de prompts e no design de ferramentas para agentes. Você pode encontrar o material fonte detalhado aqui.

Armadilhas de Prompt e Lições Aprendidas na Prática

Ao experimentar com agentes open-source iniciais e seu próprio loop agentivo, a equipe da Spotify identificou dois grandes antipadrões.

1. O Prompt Excessivamente Genérico: Espera que o agente adivinhe telepaticamente a intenção e o resultado desejado. Uma instrução como "melhore este código" não fornece um objetivo verificável, levando à confusão do agente.
2. O Prompt Excessivamente Específico: Tenta cobrir todos os casos possíveis, mas desmorona ao encontrar o inesperado. Instruções passo a passo muito rígidas sufocam a flexibilidade do agente e esgotam rapidamente a janela de contexto durante mudanças complexas e multi-etapas.

A transição para o Claude Code rendeu princípios-chave:

• Adapte os Prompts ao Agente: O Claude Code tem melhor desempenho com prompts que descrevem o estado final desejado e deixam espaço para ele descobrir o caminho.
• Declare Pré-condições: Inclua instruções que bloqueiem preventivamente tarefas impossíveis, por exemplo, "Não tome ação se o repositório usar um nível de linguagem inferior ao Java 11."
• Use Exemplos: Alguns exemplos de código concretos influenciam fortemente o resultado.
• Defina um Objetivo Verificável: Idealmente, defina o estado final desejado na forma de testes. O agente precisa de um benchmark para melhorar iterativamente sua solução.
• Faça Uma Mudança de Cada Vez: Agrupar várias mudanças relacionadas em um prompt elaborado pode parecer conveniente, mas aumenta muito o risco de esgotamento da janela de contexto ou resultados parciais.
• Peça Feedback do Agente sobre o Prompt: Após uma sessão, o próprio agente é surpreendentemente hábil em identificar o que faltava no prompt. Use isso para refinar prompts futuros.

A Arte da Limitação de Ferramentas para Previsibilidade

Embora você possa conectar um agente a inúmeras ferramentas (como ferramentas MCP) para buscar contexto dinamicamente para tarefas complexas, isso reduz a testabilidade e a previsibilidade. Mais ferramentas introduzem mais dimensões de imprevisibilidade.

A Spotify mantém as ferramentas e hooks de seu agente de codificação em background muito limitados, projetados para focar na geração da alteração de código correta a partir de um prompt.

Conjunto de Ferramentas Principal Atual:

• Ferramenta verify: Executa formatadores, linters e testes. Ela abstrai a invocação dos sistemas de build internos em milhares de repositórios distintos e resume os logs em um formato digerível para o agente.
• Ferramenta Git: Fornece acesso Git limitado e padronizado. Comandos perigosos como push ou alterar origin não são expostos, enquanto ações como definir o committer e usar formatos de mensagem de commit padrão são padronizadas.
• Ferramenta Bash: Uma ferramenta Bash com lista de permissões estrita, com acesso a alguns comandos como ripgrep.

Notavelmente, ferramentas de busca de código ou documentação não estão atualmente expostas ao agente. Em vez disso, pede-se aos usuários que condensem o contexto relevante no prompt antecipadamente, ou usem agentes de fluxo de trabalho separados para gerar prompts para o agente de codificação a partir de várias fontes.

Limitações e Considerações Críticas

O estado atual da engenharia de agentes e prompts ainda depende muito da intuição e da tentativa e erro. Falta maneiras estruturadas de avaliar quais prompts ou modelos têm melhor desempenho, e os loops de feedback para verificar se um PR mesclado realmente resolveu o problema original ainda são incipientes. O impacto na mantenabilidade a longo prazo do código gerado pelo agente também permanece uma questão em aberto.

O Caminho a Seguir: Próximos Passos de Aprendizado

A verdadeira maturidade desta tecnologia depende da construção de loops de feedback mensuráveis. Além das taxas de mesclagem de PRs, devemos explorar maneiras de avaliar quantitativamente a qualidade do código gerado, a redução no tempo de revisão e o impacto final na estabilidade do sistema. Além disso, cultivar uma cultura onde os prompts são controlados por versão e testados como código é crucial para uma automação sustentável.