Štyri typy úloh pre agenta

"Dokončite hlavnú stránku portálu" - pod takouto požiadavkou sa skrýva niekoľko rôznych úloh. V zozname akcií chýba filter. Tlačidlo bannera vedie inam, než má. Príprava údajov rebríčka je napísaná dvakrát, takže každá úprava v nej stojí dvakrát toľko. A odkiaľ sa vlastne berie adresa akcie, to si už poriadne nikto nepamätá.

Človek by sa pri takej požiadavke zrejme opýtal na podrobnosti. Claude Code sa tiež môže opýtať, no často si medzery doplní sám - uveriteľnou prácou, ktorú si nikto neobjednal. Pri každom type úlohy vyzerá táto práca inak: k filtru pribudne vyhľadávanie, k oprave odkazu nový vzhľad, refactoring popritom "opraví" radenie a prieskum sa skončí úpravami.

Čo sa má zmeniť

Typy najľahšie rozlíšite podľa toho, čo bude po dokončení práce iné:

• pribudlo správanie, ktoré predtým neexistovalo - feature, nová funkcia;
• správanie zodpovedá očakávaniu - bugfix, oprava chyby. Patrí sem aj niečo, čo už bolo implementované, no od začiatku nefungovalo podľa dohody;
• navonok zostalo všetko po starom, ale vnútorné usporiadanie kódu sa zmenilo - refactoring;
• dostali ste odpoveď na otázku o projekte a zdrojové súbory zostali nezmenené - research, prieskum.

Typ napovie, čo v zadaní spresniť a čo skontrolovať. Koľko voľnosti agentovi ponechať, závisí aj od ceny chyby a rozsahu úlohy: zmena v kóde, ktorý používajú ľudia, si vyžaduje viac pozornosti než nová stránka v cvičnom projekte. Úlohy môžu byť aj zmiešané, napríklad prieskum a po ňom úprava. Vtedy má každá etapa vlastný výsledok a hranice.

Nová funkcia

V zozname akcií potrebujeme prepínač, ktorý ponechá iba aktívne. Podmienky určíme hneď: aktívna je akcia s príznakom active: true, pri akciách A a C je zapnutý a pri B vypnutý. Údaje sú tu cvičné a zadania nižšie sú vzory, ktoré môžete preniesť do svojho projektu.

Agent pravdepodobne splní zadanie "Pridaj filter aktívnych akcií" a ešte niečo navyše. Môže to vyzerať takto: pribudne prepínač, vedľa neho vyhľadávacie pole "keď už filtrujeme" a k tomu radenie podľa dátumu ukončenia. Každé doplnenie dáva samostatne zmysel. Spolu však z jednej funkcie spravia malý podsystém, ktorý si nikto neobjednal a teraz ho bude treba aj kontrolovať.

Nadbytočné doplnky si aspoň všimnete na stránke. Horšie je, keď agent potichu rozhodne za vás. Andrej Karpathy rozprával o svojom projekte MenuGen: prihlasovanie tam funguje cez Google, platby cez Stripe a agent prepojil nákup s účtom podľa e-mailu. Ak má niekto v týchto službách odlišné adresy, platba sa k účtu nepriradí. O údajoch rozhodujete vy - podľa čoho prepojiť záznamy a čo urobiť s tými, ktoré už v projekte sú. Najlepšie priamo v zadaní. U nás je otázka jednoduchšia: čo urobiť s akciou, ktorá vôbec nemá príznak active?

Ďalším zdrojom svojvoľných úprav je vzorový kód. Agent si v projekte nájde podobný kód a zopakuje ho, no podobné môže byť práve to miesto, ktoré už všetci dávno chcú prepísať. Ak máte v projekte dobrý príklad, ukážte mu ho.

Nová funkcia potrebuje jeden používateľský scenár a jasný zoznam toho, čo do úlohy nepatrí:

Pridaj do zoznamu akcií na hlavnej stránke prepínač "Iba aktívne".
Aktívna akcia je záznam s active: true; záznam bez tohto poľa je neaktívny.
Kontrola na aktuálnych údajoch: zapnuté - zobrazia sa A a C, vypnuté - A, B a C.
Nepridávaj vyhľadávanie, radenie ani iné filtre, sú to samostatné úlohy.
Ak už projekt má podobný prepínač, postupuj rovnako
a povedz mi, podľa ktorého si sa riadil.
Najprv jednou vetou opíš scenár, ktorý budeš implementovať,
a počkaj na moju odpoveď. Súbory zatiaľ nemeň.

Posledné dva riadky stoja málo, ale pomáhajú: ak sa zhrnutie scenára nezhoduje s vaším zámerom, zistíte to ešte pred úpravami. Keď agent ukáže plán, položte mu krátku otázku: nie je riešenie zbytočne zložité, niečo mu nechýba a prečo si to myslí? Táto otázka sa hodí pri každom pláne, no pri feature obzvlášť, pretože práve tu sa skrývajú nadbytočné doplnky. Na hotovom výsledku skontrolujte oba stavy prepínača a pozrite sa, či na stránke nepribudlo niečo navyše.

Oprava chyby

Tlačidlo bannera na hlavnej stránke má otvoriť stránku /campaign/ s podmienkami akcie, no vedie na /old/.

Najkratšia cesta pre agenta je zapísať /campaign/ priamo do odkazu tlačidla. Ak bola adresa naozaj uvedená v odkaze, stačí to. Ak však pochádza zo spoločných údajov, ktoré používajú aj iné tlačidlá, takáto náhrada zakryje príznak problému: toto tlačidlo bude fungovať, ale chyba v údajoch zostane. Druhý typický krok je upraviť medzery a farbu bannera, keď už je súbor otvorený.

Zo samotného tlačidla nezistíte, ktorý prípad nastal. Ukáže to až kód.

Skôr než o čokoľvek požiadate, zopakujte chybu sami: kliknite na tlačidlo a pozrite sa, kam vedie. Ak sa chyba u vás nedá zopakovať, neponáhľajte sa s uzavretím úlohy. Najprv si ujasnite kroky a údaje, pri ktorých sa objavila. Keď chybu reprodukujete, treba nájsť príčinu. Neviete, odkiaľ tlačidlo berie adresu? Nevadí, práve to je prvá otázka pre agenta:

Tlačidlo bannera na hlavnej stránke vedie na /old/, má viesť na /campaign/.
Najprv zisti, odkiaľ tlačidlo berie adresu, a ukáž mi toto miesto.
Súbory zatiaľ nemeň.
Po mojom potvrdení oprav adresu tam, kde sa nastavuje.
Vzhľad bannera nemeň.

Po úprave zopakujte pôvodnú akciu: kliknite na tlačidlo, skontrolujte adresu a overte, že stránka zobrazuje podmienky akcie. Ak sa zmenili spoločné údaje s adresami, skontrolujte ešte jedno ďalšie miesto, ktoré ich používa.

Zmena usporiadania kódu

Príprava údajov rebríčka je napísaná dvakrát, takmer rovnako, a každú úpravu treba urobiť na oboch miestach. Cieľom je ponechať jednu verziu a nezmeniť tabuľku.

To, čo sa má pri úprave zachovať, sa nazýva invariant. Tu ide o poradie účastníkov a čísla v tabuľke pri rovnakých údajoch.

Pokazený refactoring nerobí hluk. Pri rovnakom počte bodov sa zmení radenie, zaokrúhľovanie dopadne inak, no žiadne chybové hlásenie sa neobjaví - tabuľka jednoducho ukazuje nesprávne údaje. Agent po zlúčení dvoch verzií môže pokojne oznámiť, že "správanie sa nezmenilo", hoci nič nespustil. Alebo popritom "vylepší" radenie, pretože sa mu pôvodné zdalo zvláštne.

Vezmime údaje v tomto poradí: A s 10 bodmi, C s 20, B s 20, D s 15.5. Tabuľka dnes zobrazuje C: 20, B: 20, D: 15.5, A: 10. Referenciou pre refactoring je presne tento výstup aktuálneho kódu, aj keby ste ho radšej videli inak. Zostavu sme pripravili zámerne. C je pred B, takže ak nová verzia začne zoraďovať rovnaký počet bodov podľa mena, B sa posunie dopredu. Desatinná hodnota zas ukáže prípadnú zmenu zaokrúhľovania.

Zadanie, ktoré pokrýva oba typické problémy:

Príprava údajov rebríčka sa opakuje na dvoch miestach, ponechaj jednu verziu.
Nemeň správanie tabuľky, aj keby sa ti niečo zdalo zvláštne,
také miesta vypíš osobitne.
Pred úpravou spusti existujúce kontroly a zobraz tabuľku
pre údaje A: 10, C: 20, B: 20, D: 15.5. Ulož oba výstupy.
Po úprave zopakuj to isté a porovnaj výsledky.
V správe ukáž, kde sa teraz nachádza príprava údajov.

Uložené výstupy porovnajte sami, nielen podľa riadka "zhoduje sa" v správe. Zhoda hovorí iba to, že sa správanie zachovalo pri týchto údajoch. Posledný riadok zadania kontroluje samotnú úlohu: rovnaká tabuľka ešte neznamená, že sa duplicita naozaj odstránila.

A tu je polovičaté riešenie horšie než žiadne. Predstavme si, že jedna kópia zostala a časť volaní už používa novú verziu. Tabuľka je rovnaká, ale teraz existujú dva spôsoby prípravy údajov a agent môže ďalšiu požiadavku postaviť na starom: nevie, ktorý spôsob je správny. Ak ste začali zlučovať, dotiahnite to až do jednej verzie. Ak nestíhate, zastavte sa skôr a zapíšte, v akom stave to zostalo.

Prieskum bez opráv

Research sa od ostatných typov líši najviac: výsledkom nie je upravený projekt, ale odpoveď. Otázka z nášho portálu znie, kde sa vyberá adresa, na ktorú vedie tlačidlo akcie. Je to tá istá otázka, ktorou sa začínala oprava chyby, lenže tu sa žiadna úprava vôbec neobjednáva. Tak vyzerá zmiešaná úloha: najprv prieskum a potom, ako samostatná etapa, oprava.

Agent tu môže zlyhať dvoma typickými spôsobmi. Prvý je začať cestou opravovať: nájde nepekný kus kódu a opraviť ho sa zdá jednoduchšie než ho opísať. Prieskum sa tak zmení na úpravu bez zadania a kontroly. Druhý prípad je nenápadnejší. Agent si prečíta kód a sebavedomo opíše, ako stránka funguje, hoci ju nespustil. Zvonka vyzerá zhrnutie prečítaného rovnako ako pozorovanie.

Tretí problém sa začína už zadaním. Ak v ňom napíšete, čo chcete urobiť neskôr, agent prispôsobí odpoveď tomuto cieľu: namiesto opisu súčasného stavu dostanete názor na to, ako by to bolo lepšie. Pri research sa preto pýtajte na aktuálne usporiadanie a svoj zámer si nechajte na ďalšiu etapu. V zadaní nižšie nie je ani slovo o tom, že adresu neskôr opravíme.

Zisti, odkiaľ tlačidlo bannera na hlavnej stránke berie adresu. Nič neopravuj.
V odpovedi uveď: súbory a miesta v kóde, ako spolu súvisia,
čo si zistil čítaním a čo spustením,
a čo zatiaľ nevieš.

Dobrá odpoveď na také zadanie môže vyzerať napríklad takto: "V pages/home.html pochádza adresa tlačidla z promo.url, hodnota /old/ je nastavená v data/promo.json. Zistil som to čítaním dvoch súborov. Stránku som nespustil a neoveril, či adresu nemenia skripty." Súvislosť sa dá skontrolovať a hranica toho, čo vieme, je pomenovaná poctivo.

Ak sa cestou objaví podozrivé miesto, nech sa v odpovedi uvedie samostatne: čo vidíme a čo ešte chýba na záver. Oprava patrí až do ďalšej etapy s vlastným zadaním.

Prvý krok a hranice

Všetko pokope v jednej tabuľke.

Tretí stĺpec ukazuje, čo sa oplatí v zadaní výslovne ohraničiť. Štvrtý hovorí, čo si máte skontrolovať sami alebo si to vyžiadať v odpovedi.

A platí aj opačná strana: samotný názov typu nič nepovoľuje. "Veď je to refactoring" nie je dôvod prepísať polovicu modulu a "je to bugfix" nedáva právo popritom zmeniť vzhľad. Typ napovie otázku a kontrolu, hranice však určujete vy.

Prepíšte šesť zadaní

Nižšie je šesť zadaní v podobe, v akej sa zvyknú písať. Pri každom určte typ a prepíšte ho tak, aby agent musel menej domýšľať: výsledok, hranice, kontrolu. Rozbor nasleduje hneď, skúste si to teda najprv sami.

1. "Pridajte export rebríčka do CSV".
2. "Rebríček niekedy zobrazuje toho istého účastníka dvakrát, opravte to".
3. "Rozdeľte pages/home.html na časti, je obrovský".
4. "Prečo sa hlavná stránka načítava tak pomaly?"
5. "Opravte odkaz a popritom prerobte vzhľad".
6. "Vylepšite portál".

Jeden z možných rozborov.Vaše formulácie sa môžu líšiť, dôležité je zachovať rovnaké oporné body.

1. Export rebríčka.
Feature. Chýba scenár: ktoré stĺpce budú v súbore, v akom poradí budú riadky a kde bude tlačidlo exportu. Je tu aj otázka o údajoch, ktorú ľahko prehliadnete: dostanú sa do súboru aj účastníci, ktorí zatiaľ nemajú body? Rozhodnite o tom vy, inak to urobí agent. Samostatne uveďte, čo sa robiť nemá: import, výber stĺpcov, iné formáty. Kontrola je jednoduchá: exportujte súbor s údajmi A, B, C, D a porovnajte riadky s tabuľkou na obrazovke.

2. Účastník dvakrát.
Bugfix, ale kľúčové slovo je tu "niekedy", nie "opravte to". Kým neviete, kedy sa duplicita objaví, agent nemá čo opravovať. Najpravdepodobnejšie odstráni opakované riadky pred zobrazením tabuľky. A to je práve skrytý príznak problému. Najprv zistite, po akej akcii a pri akých údajoch sa riadok zdvojí. Potom požiadajte agenta, aby bez úprav našiel miesto, kde sa to deje. Kontrolou je ten istý scenár, pri ktorom vznikla duplicita.

3. Rozdelenie veľkého súboru.
Refactoring, no invariant nie je pomenovaný a nie je podľa čoho overiť, že "sa nič nepokazilo". Doplňte, že stránka má vyzerať a fungovať ako predtým - banner, zoznam akcií, rebríček - a pred úpravou zaznamenajte výsledky kontrol. Zamedzte aj pokušeniu: pri rozdeľovaní značiek do súborov môže agent popritom upraviť medzery alebo premenovať triedy.

4. Pomalá stránka.
Research: je to otázka, nie požiadavka na zrýchlenie. Agent si ju však môže ľahko vysvetliť ako "zrýchli to". Bez pokynu "nič nemeň" odpovie optimalizáciou naslepo. Požiadajte ho, aby v odpovedi oddelil namerané údaje od toho, čo iba vyčítal z kódu: "obrázky majú niekoľko megabajtov" je fakt, ak to agent overil, kým "asi to spomaľuje skript" je odhad. Oprava príde v ďalšej etape, keď bude známa príčina.

5. Opraviť odkaz a prerobiť vzhľad.
Jedno zadanie, dva výsledky. Oprava odkazu je bugfix. Nový vzhľad sa úprimne nedá zaradiť do žiadneho zo štyroch typov: správanie sa nemení, mení sa vzhľad. Najbližšie je to k feature, len výsledok určuje vzor - návrh alebo snímka obrazovky, nie scenár. Najprv príde oprava podľa zadania z časti o bugfixe; po jej kontrole nasleduje vzhľad:

Teraz uprav vzhľad bannera podľa návrhu @banner-mockup.png.
Adresu tlačidla ani texty nemeň.

6. Vylepšiť portál.
Typ sa nedá určiť a netreba hádať. Zo zadania sa stane otázka pre toho, kto ho zadal: čo presne mu teraz prekáža? Ak ste si ho zadali sami, opýtajte sa seba. Môžete tým poveriť aj agenta:

Skôr než niečo zmeníš, polož mi najviac päť otázok,
ktoré potrebuješ na zistenie, čo presne treba vylepšiť.
Nemeň žiadne súbory.

Z odpovedí sa typ zvyčajne vyjasní sám.