Zadanie pre agenta: ako premeniť nápad na úlohu

Dve požiadavky agentovi, jedna za druhou. Prvá: "postav stránku podľa zadania zo súboru SPEC_LANDING.md". O pár minút sa v priečinku objaví index.html a vyzerá presne tak, ako bolo zamýšľané. Druhá, v ten istý večer: "postav hru 2048". A tu agent buď položí päť otázok za sebou, alebo potichu postaví pole 5×5 s tlačidlom na vrátenie ťahu, ktoré nikto nechcel.

Rozdiel nie je v agentovi. Rozdiel je v tom, čo dostal na vstupe. V tomto článku rozoberieme, z čoho sa skladá zadanie pre malú úlohu, kde vziať obsah, ktorý doň zapíšete, čo robiť, keď poznáte iba smer, a prečo po "hotovo" kontrolujete výsledok podľa tých istých riadkov, ktoré ste napísali ešte pred začiatkom.

1. Nápad ešte nie je úloha

"Chcem 2048". "Urob peknú stránku". "Urob novú hru, nejakú zaujímavejšiu". To všetko sú nápady a majú jeden spoločný problém: v hlave máte celý obraz, no v texte dve slová. Agent vidí iba text.

Keď je v požiadavke prázdne miesto, má agent dve cesty. Prvá - opýtať sa. Druhá - doplniť ho sám: vybrať pole, vymyslieť pravidlo, pridať tlačidlo. Druhá cesta je tichšia, a preto nebezpečnejšia. nevšimnete si, že za vás niekto rozhodol, kým neuvidíte výsledok. Každé nevyplnené miesto v požiadavke je rozhodnutie, ktoré niekto prijme, a predvolene to nebudete vy.

"Každý predsa vie, ako sa hrá 2048" - to máte v hlave vy. Agent to "každý vie" neprečíta. Aké pole? Odkiaľ a kedy sa berú nové dlaždice? Ktoré sa spájajú a do čoho? Kedy je výhra, kedy koniec? Pre vás je to jedno slovo, pre neho prázdne miesto, kým sa nerozloží na pravidlá. V chate to vyzerá takto:

Vy:    postav hru 2048
Agent: Pred začiatkom si upresním:
       1. Aké pole, 4×4?
       2. Čo sa počíta ako výhra?
       3. Treba vrátenie ťahu?

To je dobrý výsledok. Na tú istú požiadavku môže prísť aj iný:

Vy:    postav hru 2048
Agent: Hotovo. Hra je v súbore index.html:
       - pole 5×5
       - tlačidlo na vrátenie posledného ťahu
       - tabuľka rekordov v localStorage

To nie je chyba agenta. To sú tri vaše prázdne miesta, ktoré sa doplnili bez vás.

Takto vyzerá cesta od nápadu k výsledku, ktorému sa dá veriť. Článok ňou prechádza zľava doprava. A posledný krok sa vracia k tretiemu: skontrolovali ste, našli dieru, dopísali riadok do zadania a znova ho dali agentovi.

2. Odkiaľ sa berie obsah

Kostru stránky alebo hry agent postaví za pár minút a naozaj to nie je najťažšia časť. Ťažké je vedieť, čo má na stránke byť a čo vlastne hráme. To v kóde nie je. Je to v hlavách ľudí, niekedy vo vašej vlastnej, a niečo vie aj agent. Získava sa to otázkami a zdroje sú tri: ľudia, vy sami, agent.

Ľudia, to je ten, kto si vec objednal, a ten, kto ju bude používať. Otázky im je lepšie klásť hromadne. Zoznam piatich-šiestich bodov naraz, nie po jednej otázke denne. Pôsobí to dotieravo, viem. V skutočnosti však všetkým ušetrí týždeň dopisovania.

Keď ste zadávateľom vy sami (vlastná hra, vlastná stránka), otázky kladiete sebe a najväčšie pokušenie je odpovedať "no to je predsa jasné". Jasné sa zapisuje rovnako ako nejasné. "Pole 4×4" sú dve sekundy, no agentovi tým odpadne celé rázcestie.

Tretí zdroj je agent a tu je pasca, o ktorej sa oplatí vedieť vopred: nemôžete sa opýtať na to, o čom neviete. Počíta sa ako ťah aj ťah, ktorý nič nepohol? Treba swipe na telefóne? Zobrazovať skóre? Tieto otázky vám nenapadnú, kým hru nemáte pred očami. Agent však videl tisíc takých hier a vie, kde sa zvyčajne zakopáva. Preto namiesto "postav" je niekedy užitočnejšie začať s "poďme to prebrať":

Chcem postaviť hru 2048 v prehliadači. Zatiaľ nič nepíš.
Polož mi otázky, bez ktorých nemôžeš začať. Všetky naraz, v zozname.
Odpoviem a potom spolu zostavíme zadanie do súboru SPEC_2048.md.

Pre taký rozhovor platia dve pravidlá, inak sa neskončí. Prvé: diskusia je hotová, keď sú vyplnené štyri piliere z nasledujúcej časti, a jej výsledkom je súbor, nie chat. Druhé: otázky agenta sú možnosti, nie požiadavky. Ochotne sa opýta "a tabuľku rekordov robíme?" a "nie" je normálna odpoveď. Aj také "nie" je riadok zadania, len v časti "nerobíme".

A v každom prípade - či ste sa pýtali vy, alebo agent - odpoveď sa zapíše do súboru so zadaním, nezostane len správou v chate. Inak sa ďalšia požiadavka začne pri tej istej diere.

Tri zdroje vľavo, jeden cieľ vpravo. Prerušovaná šípka nadol je cesta, ktorou odpovede odchádzajú najčastejšie: zostali v chate a o desať správ neskôr ich už nenájdete. Šípka na schéme je, no súbor na jej konci nie.

Od agenta môžete chcieť aj viac: nielen aby sa pýtal, ale aby sám načrtol koncept zadania podľa vašich odpovedí a doplnil to, čo ste nepovedali. Čo potom robiť s tým, čo si domyslel, je v časti 4. Najprv o tom, z čoho sa zadanie skladá.

3. Štyri piliere zadania

Pre malú úlohu má zadanie šesť až osem riadkov. Stoja na štyroch pilieroch: cieľ, čo sa má diať, čo v prvej verzii nebude, ako to skontrolujeme. Tu je celé, pre hru:

# ZADANIE: 2048

CIEĽ:      hra 2048 v prehliadači, otvára sa zo súboru, bez inštalácie.
           HTML, CSS a JavaScript, bez buildu

PRAVIDLÁ:  pole 4×4
           na začiatku a po každom ťahu sa objaví nová dlaždica: 2 alebo 4
           šípky posúvajú všetky dlaždice jedným smerom, až na doraz
           dve rovnaké dlaždice sa pri zrážke spoja do jednej so súčtom
           výhra: na poli sa objavila dlaždica 2048
           prehra: nie sú ťahy, pole je plné, nie je čo spojiť

NEROBÍME:  tabuľku rekordov, animácie, vrátenie ťahu

KONTROLA:  otvoriť index.html v prehliadači, vidieť pole a úvodné dlaždice
           urobiť tri ťahy šípkami, po každom sa objaví nová dlaždica
           spojiť dve dvojky, dostať štvorku
           dohrať do konca, vidieť obrazovku prehry

Ďalej prejdeme piliere po jednom a každý ukážeme na dvoch úlohách: hra a stránka s pozvánkou na stretnutie klubu spoločenských hier.

Cieľ

Prvý riadok. Keď ho človek prečíta, má si predstaviť výsledok, nie kód. "Hra 2048 v prehliadači, otvára sa zo súboru, bez inštalácie". "Stránka s pozvánkou na stretnutie klubu: človek pochopí, o aké stretnutie ide, a prihlási sa tlačidlom".

Kontrola cieľa: ak pri jeho čítaní vidíte kód, a nie to, čo uvidí človek, už to nie je cieľ. "Urobiť funkciu na spájanie dlaždíc" nie je cieľ, to je kus práce.

Sem patrí aj jeden riadok o tom, "z čoho staviame": HTML, CSS a JavaScript, bez buildu. Bez tohto riadku si agent vyberie sám a nie je isté, že vyberie niečo, čo viete spustiť.

A "urob to pekne" cieľom byť nemôže. Nie je jasné, pre koho pekne a kde to uvidieť.

Čo sa má diať

Najdlhší pilier a pre hru je už napísaný vyššie. Pravidlo je jedno: riadok je dobrý, ak sa naň po spustení dá pozrieť a povedať "áno" alebo "nie". "Pole 4×4" - áno, alebo nie. "Dve rovnaké dlaždice sa spoja do jednej so súčtom" - áno, alebo nie. "Zaujímavejšie" - ani áno, ani nie, a takýto riadok do zadania nepatrí.

Jedna myšlienka na riadok. "Dlaždice sa objavujú a spájajú" sú dve kontroly, teda dva riadky.

Pri stránke je to rovnaké, len namiesto pravidiel píšete, čo na nej je: "hlavička s názvom a dátumom", "tri bloky: čo bude, pre koho, kde", "tlačidlo Prihlásiť sa vedie na adresu formulára". Každý riadok sa dá otvoriť a vidieť.

Taký zoznam vedľa nápadu pôsobí nudne. Nudné je presne to dobré. nudné sa dá skontrolovať.

Čo v prvej verzii nebude

Jediný pilier, na ktorý sa zvyčajne zabúda, a preto najcennejší. Prázdne miesto agent zaplní sám a najochotnejšie tak, že niečo pridá. Tabuľka rekordov, animácia dlaždíc, tlačidlo na vrátenie ťahu, tmavá téma. Všetko užitočné a nič z toho ste nechceli.

Píše sa to menovite. Nie "nič navyše" - to je želanie, nie hranica - ale "nerobíme: tabuľku rekordov, animácie, vrátenie ťahu". Pre stránku: "nerobíme: samotný prihlasovací formulár, platby, galériu fotiek". Tri položky zvyčajne stačia, desať aj tak nikto nenapíše.

Prečo je to dôležité pre vás, a nie pre agenta. Čím menej je postavené, tým menej treba kontrolovať. A tým jasnejšie je, odkiaľ sa vzalo to, čo sa pokazilo: v šiestich riadkoch sa hľadá ľahšie než na šiestich obrazovkách. Znak, že hranica chýba: vo vašej požiadavke alebo v odpovedi agenta sa čoraz častejšie objavuje slovo "popritom".

Ako to skontrolujeme

Každý riadok z "čo sa má diať" je jedna kontrola po tom, čo agent povedal "hotovo". Otvorili ste hru - pole 4×4, áno. Stlačili ste šípku - dlaždice sa pohli, objavila sa nová, áno. Spojili ste dve dvojky - štvorka, áno. Zoznam kontrol nepíšete zvlášť, ten už je napísaný.

K tomu dva-tri riadky "kontrola" priamo v zadaní: čo presne urobiť ručne. "Otvoriť súbor v prehliadači, urobiť tri ťahy, prehrať až do konca". Tieto riadky sa píšu pred požiadavkou, nie po nej. Po výsledku ich človek nenápadne prispôsobí tomu, čo vyšlo - deje sa to samo od seba a stane sa to aj vám.

"Hotovo" od agenta je replika, nie kontrola. Kontrola je vaša, podľa vašich riadkov.

Teraz prax. Vezmite požiadavku "urob peknú stránku na stretnutie klubu spoločenských hier" a rozložte ju na štyri piliere, riadok-dva na každý. Odpoveď je hneď nižšie, porovnajte si ju:

# ZADANIE: stránka s pozvánkou

CIEĽ:        stránka s pozvánkou na stretnutie klubu spoločenských hier:
             človek pochopí, o aké stretnutie ide, kedy a kde, a prihlási sa tlačidlom.
             jeden súbor HTML, štýly vnútri

NA STRÁNKE:  hlavička s názvom klubu a dátumom stretnutia
             tri bloky: čo bude, pre koho, kde
             tlačidlo "Prihlásiť sa" vedie na adresu formulára

NEROBÍME:    samotný prihlasovací formulár, platby, galériu fotiek

KONTROLA:    otvoriť v prehliadači, vidieť hlavičku a tri bloky
             stlačiť tlačidlo, dostať sa na adresu formulára

Všimnite si, že slovo "peknú" sa do zadania vôbec nedostalo. Nedá sa skontrolovať. Ak na kráse naozaj záleží, rozkladá sa na riadky rovnako ako všetko ostatné: "jeden obrázok v hlavičke", "najviac dve farby", "všetko sa zmestí na obrazovku telefónu". To sa už dá otvoriť a pozrieť.

Názvy blokov sa v oboch príkladoch líšia: pri hre "pravidlá", pri stránke "na stránke". Na tom nezáleží, pomenujte ich, ako vám vyhovuje. Dôležité je, aby v každom boli štyri piliere:

4. Čie je to rozhodnutie

V zadaní sa objavujú rozhodnutia, ktoré nikto neodsúhlasil, a stáva sa to dvoma spôsobmi. Prvý: dovolili ste agentovi zaplniť diery "niečím rozumným", aby ste mali koncept hneď a nečakali na odpovede do utorka. Druhý: rozhodli ste sami za zadávateľa, pretože sa nemáte koho alebo kedy opýtať.

Oba prípady sú v poriadku. V poriadku nie je zabudnúť, že ide o predpoklad. O týždeň si nikto nespomenie, kto vymyslel, že tlačidlo vedie na e-mail, a nie na formulár, a hádať sa bude práve o tom.

Pri prvom prípade vyzerá požiadavka agentovi takto:

Zostav koncept zadania pre stránku s pozvánkou podľa týchto odpovedí.
Kde odpovede chýbajú, vymysli niečo rozumné a v samostatnom zozname
vypíš, čo si vymyslel sám. Zapíš to do súboru SPEC_INVITE.md.

Zoznam domyslených vecí čítate ako prvý, ešte pred samotným zadaním. Sú to rozhodnutia prijaté za vás: každé buď ide na odsúhlasenie tomu, kto sa v téme vyzná, alebo zostane v zadaní s poznámkou.

Pri druhom prípade - poznámka priamo v súbore. Riadok "predpoklad:" pred rozhodnutím alebo len otáznik na konci riadku: "tlačidlo vedie na e-mail klubu (?)". Keď príde odpoveď, hneď vidno, čo zmeniť. a netreba spomínať, odkiaľ sa to vzalo.

Poznámka funguje oboma smermi. Agent, ktorý dostane zadanie s otáznikmi, sa na ne zvyčajne opýta ako na prvé: pre neho je to rovnaký signál ako pre vás.

5. Sandbox namiesto otázok

Stáva sa, že sa štyri piliere nedajú napísať, nech nad nimi sedíte, koľko chcete. "Chcem niečo ako 2048, ale neviem, či treba skóre, či treba swipe a či je to vôbec 4×4". To nie je zadanie, ba ani nápad v bežnom zmysle. Je to orientačný bod: smer je jasný, výsledok nie. Otázky tu nepomôžu: odpovede zatiaľ nemáte vy ani zadávateľ a možnosti od agenta nemáte s čím porovnať.

V takom prípade je najlacnejšie pozrieť sa. Postaviť sandbox: najjednoduchšiu verziu, na ktorú sa dá pozrieť a vyskúšať si ju, aby ste pochopili, čo vlastne chcete. S agentom to trvá desať minút a výsledok desiatich minút nie je škoda zahodiť.

Aj pre sandbox sa píše zadanie na štyri piliere, len s iným cieľom:

# ZADANIE: sandbox 2048

CIEĽ:      pozrieť sa, ako sa hrá 2048 v prehliadači, a pochopiť, čo chcem.
           HTML, CSS a JavaScript, bez buildu

PRAVIDLÁ:  pole 4×4
           šípky posúvajú dlaždice, rovnaké sa spájajú
           po ťahu sa objaví nová dlaždica

NEROBÍME:  všetko ostatné: výhru, prehru, skóre, swipe, dizajn

KONTROLA:  hrať päť minút a zapísať, čo chýba a čo je navyše

Pozrite sa, čo sa zmenilo. Cieľom nie je hra, ale pochopenie. "Nerobíme" je najdlhší riadok, je v ňom všetko, čím si nie ste istí. A kontrola nie je "funguje to?", ale "čo teraz viem". Päť minút hry - a otázky, ktoré sa na začiatku nedali položiť, sa objavia samy: swipe netreba, pri počítači sa hrá šípkami; skóre treba, bez neho je to nuda; 4×4 je málo, chce to skúsiť 5×5; prehru treba ukázať, inak nie je jasné, že hra skončila.

Presne to je výsledok sandboxu. Nie kód, ale odpovede. Z nich sa napíše skutočné zadanie a stavia sa od nuly, v čistom priečinku, jednou vetou: "postav hru podľa zadania zo súboru". Sandbox svoje odviedol.

Je to ten istý reťazec z prvej časti, len krok "Otázky" tu nahradila slučka: keď sa nie je na čo pýtať, najprv sa pozeráme, potom zapisujeme. Nadol, do zadania, ide jediná vec - odpovede. Zo sandboxu nevedie šípka k agentovi a nie je to zábudlivosť: skutočnú verziu agent stavia v čistom priečinku, od nuly. ďalej už všetko ide podľa reťazca.

6. Zadanie žije v súbore

Prečo súbor, a nie konverzácia. Konverzácia sa stráca: o desať správ neskôr už pravidlo o spájaní dlaždíc nenájdete. Súbor leží v priečinku projektu vedľa kódu, agent si ho prečíta sám, keď naň ukážete, a keď ho upravíte, odovzdáte ho znova tou istou vetou. Názov môže byť akýkoľvek: SPEC_2048.md, SPEC_LANDING.md, hoci aj zadanie.txt. Je to obyčajný textový súbor, žiadny špeciálny formát nemá.

Odovzdáva sa jednou vetou. Porovnajte:

Predtým: "postav hru 2048, veď vieš akú, nejakú zaujímavejšiu".

Potom: "postav hru podľa zadania zo súboru SPEC_2048.md".

Druhá požiadavka je kratšia než prvá, no informácií je v nej desaťkrát viac - sú v súbore. Kopírovať text zadania do chatu netreba, agent si súbor otvorí sám.

Čo meniť v súbore a čo povedať slovami. Platí zhruba toto: zmenilo sa pravidlo alebo hranica - upravíme súbor a dáme ho znova ("výhra pri 2048, nie pri 1024" patrí do súboru). Zmenila sa drobnosť vo vzhľade, ktorá pravidlá neovplyvní - dá sa to povedať slovami ("urob tlačidlo modré"). Ak váhate, do súboru: riadok navyše je lacnejší než zabudnuté pravidlo.

K veľkosti. Pre malú úlohu je to šesť až osem riadkov, ako blok pre 2048 vyššie. Ak sa zadanie na hru na jeden večer natiahlo na dve strany, pravdepodobne sa doň dostalo to, čo malo skončiť v "nerobíme".

A posledná vec, skôr než súbor dáte agentovi: prečítajte si ho raz, akoby bol cudzí. Riadok, ktorý sa nedá skontrolovať, sa nájde takmer vždy. u mňa sa nájde.

7. Čo agent robí so zadaním a čo zostáva na vás

Zhrňme si všetko dohromady: čo v tejto schéme robí Claude Code a čo zostáva na vašej strane. Po dvojiciach.

Zmysel zadania nie je v tom, aby agent pochopil. Aj z dvoch slov niečo postaví. Zmysel je v tom, aby ste vy sami vedeli, čo ste si objednali, a mohli to skontrolovať.