Escreva um enunciado de tarefa para um agente

Descreva uma alteração que o revisor consiga avaliar

«Acrescentar exportação de clientes» deixa várias decisões em aberto. Quem pode exportar registos? Que registos e campos são incluídos? O que acontece se um pedido falhar? Um agente pode preencher estas lacunas com escolhas plausíveis. Ainda assim, podem estar erradas para o negócio.

Comece pelo utilizador e pelo problema. Depois descreva o comportamento exigido. Inclua as provas que permitem saber se o resultado é aceitável.

Um enunciado deve reduzir a incerteza sem fixar todas as decisões internas de conceção. Especifique o limite de dados exigido. Deixe a implementação usar os padrões existentes no repositório, salvo se houver uma razão para os alterar.

Use um exemplo concreto

O enunciado seguinte destina-se a uma aplicação fictícia de apoio ao cliente. É um exemplo educativo, não uma especificação completa para produção.

Resultado: Um gestor de apoio ao cliente pode descarregar uma lista de clientes.
Interveniente: Um gestor da organização atual.
Dados: Apenas clientes ativos dessa organização.
Campos: ID do cliente, nome da empresa e estado da conta.
Formato: CSV em UTF-8 com uma linha de cabeçalho.
Pedido recusado: Devolver o erro de autorização existente.
Resultado vazio: Devolver um CSV válido só com o cabeçalho.
Âmbito: Usar a rota de exportação e o padrão de auditoria existentes.
Exclusões: Sem novos papéis, dependências ou deployment.
Provas: Testes para pedidos permitidos, recusados, vazios e entre organizações.

Este enunciado identifica um comportamento útil e os seus limites. Também revela novas questões. O sistema deve limitar o tamanho da exportação? Um campo pode conter uma fórmula de folha de cálculo? Quem pode aceder ao registo de auditoria? Resolva as questões com consequências relevantes antes da implementação. Não trate o exemplo como uma lista de verificação universal.

Separe requisitos de pressupostos

Um requisito estabelece um comportamento que a alteração tem de cumprir. Um pressuposto é um facto ainda não verificado. Mantenha-os separados.

Por exemplo, «usar o padrão de auditoria existente» pressupõe que existe um padrão adequado. Peça ao agente que o encontre. Se não existir no repositório, o agente deve comunicar a dependência em falta antes de inventar um novo sistema de auditoria.

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

Inclua as provas na condição de conclusão

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

O pull request deve preservar a razão da alteração. Quem fizer manutenção mais tarde pode ver o código sem a conversa original. Inclua contexto suficiente para explicar por que motivo a exportação exclui certos campos e como se impõem os limites de acesso.

As orientações da Google sobre descrições de alterações são uma referência útil para este registo. A descrição deve explicar a alteração e o seu objetivo. Após correções da revisão, mantenha o registo alinhado com a implementação final.

Ajuste o detalhe à tarefa

Uma pequena correção de texto pode ter um enunciado curto. Uma exportação de dados exige mais detalhe porque uma falha pode expor informação. Um novo processo de pagamentos exige ainda mais análise e revisão.

Não meça a qualidade do enunciado pelo comprimento. Pergunte se um revisor competente consegue distinguir um resultado correto de um incorreto. Se duas implementações razoáveis puderem divergir num comportamento com consequências relevantes, esclareça-o primeiro.