Skriv en opgavebeskrivelse til en agent

Beskriv en ændring, som en reviewer kan vurdere

»Tilføj kundeeksport« efterlader flere åbne beslutninger. Hvem må eksportere poster? Hvilke poster og felter medtages? Hvad sker der, når en forespørgsel fejler? En agent kan udfylde hullerne med plausible valg. Valgene kan stadig være forkerte for virksomheden.

Start med brugeren og problemet. Beskriv derefter den krævede adfærd. Medtag den dokumentation, der skal vise, om resultatet er acceptabelt.

En opgavebeskrivelse skal reducere usikkerhed uden at fastlåse alle interne designvalg. Angiv en krævet datagrænse. Lad implementeringen bruge repositoryets eksisterende mønstre, medmindre der er grund til at ændre dem.

Brug et konkret eksempel

Følgende opgavebeskrivelse gælder en fiktiv supportapplikation. Det er et undervisningseksempel, ikke en komplet specifikation til produktion.

Resultat: En supportleder kan hente en kundeliste.
Aktør: En leder i den aktuelle organisation.
Data: Kun aktive kunder i den organisation.
Felter: Kunde-ID, virksomhedsnavn og kontostatus.
Format: UTF-8 CSV med en overskriftsrække.
Afvist forespørgsel: Returnér den eksisterende fejl for manglende rettigheder.
Tomt resultat: Returnér gyldig CSV med kun overskriften.
Omfang: Brug den eksisterende eksportroute og det eksisterende auditmønster.
Uden for opgaven: Ingen nye roller, afhængigheder eller udrulning.
Dokumentation: Tests for tilladte, afviste og tomme forespørgsler samt forespørgsler på tværs af organisationer.

Beskrivelsen angiver nyttig adfærd og grænser. Den viser også flere spørgsmål. Skal systemet begrænse eksportens størrelse? Kan et felt indeholde en regnearksformel? Hvem har adgang til auditregistreringen? Afklar spørgsmål med væsentlige konsekvenser før implementering. Betragt ikke eksemplet som en universel tjekliste.

Skeln mellem krav og antagelser

Et krav angiver adfærd, som ændringen skal opfylde. En antagelse er et forhold, du endnu ikke har verificeret. Hold dem adskilt.

For eksempel forudsætter »brug det eksisterende auditmønster«, at et passende mønster findes. Bed agenten om at finde det. Hvis repositoryet ikke har et, skal agenten rapportere den manglende afhængighed, før den opfinder et nyt auditsystem.

En begrænsning kan også være i konflikt med resultatet. Den eksisterende route kan være designet til at returnere alle organisationer. Agenten skal vise konflikten og foreslå en afgrænset rettelse. Den må ikke stiltiende fjerne datagrænsen eller udvide opgaven til en omskrivning af arkitekturen.

Lad færdiggørelse omfatte dokumentation

Bed om en leverancebeskrivelse, der forklarer den endelige adfærd, ændringer i omfanget og de udførte kontroller. Kræv præcise kommandoer og resultater, hvor de har betydning. Skeln mellem en bestået kontrol og en kontrol, der ikke kunne køres.

Pull requesten skal bevare begrundelsen for ændringen. En senere vedligeholder kan se koden uden den oprindelige samtale. Medtag nok kontekst til at forklare, hvorfor eksporten udelader bestemte felter, og hvordan adgangen håndhæves.

Googles vejledning om ændringsbeskrivelser er en nyttig reference. Beskrivelsen skal forklare ændringen og dens formål. Hold dokumentationen i overensstemmelse med den endelige implementering efter rettelser fra review.

Tilpas beskrivelsens omfang til opgaven

En lille tekstrettelse kan have en kort opgavebeskrivelse. En dataeksport kræver flere detaljer, fordi fejl kan eksponere oplysninger. En ny betalingsproces kræver endnu mere analyse og review.

Mål ikke beskrivelsens kvalitet på dens længde. Spørg, om en kompetent reviewer kan skelne et korrekt resultat fra et forkert. Hvis to rimelige implementeringer ville være uenige om en vigtig adfærd, skal den afklares først.