Escriviu un encàrrec per a un agent

Descriviu un canvi que es pugui revisar

«Afegiu l’exportació de dades de clients» deixa diverses decisions obertes. Qui pot exportar registres? Quins registres i camps s’inclouen? Què passa quan una petició falla? Un agent pot omplir aquests buits amb opcions plausibles. Tot i així, poden ser incorrectes per al negoci.

Comenceu per l’usuari i el problema. Després descriviu el comportament requerit. Incloeu les evidències que mostraran si el resultat és acceptable.

Un encàrrec ha de reduir la incertesa sense fixar totes les decisions de disseny intern. Especifiqueu el límit de dades requerit. Deixeu que la implementació utilitzi els patrons existents del repositori, llevat que hi hagi un motiu per canviar-los.

Utilitzeu un exemple concret

L’encàrrec següent és per a una aplicació fictícia de suport. És un exemple educatiu, no una especificació completa per a producció.

Resultat: Un responsable de suport pot descarregar una llista de clients.
Actor: Un responsable de l'organització actual.
Dades: Només els clients actius d'aquesta organització.
Camps: Identificador de client, nom de l'empresa i estat del compte.
Format: CSV UTF-8 amb una fila de capçalera.
Petició denegada: Retorneu l'error d'autorització existent.
Resultat buit: Retorneu un CSV vàlid amb només la capçalera.
Abast: Utilitzeu la ruta d'exportació i el patró d'auditoria existents.
Exclusions: Cap rol nou, dependència nova ni desplegament.
Evidències: Proves de peticions permeses, denegades, buides i entre organitzacions.

Aquest encàrrec identifica comportaments i límits útils. També revela altres preguntes. El sistema ha de limitar la mida de l’exportació? Un camp pot contenir una fórmula de full de càlcul? Qui pot accedir al registre d’auditoria? Resoleu les preguntes amb conseqüències importants abans de la implementació. No tracteu l’exemple com una llista de comprovació universal.

Separeu els requisits de les hipòtesis

Un requisit indica un comportament que el canvi ha de satisfer. Una hipòtesi és un fet que encara no heu verificat. Manteniu-los separats.

Per exemple, «utilitzeu el patró d’auditoria existent» suposa que n’hi ha un d’adequat. Demaneu a l’agent que el trobi. Si el repositori no en té cap, l’agent ha d’informar d’aquest element necessari que falta abans d’inventar un sistema d’auditoria nou.

Una restricció també pot entrar en conflicte amb el resultat. La ruta existent podria retornar totes les organitzacions per disseny. L’agent ha de mostrar el conflicte i proposar una correcció limitada. No ha d’eliminar el límit de dades sense dir-ho ni ampliar la tasca fins a reescriure l’arquitectura.

Feu que acabar inclogui les evidències

Demaneu un resum del lliurament que expliqui el comportament final, els canvis d’abast i les comprovacions fetes. Exigiu les ordres i els resultats exactes quan siguin rellevants. Distingiu una comprovació superada d’una que no s’ha pogut executar.

La pull request ha de conservar el motiu del canvi. Més endavant, una persona de manteniment pot veure el codi sense la conversa original. Incloeu prou context per explicar per què l’exportació exclou determinats camps i com es fa complir el control d’accés.

Les directrius de Google sobre descripcions de canvis són una referència útil per a aquest registre. La descripció ha d’explicar el canvi i la seva finalitat. Manteniu el registre alineat amb la implementació final després dels canvis de revisió.

Adapteu l’encàrrec a la tasca

Una petita correcció de text pot tenir un encàrrec breu. Una exportació de dades necessita més detall perquè les seves fallades poden exposar informació. Un nou flux de pagament necessita encara més anàlisi i revisió.

No mesureu la qualitat d’un encàrrec per la llargada. Pregunteu-vos si una persona competent podria distingir un resultat correcte d’un d’incorrecte en revisar-lo. Si dues implementacions raonables no coincidirien en un comportament amb conseqüències importants, aclariu-lo primer.