Assistentes de código: como delimitar bem uma tarefa

Um desenvolvedor autônomo pede ao seu assistente de código: “Adicione uma exportação CSV das notas fiscais.” Vinte minutos depois, a ferramenta mexeu em onze arquivos, adicionou uma biblioteca, reformatou dois módulos que não tinham nada a ver com o assunto e escreveu uma exportação que esquece as notas de crédito. Nada quebrou de forma visível, e mesmo assim é preciso reler tudo.

Os assistentes de código atuais não se limitam mais a completar uma linha. Eles leem o projeto, alteram vários arquivos, executam comandos e testes. Quanto mais a ferramenta age sozinha, mais o seu pedido deve se parecer com o briefing que se passa a um prestador que você só vai ver na entrega.

O que um briefing de tarefa contém

Cinco elementos bastam na maioria dos casos.

1. O objetivo, dito em termos de resultado: o que o usuário ou o sistema poderá fazer depois.
2. O escopo: os arquivos ou pastas envolvidos, e o que não deve ser tocado.
3. As restrições: tecnologias obrigatórias, convenções, dependências proibidas.
4. O critério de sucesso: como você vai saber que terminou, de preferência um comando ou um teste.
5. O modo de trabalhar: propor um plano antes de alterar, ou avançar em pequenas etapas.

Aqui está o briefing do desenvolvedor, refeito com cuidado:

Objetivo: adicionar uma exportação CSV das notas fiscais de um mês específico, acessível a partir da página Faturamento.

Escopo: você pode alterar o módulo faturamento/ e a página Faturamento. Não toque nos outros módulos nem na configuração do projeto.

Restrições: nenhuma dependência nova, use o módulo CSV da biblioteca padrão. Mesmo estilo das exportações existentes (veja export_clientes).

Regras de negócio: a exportação contém as notas fiscais e as notas de crédito do mês. As notas de crédito entram com valor negativo. Os valores estão em centavos no banco de dados e em euros com duas casas decimais no arquivo.

Critério de sucesso: os testes existentes passam, e você adiciona um teste que verifica um mês contendo uma nota fiscal e uma nota de crédito.

Antes de alterar qualquer coisa, descreva o seu plano em no máximo cinco linhas e aguarde o meu OK.

A última frase é a que mais compensa. Um plano errado se corrige em dez segundos; um código errado se corrige em dez minutos.

O que a ferramenta não consegue adivinhar

As regras de negócio não estão escritas em lugar nenhum do código, ou então estão de forma indireta. O fato de as notas de crédito entrarem na exportação, de os valores estarem em centavos, de a página se chamar Faturamento: o assistente pode redescobrir uma parte disso lendo o projeto, mas você ganha tempo escrevendo. É melhor dizer uma coisa óbvia a mais do que receber uma exportação errada e plausível.

Tudo o que você repete de uma tarefa para a outra (convenções, comandos de teste, pastas a evitar) pode ir para um arquivo de instruções lido automaticamente pela ferramenta. O nome do arquivo e o local dependem do assistente que você usa. O artigo sobre instruções para agentes de IA explica como redigi-lo sem transformá-lo em um romance.

Uma mudança por vez

A tentação, quando a ferramenta é rápida, é empilhar os pedidos: a exportação, depois um filtro, depois uma reformulação da página, tudo na mesma sessão. Cada acréscimo torna o resultado mais difícil de revisar. Pegue o hábito de dividir, como em uma cadeia de prompts:

• uma tarefa, um objetivo, um resultado verificável;
• um backup do seu trabalho (um commit) antes de cada tarefa, para poder voltar atrás;
• uma sessão nova quando o assunto muda, porque a conversa vai ficando pesada e a ferramenta acaba perdendo detalhes do início.

Se a tarefa for grande demais para um briefing de uma página, peça primeiro uma divisão:

Quero migrar a autenticação do aplicativo para [NOVO MÉTODO]. Não altere nada por enquanto. Percorra o projeto, liste os arquivos envolvidos e proponha uma divisão em etapas independentes, cada uma testável isoladamente. Para cada etapa, indique o principal risco.

Depois você escolhe a etapa a executar e escreve o briefing dela.

Revisar o resultado

O trabalho não termina quando a ferramenta diz “pronto”. Quatro verificações, nesta ordem.

Primeiro, o diff. Olhe a lista de arquivos modificados antes de abrir um único arquivo. Se ela contiver arquivos fora do escopo, pergunte por quê, ou desfaça.

Depois, os testes, executados por você, se possível. Um assistente pode afirmar que os testes passam sem tê-los executado direito, ou alterar um teste para fazê-lo passar. Confira se os testes existentes não foram mudados sem motivo.

Os casos-limite. Retome as regras de negócio do seu briefing e teste-as manualmente: o mês sem nota fiscal, a nota de crédito maior que a nota fiscal, o valor zerado.

Os acréscimos discretos. Uma dependência nova, um arquivo de configuração, a remoção de um trecho de código que ele julgou inútil: peça à ferramenta que os liste, se ela não o fez.

Resuma o que você modificou, arquivo por arquivo, em uma linha cada. Indique o que você removeu, adicionou como dependência ou alterou fora do escopo pedido. Liste em seguida os casos-limite que você não testou.

Esse resumo não substitui a sua revisão do diff, porque a ferramenta pode esquecer de mencionar uma modificação. Ele apenas indica onde olhar.

Quando não funciona

Se o assistente anda em círculos, corrija a causa em vez de repetir o pedido. Muitas vezes é um contexto que faltou ou uma instrução contraditória no briefing. Recomece com uma sessão nova e um briefing corrigido, em vez de acrescentar “não, assim não” vinte vezes. Para as tarefas de revisão, depuração ou geração de testes fora desse quadro, o artigo sobre prompts para desenvolvedores traz outros modelos, e o do GitHub Copilot detalha o trabalho dentro do editor.

E mantenha o controle sobre o que a ferramenta pode fazer: executar comandos, apagar arquivos, acessar a rede. Leia o que o seu assistente pede para você autorizar antes de aceitar, e evite abrir para ele o acesso a chaves ou a bancos de produção em uma tarefa que não precisa disso.

Para fazer antes da sua próxima tarefa

Pegue uma tarefa que você vai confiar ao assistente esta semana. Escreva as cinco linhas do briefing, incluindo o comando que vai provar que terminou. Se você não sabe escrever esse comando, a tarefa ainda não está clara o bastante, e esta é a hora de descobrir.