En bra story är inte en lång en

När en agent kommer tillbaka med något som missat målet är den naturliga reaktionen att skriva mer nästa gång: mer detalj, mer bakgrund, mer prosa. Men längd är ett dåligt mått på kvalitet. En spec som konkurrerar med en RFC gör inte en agent skarpare — bortom en viss punkt arbetar ren storlek emot den, eftersom "kontextfönstrets gränser och modellens 'uppmärksamhetsbudget' kommer i vägen". Det bättre greppet är att bryta ner stora uppgifter i mindre istället för att packa allt i en enda jätteprompt. [1]

Målet var aldrig en längre ticket. Det handlar om att ta bort tvetydigheten som annars dyker upp som dålig kod och bullrig granskning — som en leverantör av agentverktyg uttrycker det. [2] En story bedöms efter en enda sak: kommer agenten tillbaka med det du menade byggt? Allt annat är dekoration.

Anledningen till att detta spelar större roll nu är att läsaren har förändrats. En user story har alltid varit en samtalsstartare — en utvecklare läser den, går bort till personen som skrev den, ställer sex frågor och fyller i resten utifrån vad hen vet om kodbasen och teamet. [3] En agent kan inte gå bort till någon. Den läser det som står på sidan, fyller varje lucka med sin bästa gissning och bygger exakt det den gissade. [3]

Och när storyn lämnar utrymme för tolkning kommer agenten att tolka — felet ligger sällan hos modellen, det ligger i kontraktet den fick. [4] Modellen är sällan variabeln du styr över. Storyn är det. [5]

Den starkaste storyn för en agent börjar inte med en att-göra- lista utan med ett tydligt uppdrag. Ange målet och några kärnkrav på en hög nivå och låt agenten fylla i detaljerna därifrån — modeller är bra på att utveckla en solid instruktion, men de behöver ett tydligt uppdrag för att inte driva iväg. [1] Ditt jobb i storyn är att förmedla visionen; agentens jobb är allt annat.

Det är därför det klassiska user story-formatet har hållit i sig: det packar tre delar av avsikt i en enda mening — "som en [typ av användare] vill jag [ett mål], så att [en anledning]". Den tredje satsen, den alla hoppar över, är det som bär visionen:

"Utan den optimerar agenten för den bokstavliga funktionsbegäran. Med den kan agenten resonera kring edge cases." [6]

Se vad som händer utan den. "Fixa inloggningsbuggen" är en fullständig instruktion för en människa som var i rummet när buggen rapporterades. För en agent är det ett förslag — den kanske levererar en 400-raders pull request som rör flödet för lösenordsåterställning, sessionsmellanprogramvaran och en feature-flagga, när den faktiska fixen var en felstavning i ett felmeddelande. [4] Visionen i den storyn — vem är utelåst, vad som borde hända istället, varför det spelar roll — är det som hade valt rätt implementation på första försöket.

En mänsklig läsare fyller luckor med omdöme, minne och ett billigt Slack-meddelande. En agent fyller dem med sina standardval — och den väljer gärna tre försök när du menade fem, eller låser konton på ett sätt som låter vem som helst låsa ute alla dina kunder. [3] Hantverket är att namnge de beslut där ett felaktigt standardval skulle kosta dig. Ett enkelt test för varje öppet beslut: "Skulle jag bli irriterad om agenten gissade?" Om ja, hör det hemma i storyn. [7]

Det som ligger utanför scope spelar lika stor roll som scope. En kort "rör inte"-lista — beteenden, filer och gränser som agenten måste lämna ifred — är ofta den enskilt mest användbara meningen i hela storyn, för utan den behandlar agenten hjälpsam städning som tillstånd. [8] Uttryckliga icke-mål hindrar den från att fixa saker ingen bad om. [9] Eller, med en utvecklares ord: "Fem rader i ticketen förhindrar två timmar i granskning." [4]

En story som bär detta väl läses som ett litet kontrakt: problemet, det förväntade resultatet, godkännandekraven, begränsningarna och vad som är off limits. Inte för att en mall är magisk — utan för att varje fält är en lucka som annars skulle fyllas av en gissning.

Den vanan som ger störst utväxling är att skriva godkännandekraven först och låta dem dra resten av storyn i fokus. [7] Godkännandekriterier är observerbart beteende — vad som måste vara sant efter ändringen — inte en omformulering av begäran. "Formuläret skickas" är en önskan; "att skicka med en utgången token visar sessionen-har-gått-ut-skärmen och rensar inte det utkastade meddelandet" är en kontroll.

De bästa kontrollerna är de agenten kan köra själv: kommandot att köra, testet som ska passera, felfallen att täcka. En gång skrivna ger de "godkännandekriterier som definierar klart för både agenten och personen" — "en enda sanningskälla agenten bygger från och granskaren kontrollerar mot". [10]

Definiera även överlämningen. Be agenten, i varje story, att "sammanfatta ändrade filer, körda kontroller, påträffade fel och eventuell kvarstående risk" i sin pull request. [9] Det kostar en rad i storyn och gör varje granskning snabbare.

Ett knep till som håller visionen ärlig: låt agenten omvandla din avsikt till ett utkast till spec och fixa sedan utkastet. Om agentens omformulering av storyn inte matchar vad du menade ligger luckan i din story — och det är mycket billigare att hitta den innan pull requesten. [1]

Agenter behöver ingen prosa som beskriver din arkitektur — de kan läsa koden. Det de inte kan härleda är vilka delar av den som storyn rör. Peka istället för att beskriva: referera filerna att röra, de befintliga mönstren att spegla, konventionerna att respektera. [7] Ett fem-raders exempel i storyn lär agenten mer än ett stycke som förklarar regeln.

Och håll arbetet dimensionerat för en story — något som kan byggas och verifieras på en enda eftermiddag — och dela upp allt större på story-nivå, före utskick, inte mitt i körningen. [7] Mindre, skarpare stories är också det som gör det hanterbart att köra flera agenter parallellt — se vår guide till parallella kodningsagenter.

Här är samma Linear-ärende, skrivet två gånger.

Den sista kontrollen är "skulle jag bli irriterad om agenten gissade?"-testet i praktiken: olöst skulle en rimlig agent lätt kunna visa låsningsmeddelandet endast för riktiga konton — och läcka vilka e-postadresser som är registrerade.

Allt i den här guiden — uppdraget, icke-målen, godkännandekraven, filerna att titta på — är det Aerunits story-skrivare utkastar åt dig. Du beskriver arbetet; Aerunit läser dina repositories och föreslår Linear-ärenden med scope, godkännandekriterier och icke-mål, pekande på koden som spelar roll. Du redigerar, godkänner, och storyn är redo för en agent.

Aerunit läser varje repository en story rör innan den skrivs, så arbete över flera repon får en sammanhängande plan: en huvudstory plus ett underärende per berört repo. Och teamets konventioner och återanvändbara instruktioner lagras en gång som delad kontext och skills, och matas sedan in i varje story och agentkörning — så du slipper upprepa "spegla det befintliga mönstret" i varje ticket, och agenter uppfinner inte dina mönster på nytt.