Skriv en uppgiftsbeskrivning för en agent

Beskriv en ändring som en granskare kan bedöma

”Lägg till kundexport” lämnar flera beslut öppna. Vem får exportera poster? Vilka poster och fält ingår? Vad händer när en förfrågan misslyckas? En agent kan fylla luckorna med rimliga val. Valen kan ändå vara fel för verksamheten.

Börja med användaren och problemet. Beskriv sedan nödvändigt beteende. Ta med underlaget som visar om resultatet är acceptabelt.

En uppgiftsbeskrivning ska minska osäkerhet utan att låsa varje internt designval. Ange en nödvändig datagräns. Låt implementationen använda repositoryts befintliga mönster om det inte finns skäl att ändra dem.

Använd ett konkret exempel

Följande uppgiftsbeskrivning gäller en fiktiv supportapplikation. Den är ett undervisningsexempel, inte en fullständig produktionsspecifikation.

Resultat: En supportchef kan ladda ned en kundlista.
Aktör: En chef i den aktuella organisationen.
Data: Endast aktiva kunder i den organisationen.
Fält: Kund-ID, företagsnamn och kontostatus.
Format: UTF-8 CSV med rubrikrad.
Nekad förfrågan: Returnera befintligt auktoriseringsfel.
Tomt resultat: Returnera en giltig CSV med bara rubrikraden.
Omfång: Använd befintlig exportroute och befintligt revisionsmönster.
Undantaget: Inga nya roller, beroenden eller driftsättningar.
Underlag: Tester för tillåtna, nekade, tomma och organisationsöverskridande förfrågningar.

Beskrivningen identifierar användbart beteende och gränser. Den visar också fler frågor. Ska systemet begränsa exportstorleken? Kan ett fält innehålla en kalkylbladsformel? Vem får läsa revisionsloggen? Lös frågor med betydande konsekvenser före implementation. Behandla inte exemplet som en universell checklista.

Skilj krav från antaganden

Ett krav anger beteende som ändringen måste uppfylla. Ett antagande är en uppgift som du ännu inte har verifierat. Håll dem åtskilda.

Till exempel antar ”använd befintligt revisionsmönster” att ett lämpligt mönster finns. Be agenten hitta det. Om repositoryt saknar ett ska agenten rapportera det saknade beroendet innan den uppfinner ett nytt revisionssystem.

En begränsning kan också strida mot resultatet. Den befintliga routen kan vara avsedd att returnera alla organisationer. Agenten ska visa konflikten och föreslå en begränsad rättning. Den ska inte tyst ta bort datagränsen eller utöka uppgiften till en arkitekturomskrivning.

Låt färdigt omfatta underlag

Begär en leveranssammanfattning som förklarar slutligt beteende, ändrat omfång och utförda kontroller. Kräv exakta kommandon och resultat där de spelar roll. Skilj en godkänd kontroll från en som inte kunde köras.

Pull requesten ska bevara skälet till ändringen. En framtida underhållsansvarig kan se koden utan det ursprungliga samtalet. Ta med tillräckligt med kontext för att förklara varför exporten utesluter vissa fält och hur åtkomsten upprätthålls.

Googles vägledning för ändringsbeskrivningar är en användbar referens. Beskrivningen ska förklara ändringen och dess syfte. Håll den i linje med den slutliga implementationen efter granskningsändringar.

Anpassa beskrivningens omfattning

En liten texträttning kan ha en kort beskrivning. En dataexport behöver mer detaljer eftersom fel kan exponera information. Ett nytt betalningsflöde behöver ännu mer analys och granskning.

Mät inte kvaliteten i längd. Fråga om en kompetent granskare kan skilja ett korrekt resultat från ett felaktigt. Om två rimliga implementationer skulle skilja sig i ett beteende med betydande konsekvenser ska du förtydliga det först.