Schrijf een taakbeschrijving voor een agent

Beschrijf een wijziging die een reviewer kan beoordelen

‘Voeg klantexport toe’ laat meerdere besluiten open. Wie mag records exporteren? Welke records en velden horen erbij? Wat gebeurt er als een verzoek mislukt? Een agent kan deze gaten invullen met aannemelijke keuzes. Die keuzes kunnen toch verkeerd zijn voor de bedrijfsvoering.

Begin met de gebruiker en het probleem. Beschrijf daarna het vereiste gedrag. Neem het bewijs op dat zal tonen of het resultaat aanvaardbaar is.

Een taakbeschrijving moet onzekerheid verminderen zonder elke interne ontwerpkeuze vast te leggen. Specificeer een noodzakelijke gegevensgrens. Laat de implementatie bestaande repositorypatronen gebruiken, tenzij er een reden is om ze te wijzigen.

Gebruik een concreet voorbeeld

De volgende taakbeschrijving is voor een fictieve supportapplicatie. Het is een leervoorbeeld, geen volledige productiespecificatie.

Resultaat: Een supportmanager kan een klantenlijst downloaden.
Actor: Een manager in de huidige organisatie.
Gegevens: Alleen actieve klanten in die organisatie.
Velden: Klant-ID, bedrijfsnaam en accountstatus.
Formaat: UTF-8 CSV met een koprij.
Geweigerd verzoek: Geef de bestaande autorisatiefout terug.
Leeg resultaat: Geef een geldige CSV terug met alleen de koprij.
Scope: Gebruik de bestaande exportroute en het auditpatroon.
Uitgesloten: Geen nieuwe rollen, dependencies of deployment.
Bewijs: Tests voor toegestane, geweigerde, lege en organisatieoverschrijdende verzoeken.

Deze beschrijving benoemt bruikbaar gedrag en grenzen. Ze maakt ook verdere vragen zichtbaar. Moet het systeem de exportgrootte beperken? Kan een veld een spreadsheetformule bevatten? Wie krijgt toegang tot het auditrecord? Los vragen met belangrijke gevolgen vóór implementatie op. Behandel het voorbeeld niet als universele checklist.

Scheid eisen van aannames

Een eis beschrijft gedrag waaraan de wijziging moet voldoen. Een aanname is een feit dat u nog niet hebt geverifieerd. Houd ze gescheiden.

‘Gebruik het bestaande auditpatroon’ neemt bijvoorbeeld aan dat een geschikt patroon bestaat. Vraag de agent het te vinden. Als de repository er geen heeft, moet de agent de ontbrekende dependency melden voordat een nieuw auditsysteem wordt bedacht.

Een beperking kan ook botsen met het resultaat. De bestaande route kan bewust elke organisatie teruggeven. De agent moet het conflict tonen en een beperkte correctie voorstellen. De agent mag niet ongemerkt de gegevensgrens verwijderen of de taak uitbreiden tot het herschrijven van de architectuur.

Laat bewijs bij afronding horen

Vraag een opleveringssamenvatting die het uiteindelijke gedrag, de gewijzigde scope en de uitgevoerde controles uitlegt. Vereis exacte opdrachten en resultaten waar die belangrijk zijn. Maak onderscheid tussen een geslaagde controle en een controle die niet kon draaien.

De pull request moet de reden voor de wijziging bewaren. Een latere beheerder ziet mogelijk de code zonder het oorspronkelijke gesprek. Geef voldoende context om uit te leggen waarom de export bepaalde velden uitsluit en hoe toegang wordt afgedwongen.

Google’s advies voor wijzigingsbeschrijvingen is een bruikbare referentie. De beschrijving moet de wijziging en het doel uitleggen. Houd de documentatie na reviewwijzigingen in lijn met de uiteindelijke implementatie.

Houd de beschrijving in verhouding

Een kleine tekstcorrectie kan met een korte beschrijving. Een gegevensexport heeft meer detail nodig omdat fouten informatie kunnen blootleggen. Een nieuwe betaalworkflow vereist nog meer analyse en review.

Meet de kwaliteit van een taakbeschrijving niet aan de lengte. Vraag of een bekwame reviewer een correct resultaat van een onjuist resultaat kan onderscheiden. Verduidelijk het gedrag eerst als twee redelijke implementaties van mening zouden verschillen over gedrag met belangrijke gevolgen.