Escreva uma descrição de tarefa para um agente

Descreva uma alteração que o revisor possa avaliar

“Adicionar exportação de clientes” deixa várias decisões em aberto. Quem pode exportar registros? Quais registros e campos são incluídos? O que acontece quando uma requisição falha? Um agente pode preencher essas lacunas com escolhas plausíveis. Elas ainda podem estar erradas para o negócio.

Comece pelo usuário e pelo problema. Depois, descreva o comportamento exigido. Inclua as evidências que mostrarão se o resultado é aceitável.

A descrição deve reduzir a incerteza sem determinar cada decisão interna de projeto. Especifique o limite de dados exigido. Deixe a implementação seguir os padrões existentes no repositório, a menos que haja motivo para alterá-los.

Use um exemplo concreto

A descrição a seguir se refere a uma aplicação fictícia de suporte. É um exemplo educativo, não uma especificação completa de produção.

Resultado: Um gerente de suporte pode baixar uma lista de clientes.
Usuário: Um gerente da organização atual.
Dados: Somente clientes ativos dessa organização.
Campos: ID do cliente, nome da empresa e status da conta.
Formato: CSV em UTF-8 com uma linha de cabeçalho.
Requisição negada: Retornar o erro de autorização existente.
Resultado vazio: Retornar um CSV válido apenas com o cabeçalho.
Escopo: Usar a rota de exportação e o padrão de auditoria existentes.
Exclusões: Sem novos papéis, dependências ou deployment.
Evidências: Testes para requisições permitidas, negadas, vazias e entre organizações.

Essa descrição identifica o comportamento útil e seus limites. Também revela outras perguntas. O sistema deve limitar o tamanho da exportação? Um campo pode conter uma fórmula de planilha? Quem pode acessar o registro de auditoria? Resolva questões de maior consequência antes da implementação. Não trate o exemplo como uma checklist universal.

Separe requisitos de premissas

Um requisito define o comportamento que a alteração deve atender. Uma premissa é um fato que você ainda não verificou. Mantenha-os separados.

Por exemplo, “Use o padrão de auditoria existente” pressupõe que exista um padrão adequado. Peça ao agente que o encontre. Se o repositório não tiver nenhum, o agente deve informar essa dependência ausente antes de inventar um novo sistema de auditoria.

Uma restrição também pode entrar em conflito com o resultado. A rota existente pode retornar todas as organizações por decisão de projeto. O agente deve mostrar o conflito e propor uma correção limitada. Não deve remover silenciosamente o limite de dados nem ampliar a tarefa para uma reescrita da arquitetura.

Inclua evidências na conclusão

Peça um resumo da entrega que explique o comportamento final, as mudanças de escopo e as verificações executadas. Exija comandos e resultados exatos quando forem relevantes. Diferencie uma verificação que passou de uma que não pôde ser executada.

O pull request deve preservar o motivo da alteração. Um futuro mantenedor pode ver o código sem a conversa original. Inclua contexto suficiente para explicar por que a exportação exclui determinados campos e como o acesso é controlado.

As orientações do Google sobre descrições de alterações são uma referência útil para esse registro. A descrição deve explicar a alteração e seu objetivo. Mantenha o registro alinhado à implementação final depois das correções de revisão.

Mantenha a descrição proporcional

Uma pequena correção de texto pode ter uma descrição curta. Uma exportação de dados precisa de mais detalhes porque suas falhas podem expor informações. Um novo fluxo de pagamentos exige ainda mais análise e revisão.

Não meça a qualidade da descrição pelo tamanho. Pergunte se um revisor competente conseguiria distinguir um resultado correto de um incorreto. Se duas implementações razoáveis puderem divergir quanto a um comportamento com consequências relevantes, esclareça esse comportamento primeiro.