Čtyři typy úkolů pro agenta

"Dodělejte hlavní stránku portálu" - za takovou prosbou se může skrývat několik různých úkolů. V seznamu akcí chybí filtr. Tlačítko banneru vede jinam. Příprava dat žebříčku je napsaná dvakrát, takže každá úprava stojí dvojnásobek práce. A odkud se vlastně bere adresa akce, to si skoro nikdo nepamatuje.

Člověk, který takové zadání dostane, se nejspíš doptá. Claude Code se také může zeptat, ale často si mezery doplní sám - věrohodnou prací, kterou po něm nikdo nechtěl. Každý typ úkolu má přitom své typické rozšíření: k filtru přibude hledání, k opravě odkazu nové styly, refactoring cestou "opraví" řazení a průzkum skončí úpravami.

Co se má změnit

Typ úkolu nejlépe poznáte podle toho, co bude na konci jiné:

• přibylo chování, které dříve neexistovalo - feature, nová funkce;
• chování odpovídá očekávání - bugfix, oprava chyby. Patří sem i něco, co už je hotové, ale od začátku to fungovalo jinak, než bylo domluveno;
• navenek se nic nezměnilo, ale kód uvnitř je uspořádaný jinak - refactoring;
• dostali jste odpověď na otázku o projektu a zdrojové soubory zůstaly stejné - research, průzkum.

Typ napoví, co v zadání ohraničit a co ověřit. Kolik volnosti agentovi dát, závisí také na ceně chyby a rozsahu úkolu: úprava kódu, který používají lidé, vyžaduje větší pozornost než nová stránka ve výukovém projektu. Někdy se úkoly kombinují, třeba nejprve průzkum a pak oprava. Každá fáze má pak vlastní výsledek i hranice.

Nová funkce

V seznamu akcí má být přepínač, který zobrazí jen aktivní akce. Podmínky si stanovme hned: aktivní je akce s příznakem active: true, u akcí A a C je zapnutý, u B vypnutý. Jde o výuková data a níže uvedená zadání jsou vzory, které můžete přenést do svého projektu.

Zadání "Přidej filtr aktivních akcí" agent nejspíš splní, a ještě něco navíc. Může to vypadat takhle: přibude přepínač, vedle něj vyhledávací pole "když už filtrujeme" a také řazení podle data ukončení. Každé rozšíření dává samo o sobě smysl. Dohromady ale z jedné funkce udělají malý subsystém, který nikdo neobjednal a který bude potřeba také kontrolovat.

Další funkce navíc jsou na stránce aspoň vidět. Horší je, když se agent potichu rozhodne za vás. Andrej Karpathy psal o svém projektu MenuGen: přihlášení přes Google, platby přes Stripe a agent propojil nákup s účtem podle e-mailu. Když má člověk v obou službách jinou adresu, platba se k účtu nepřiřadí. Rozhodnutí o datech - podle čeho záznamy propojit a co udělat s těmi, které už v projektu jsou - patří vám. Nejlépe ho uveďte přímo v zadání. Náš případ je jednodušší: co s akcí, které příznak active úplně chybí?

Dalším zdrojem svévole je vzor. Agent v projektu hledá podobný kód a napodobí ho, jenže podobný může být zrovna kus, který už všichni chtějí přepsat. Pokud projekt obsahuje dobrý příklad, ukažte mu ho sami.

Pro novou funkci stačí jeden uživatelský scénář a jasný seznam toho, co do zadání nepatří:

Přidej do seznamu akcí na hlavní stránce přepínač "Jen aktivní".
Aktivní akce je záznam s active: true, záznam bez tohoto pole je neaktivní.
Kontrola se současnými daty: zapnuto - zobrazí se A a C, vypnuto - A, B a C.
Nepřidávej hledání, řazení ani jiné filtry, to jsou samostatné úkoly.
Pokud už projekt obsahuje podobný přepínač, postupuj stejně
a uveď, podle kterého ses řídil.
Nejdřív jednou větou popiš scénář, který budeš implementovat,
a počkej na mou odpověď. Zatím soubory neměň.

Poslední dva řádky nestojí skoro nic, ale pomůžou: pokud se popis scénáře liší od vašeho záměru, poznáte to ještě před úpravami. Až agent ukáže plán, položte mu krátkou otázku: není řešení zbytečně složité nebo naopak nedotažené, a proč si to myslí? Tato otázka se hodí ke každému plánu, u feature obzvlášť - právě tady se snadno skryjí zbytečné dodatky. Nakonec vyzkoušejte oba stavy přepínače a podívejte se, jestli na stránce nepřibylo ještě něco navíc.

Oprava chyby

Tlačítko banneru na hlavní stránce má otevřít stránku /campaign/ s podmínkami akce, ale vede na /old/.

Nejkratší cestou je pro agenta vepsat /campaign/ přímo do odkazu tlačítka. Pokud je adresa uložená právě v odkazu, bude to stačit. Jestli se ale načítá ze společných dat, která používají i další tlačítka, taková náhrada skryje symptom: toto tlačítko začne fungovat, ale chyba v datech zůstane. Dalším obvyklým krokem je upravit odsazení a barvu banneru, když už je soubor otevřený.

Ze samotného tlačítka nepoznáte, který případ nastal. Ukáže to až kód.

Než o něco požádáte, zkuste chybu sami zopakovat: klikněte na tlačítko a podívejte se, kam vede. Pokud se u vás chyba neprojeví, nespěchejte s uzavřením úkolu. Nejdřív upřesněte kroky a data, při kterých ji někdo zaznamenal. Jakmile se chyba dá zopakovat, je potřeba zjistit její příčinu. Nevíte, odkud tlačítko bere adresu? To je v pořádku, právě na to se můžete agenta nejdřív zeptat:

Tlačítko banneru na hlavní stránce vede na /old/, má vést na /campaign/.
Nejdřív zjisti, odkud tlačítko bere adresu, a ukaž mi toto místo.
Zatím soubory neměň.
Po mém potvrzení oprav adresu tam, kde se nastavuje.
Na vzhled banneru nesahej.

Po úpravě zopakujte původní akci: klikněte na tlačítko, zkontrolujte adresu a ověřte, že stránka zobrazuje podmínky akce. Pokud se měnila společná data s adresami, zkontrolujte i další místo, které tato data používá.

Změna vnitřního uspořádání kódu

Příprava dat žebříčku je napsaná dvakrát a téměř stejně, takže každou úpravu je třeba provést na obou místech. Cílem je ponechat jen jednu verzi a nezměnit tabulku.

To, co se má při úpravě zachovat, se nazývá invariant. Tady jde o pořadí účastníků a čísla v tabulce při stejných datech.

Chyba po refactoringu nemusí být nápadná. Posune se řazení při shodném počtu bodů, změní se zaokrouhlení, ale žádná chybová zpráva se neobjeví - tabulka jen ukáže něco jiného. Agent může po sloučení obou verzí klidně oznámit, že "chování se nezměnilo", aniž cokoli spustil. Nebo cestou "vylepší" řazení, protože mu původní připadalo zvláštní.

Vezměme data v tomto pořadí: A s 10 body, C s 20, B s 20 a D s 15.5. Tabulka teď ukazuje C: 20, B: 20, D: 15.5, A: 10. Referencí pro refactoring je právě tento výstup současného kódu, i kdybyste si přáli jiné pořadí. Data jsou zvolená záměrně. C je před B, takže pokud nová verze začne řadit shodný počet bodů podle jména, B se dostane dopředu. A desetinné číslo zase odhalí změnu zaokrouhlování.

Zadání, které ohraničí obě rizika:

Příprava dat žebříčku se opakuje na dvou místech, ponech jednu verzi.
Chování tabulky neměň, ani když ti něco připadá zvláštní,
taková místa vypiš zvlášť.
Před úpravou spusť existující kontroly a vypiš tabulku
pro data A: 10, C: 20, B: 20, D: 15.5. Ulož oba výstupy.
Po úpravě zopakuj totéž a porovnej výsledky.
V hlášení ukaž, kde se teď příprava dat nachází.

Uložené výstupy porovnejte sami, nejen podle řádku "shoduje se" v hlášení. Shoda potvrzuje, že se chování zachovalo pro tato data, nic víc. Poslední řádek zadání ověřuje samotný cíl úkolu: stejná tabulka ještě neznamená, že se duplicita opravdu odstranila.

A tady je polovičaté řešení horší než žádné. Představte si, že jedna kopie zůstane a část volání začne používat novou verzi. Tabulka je stejná, ale příprava dat má stále dvě podoby a agent může při dalším zadání klidně vycházet z té staré. Neví, kterou má považovat za správnou. Když už slučujete, dotáhněte to na jednu verzi. Pokud to nestíháte, raději se zastavte dřív a zapište si, v jakém stavu to zůstalo.

Průzkum bez oprav

Research se od ostatních typů liší nejvíc: výsledkem není změněný projekt, ale odpověď. V našem portálu se ptáme, kde se nastavuje adresa, na kterou vede tlačítko akce. Je to stejná otázka, od které začínala oprava chyby, jenže tady se žádná úprava nezadává. Tak vypadá kombinovaný úkol: nejdřív průzkum a potom samostatná fáze opravy.

Agent tu může udělat dvě typické chyby. První je začít cestou opravovat: našel problematické místo a opravit ho se zdá jednodušší než ho popisovat. Průzkum se tak změní v úpravu bez zadání a bez kontroly. Druhá chyba je nenápadnější. Agent si přečte kód a sebejistě popíše, jak stránka funguje, přestože ji nespustil. Zvenčí pak takový popis vypadá stejně jako pozorování.

Třetí chyba začíná už v zadání. Když do něj napíšete, co chcete udělat dál, agent začne odpověď přizpůsobovat tomuto cíli: místo popisu současného stavu dostanete názor na to, jak by to bylo lepší. Proto se při research ptejte na současné uspořádání a svůj záměr nechte na další fázi. V následujícím zadání není ani slovo o pozdější opravě adresy.

Zjisti, odkud tlačítko banneru na hlavní stránce bere adresu. Nic neopravuj.
V odpovědi uveď: soubory a místa v kódu, jak spolu souvisejí,
co jsi zjistil čtením a co spuštěním,
a co zatím nevíš.

Dobrá odpověď na takové zadání může vypadat třeba takhle: "V souboru pages/home.html se adresa tlačítka načítá z promo.url, hodnota /old/ je nastavená v data/promo.json. Zjistil jsem to čtením dvou souborů. Stránku jsem nespustil a neověřil, jestli adresu nemění skripty." Toto propojení lze ověřit a hranice toho, co agent ví, je poctivě pojmenovaná.

Pokud cestou narazí na podezřelé místo, ať ho v odpovědi uvede zvlášť: co je vidět a co ještě chybí k závěru. Oprava přijde až v další fázi s vlastním zadáním.

První krok a hranice

Všechno shrnuje tato tabulka.

Třetí sloupec ukazuje, co je dobré v zadání výslovně ohraničit. Ve čtvrtém je to, co máte sami ověřit nebo si nechat ukázat v odpovědi.

A platí i opačná věc: název typu sám o sobě nic nepovoluje. "Vždyť je to refactoring" není důvod přepsat polovinu modulu a "je to bugfix" nedává právo cestou změnit vzhled. Typ napoví otázku a způsob ověření, hranice ale určujete vy.

Přeformulujte šest zadání

Níže je šest zadání v podobě, v jaké se běžně píšou. U každého určete typ a přeformulujte ho tak, aby agent musel méně domýšlet: výsledek, hranice, ověření. Hned za nimi následuje rozbor, zkuste si to tedy nejdřív sami.

1. "Přidejte export žebříčku do CSV".
2. "Žebříček občas ukáže stejného účastníka dvakrát, opravte to".
3. "Rozdělte pages/home.html na části, je moc velký".
4. "Proč se hlavní stránka načítá tak pomalu?"
5. "Opravte odkaz a rovnou přepracujte vzhled".
6. "Vylepšete portál".

Jeden z možných rozborů. Vaše formulace se mohou lišit, důležité je zachovat stejné opěrné body.

1. Export žebříčku.
Feature. Chybí scénář: které sloupce budou v souboru, v jakém pořadí budou řádky a kde bude tlačítko exportu. Snadno přehlédnete i otázku týkající se dat: mají se do souboru zahrnout účastníci, kteří zatím nemají žádné body? Rozhodněte to sami, jinak rozhodne agent. A zvlášť napište, co se dělat nemá: import, výběr sloupců ani jiné formáty. Kontrola je jednoduchá: exportujte data účastníků A, B, C, D a porovnejte řádky s tabulkou na obrazovce.

2. Účastník dvakrát.
Bugfix, ale důležité slovo je "občas", ne "opravte". Dokud není jasné, kdy se duplicita objeví, agent nemá co opravit a nejspíš začne odstraňovat opakované záznamy před zobrazením tabulky. To by ale jen skrylo symptom. Nejdřív zjistěte, po jaké akci a s jakými daty se řádek zdvojí, a pak agenta požádejte, aby místo našel bez úprav. Ověřte stejný scénář, který duplicitu způsobil.

3. Rozdělit velký soubor.
Refactoring, ale invariant není uvedený a není jasné, jak ověřit, že "se nic nerozbilo". Doplňte, že stránka má vypadat a fungovat jako dosud - banner, seznam akcí i žebříček - a před úpravou zaznamenejte výsledky kontrol. Ohraničte také další pokušení: při rozdělování značek do souborů může agent snadno upravit odsazení nebo přejmenovat třídy.

4. Pomalá stránka.
Research: je to otázka, ne zadání na zrychlení. Agent ji ale snadno pochopí jako "udělej to rychlejší" a bez pokynu "nic neměň" začne naslepo optimalizovat. Požádejte ho, aby v odpovědi oddělil naměřené hodnoty od toho, co jen vyčetl: "obrázky mají několik megabajtů" je fakt, pokud to agent ověřil, zatímco "asi stránku zpomaluje skript" je odhad. Oprava přijde v další fázi, až bude známá příčina.

5. Opravit odkaz a přepracovat vzhled.
Jedno zadání obsahuje dva výsledky. Oprava odkazu je bugfix. Nový vzhled se do čtyř typů přesně nevejde: chování zůstává stejné, mění se vzhled. Nejblíž má k feature, jenže výsledek neurčuje scénář, ale vzor - návrh nebo snímek obrazovky. Nejdřív opravte odkaz podle zadání z části o bugfixu a po ověření změňte vzhled:

Teď uprav vzhled banneru podle návrhu @banner-mockup.png.
Adresu tlačítka ani texty neměň.

6. Vylepšit portál.
Typ určit nelze a není třeba hádat. Zadání se mění v otázku pro toho, kdo o úpravu požádal: co přesně mu teď vadí? Pokud jste žádali vy, zeptejte se sami sebe. Můžete to svěřit i agentovi:

Než cokoli změníš, polož mi až pět otázek,
které ti pomohou pochopit, co přesně vylepšit.
Soubory neměň.

Odpovědi obvykle samy ukážou, o jaký typ úkolu jde.