Specificația pentru agent: cum transformați o idee într-o sarcină

Două cereri către agent, una după alta. Prima: "construiește pagina după specificația din fișierul SPEC_LANDING.md". După câteva minute, în folder apare index.html și arată exact cum trebuia. A doua, în aceeași seară: "construiește jocul 2048". Și de data asta agentul fie pune cinci întrebări la rând, fie construiește în tăcere o tablă de 5×5 cu un buton de anulare a mutării pe care nu l-a cerut nimeni.

Diferența nu ține de agent. Ține de ce a primit la intrare. În acest articol vedem din ce e făcută o specificație pentru o sarcină mică, de unde luați conținutul pe care îl scrieți în ea, ce faceți când știți doar direcția și de ce, după "gata", verificați rezultatul după aceleași rânduri pe care le-ați scris înainte de început.

1. O idee nu e încă o sarcină

"Vreau 2048". "Fă o pagină frumoasă". "Fă un joc nou, ceva mai interesant". Toate acestea sunt idei și au aceeași problemă: în cap aveți o imagine întreagă, iar în text sunt două cuvinte. Agentul vede doar textul.

Când într-o cerere e un gol, agentul are două variante. Prima - să întrebe. A doua - să-l umple singur: alege dimensiunea tablei, inventează o regulă, adaugă un buton. A doua variantă e mai silențioasă și tocmai de aceea mai periculoasă. nu veți observa că s-a decis în locul dumneavoastră până nu vedeți rezultatul. Fiecare loc gol din cerere e o decizie pe care o va lua cineva, iar implicit acel cineva nu veți fi dumneavoastră.

"Toată lumea știe cum se joacă 2048" - asta e în capul dumneavoastră. Agentul nu citește acel "toată lumea știe". Ce tablă? De unde apar plăcile noi și când? Care se unesc și în ce? Când e victorie, când se termină jocul? Pentru dumneavoastră e un singur cuvânt, pentru el e un gol, până nu e descompus în reguli. În chat arată așa:

Dvs.:   construiește jocul 2048
Agent:  Înainte să încep, câteva clarificări:
        1. Ce tablă, 4×4?
        2. Ce se consideră victorie?
        3. E nevoie de anularea mutării?

Acesta e scenariul bun. Există și altul, la aceeași cerere:

Dvs.:   construiește jocul 2048
Agent:  Gata. Jocul e în fișierul index.html:
        - tablă 5×5
        - buton de anulare a ultimei mutări
        - tabel de recorduri în localStorage

Nu e o greșeală a agentului. Sunt trei goluri ale dumneavoastră, umplute fără dumneavoastră.

Așa arată drumul de la idee la un rezultat în care puteți avea încredere. Articolul îl parcurge de la stânga la dreapta. Iar ultimul pas vă întoarce la al treilea: ați verificat, ați găsit o gaură, ați adăugat un rând în specificație și i-ați dat-o din nou agentului.

2. De unde vine conținutul

Scheletul unei pagini sau al unui joc agentul îl face în câteva minute și, sincer, nu asta e partea grea. Greu e să știți ce trebuie să fie pe pagină și ce joc, de fapt, construim. Asta nu se află în cod. Se află în capul oamenilor, uneori chiar în al dumneavoastră, iar câte ceva știe și agentul. Se scoate la iveală prin întrebări, iar sursele sunt trei: oamenii, dumneavoastră înșivă, agentul.

Oamenii înseamnă cel care a comandat lucrarea și cel care o va folosi. Întrebările e mai bine să le trimiteți grupat. O listă de cinci-șase puncte deodată, nu câte o întrebare pe zi. Un pachet de întrebări pare insistent, știu. În practică, le economisește tuturor o săptămână de mesaje trimise încoace și încolo.

Când clientul sunteți chiar dumneavoastră (jocul dumneavoastră, pagina dumneavoastră), întrebările vi le puneți singur, iar aici tentația principală e să răspundeți "păi e evident". Evidentul se scrie la fel ca neevidentul. "Tablă 4×4" înseamnă două secunde, iar agentului îi închid o bifurcație întreagă.

A treia sursă e agentul, și aici e o capcană pe care e bine s-o cunoașteți dinainte: nu puteți întreba despre ceea ce nu știți. O mutare care n-a mișcat nimic se consideră mutare? E nevoie de swipe pe telefon? Se afișează scorul? Întrebările astea nu vă vin în minte până când jocul nu e în fața ochilor. Agentul, în schimb, a văzut o mie de jocuri de felul ăsta și știe unde se împiedică de obicei lumea. De aceea, în loc de "construiește", uneori e mai util să începeți cu "hai să discutăm":

Vreau să fac jocul 2048 în browser. Deocamdată nu scrie nimic.
Pune-mi întrebările fără de care nu poți începe. Toate deodată, într-o listă.
Eu răspund, iar apoi scriem specificația în fișierul SPEC_2048.md.

Două reguli pentru o astfel de discuție, altfel nu se mai termină. Prima: discuția s-a încheiat când sunt completați cei patru piloni din secțiunea următoare, iar rezultatul ei e un fișier, nu un chat. A doua: întrebările agentului sunt variante, nu cerințe. Vă va întreba bucuros "facem și un tabel de recorduri?", iar "nu" e un răspuns perfect normal. Un astfel de "nu" e tot un rând din specificație, doar că la "nu facem".

Și în orice caz - fie că ați întrebat dumneavoastră, fie agentul - răspunsul se scrie în fișierul cu specificația, nu rămâne o replică în chat. Altfel cererea următoare va porni de la aceeași gaură.

Trei surse în stânga, o singură destinație în dreapta. Săgeata punctată în jos e drumul pe care îl iau cel mai des răspunsurile: au rămas în chat și după zece mesaje nu le mai găsiți. Săgeata există în schemă, dar fișierul de la capătul ei nu există.

Agentului îi puteți cere și mai mult: nu doar să întrebe, ci și să schițeze singur o specificație pe baza răspunsurilor dumneavoastră, completând ce nu ați spus. Ce faceți apoi cu ce a adăugat de la el - în secțiunea 4. Mai întâi, din ce e făcută o specificație.

3. Cei patru piloni ai specificației

Pentru o sarcină mică, specificația are șase-opt rânduri. Ele se sprijină pe patru piloni: scopul, ce trebuie să se întâmple, ce nu va avea prima versiune, cum verificăm. Iată una întreagă, pentru joc:

# Specificație: 2048

SCOP:       joc 2048 în browser, se deschide dintr-un fișier, fără instalare.
            HTML, CSS și JavaScript, fără build

REGULI:     tablă 4×4
            la pornire și după fiecare mutare apare o placă nouă: 2 sau 4
            săgețile mută toate plăcile într-o direcție, până la capăt
            două plăci egale care se ciocnesc se unesc într-una cu suma lor
            victorie: pe tablă a apărut placa 2048
            înfrângere: nu mai sunt mutări, tabla e plină, nimic de unit

NU FACEM:   tabel de recorduri, animații, anularea mutării

VERIFICARE: deschid index.html în browser, văd tabla și plăcile de start
            fac trei mutări cu săgețile, după fiecare apare o placă nouă
            unesc doi de 2, obțin un 4
            joc până la capăt, văd ecranul de înfrângere

Mai departe, câte un pilon pe rând, fiecare ilustrat pe două sarcini: jocul și o pagină-invitație la întâlnirea unui club de jocuri de societate.

Scopul

Primul rând. După ce îl citește, omul trebuie să-și imagineze rezultatul, nu codul. "Joc 2048 în browser, se deschide dintr-un fișier, fără instalare". "Pagină-invitație la întâlnirea clubului: omul înțelege ce fel de întâlnire e și se înscrie printr-un buton".

Testul scopului: dacă, citindu-l, vedeți cod, nu ceea ce va vedea omul, atunci nu mai e un scop. "Scrie funcția de unire a plăcilor" nu e un scop, e o bucată de lucru.

Tot aici, într-un rând, "cu ce construim": HTML, CSS și JavaScript, fără build. Fără acest rând agentul alege singur și nu e sigur că va alege ceva ce știți să rulați.

Iar "fă-o frumos" nu poate fi un scop. Nu e clar frumos pentru cine și unde se vede asta.

Ce trebuie să se întâmple

Cel mai lung pilon, iar pentru joc e deja scris mai sus. Regula e una singură: un rând e bun dacă, după pornire, vă puteți uita la el și spune "da" sau "nu". "Tablă 4×4" - da sau nu. "Două plăci egale se unesc într-una cu suma lor" - da sau nu. "Ceva mai interesant" - nici da, nici nu, iar un astfel de rând n-are ce căuta în specificație.

O idee pe rând. "Plăcile apar și se unesc" înseamnă două verificări, deci două rânduri.

Pentru pagină e la fel, doar că în loc de reguli scrieți ce e pe ea: "antet cu numele și data", "trei blocuri: ce va fi, pentru cine, unde", "butonul Înscrie-te duce la adresa formularului". Fiecare rând se poate deschide și vedea.

O astfel de listă pare plictisitoare lângă idee. Plictisitor înseamnă bine. ce e plictisitor se poate verifica.

Ce nu va avea prima versiune

Singurul pilon pe care îl uită de obicei toată lumea și, tocmai de aceea, cel mai valoros. Un gol agentul îl umple singur și cel mai bucuros o face adăugând ceva. Tabel de recorduri, animația plăcilor, buton de anulare a mutării, temă întunecată. Toate sunt utile și pe niciuna n-ați cerut-o.

Se scrie cu nume concrete. Nu "nimic în plus" (asta nu e o limită, ci o dorință), ci "nu facem: tabel de recorduri, animații, anularea mutării". Pentru pagină: "nu facem: formularul de înscriere propriu-zis, plata, galeria de fotografii". Trei nume ajung de obicei, zece oricum nu scrie nimeni.

De ce vă ajută pe dumneavoastră, nu pe agent. Cu cât se construiește mai puțin, cu atât aveți mai puțin de verificat. Și cu atât e mai clar de unde vine ce s-a stricat: în șase rânduri căutați mai ușor decât în șase ecrane. Semnul că limita lipsește: în cererea dumneavoastră sau în răspunsul agentului apare tot mai des expresia "și, pe lângă asta".

Cum verificăm

Fiecare rând din "ce trebuie să se întâmple" e o verificare după ce agentul a spus "gata". Ați deschis jocul - tablă 4×4, da. Ați apăsat o săgeată - plăcile s-au mișcat, a apărut una nouă, da. Ați unit doi de 2 - un 4, da. Lista de verificări nu o scrieți separat, e deja scrisă.

Plus două-trei rânduri de "verificare" chiar în specificație: ce anume faceți de mână. "Deschid fișierul în browser, fac trei mutări, joc până pierd". Rândurile astea se scriu înainte de cerere, nu după. După rezultat, sunt ajustate pe nesimțite la ce a ieșit - se întâmplă de la sine și vi se va întâmpla și dumneavoastră.

"Gata" de la agent e o replică, nu o verificare. Verificarea e a dumneavoastră, după rândurile dumneavoastră.

Acum, practică. Luați cererea "fă o pagină frumoasă pentru întâlnirea clubului de jocuri de societate" și descompuneți-o în cei patru piloni, câte un rând-două pe fiecare. Răspunsul e imediat mai jos, comparați:

# Specificație: pagină-invitație

SCOP:         pagină-invitație la întâlnirea clubului de jocuri de societate:
              omul înțelege ce fel de întâlnire e, când și unde, și se înscrie printr-un buton.
              un singur fișier HTML, stilurile în interior

PE PAGINĂ:    antet cu numele clubului și data întâlnirii
              trei blocuri: ce va fi, pentru cine, unde
              butonul "Înscrie-te" duce la adresa formularului

NU FACEM:     formularul de înscriere propriu-zis, plata, galeria de fotografii

VERIFICARE:   deschid în browser, văd antetul și cele trei blocuri
              apăs butonul, ajung la adresa formularului

Observați că cuvântul "frumoasă" n-a ajuns deloc în specificație. Nu se poate verifica. Dacă frumusețea chiar contează, ea se descompune în rânduri la fel ca tot restul: "o singură imagine în antet", "cel mult două culori", "totul încape pe ecranul telefonului". Asta deja se poate deschide și vedea.

Numele blocurilor diferă în cele două exemple: la joc "reguli", la pagină "pe pagină". Nu contează, numiți-le cum vă e comod. Contează ca în fiecare să existe cei patru piloni:

4. A cui e decizia

În specificație apar decizii pe care nu le-a aprobat nimeni, iar asta se întâmplă în două feluri. Primul: i-ați permis agentului să astupe găurile cu "ceva rezonabil", ca să aveți o ciornă acum, nu să așteptați răspunsuri până marți. Al doilea: ați decis chiar dumneavoastră în locul clientului, pentru că n-aveți pe cine sau când să întrebați.

Ambele cazuri sunt normale. Nu e normal să uitați că e o presupunere. Peste o săptămână nimeni nu-și va aminti cine a hotărât că butonul duce la e-mail, nu la formular, iar disputa va fi exact despre asta.

Pentru primul caz, cererea către agent arată așa:

Scrie o ciornă de specificație pentru pagina-invitație pe baza acestor răspunsuri.
Unde nu există răspunsuri, alege ceva rezonabil și enumeră separat,
într-o listă, ce ai decis de la tine. Scrie totul în fișierul SPEC_INVITE.md.

Lista cu ce a adăugat agentul o citiți prima, înaintea specificației propriu-zise. Sunt decizii luate în locul dumneavoastră: fiecare fie merge la aprobare la cineva care cunoaște subiectul, fie rămâne în specificație cu un marcaj.

Pentru al doilea caz - marcajul direct în fișier. Cuvântul "presupunere:" înaintea deciziei sau pur și simplu un semn de întrebare la finalul rândului: "butonul duce la e-mailul clubului (?)". Când vine răspunsul, vedeți imediat ce trebuie schimbat. și nu mai trebuie să vă amintiți de unde a apărut.

Marcajul funcționează în ambele sensuri. Un agent care primește o specificație cu semne de întrebare de obicei întreabă de ele înainte de orice: pentru el e același semnal ca pentru dumneavoastră.

5. Un sandbox în loc de întrebări

Se întâmplă ca cei patru piloni să nu iasă, oricât v-ați strădui. "Vreau ceva de genul 2048, dar nu știu dacă e nevoie de scor, de swipe și dacă e măcar 4×4". Asta nu e o specificație și nici măcar o idee în sensul obișnuit. E un reper: direcția e clară, rezultatul - nu. Întrebările nu ajută aici: răspunsuri încă nu au nici dumneavoastră, nici clientul, iar variantele agentului nu aveți cu ce să le comparați.

Într-un astfel de caz, cel mai ieftin e să vă uitați. Să construiți un sandbox: cea mai simplă versiune, pe care o puteți vedea, încerca și din care înțelegeți ce vreți de fapt. Cu agentul asta costă zece minute, iar pentru zece minute nu e păcat să aruncați rezultatul.

Sandboxul e tot o specificație pe patru piloni, doar că are alt scop:

# Specificație: sandbox 2048

SCOP:       să văd cum se joacă 2048 în browser și să înțeleg ce vreau.
            HTML, CSS și JavaScript, fără build

REGULI:     tablă 4×4
            săgețile mută plăcile, cele egale se unesc
            după fiecare mutare apare o placă nouă

NU FACEM:   tot restul: victoria, înfrângerea, scorul, swipe-ul, designul

VERIFICARE: joc cinci minute și notez ce lipsește și ce e în plus

Uitați-vă ce s-a schimbat. Scopul nu e jocul, ci înțelegerea. "Nu facem" e cel mai lung rând, în el intră tot ce nu știți sigur dacă vreți. Iar verificarea nu e "merge sau nu", ci "ce știu acum". Ați jucat cinci minute - și întrebările pe care nu le puteați pune la început apar singure: swipe-ul nu e necesar, la calculator se joacă cu săgețile; scorul e necesar, fără el e plictisitor; 4×4 e puțin, aș vrea să încerc 5×5; înfrângerea trebuie afișată, altfel nu e clar că jocul s-a terminat.

Acesta e rezultatul sandboxului. Nu cod, ci răspunsuri. Din ele se scrie specificația adevărată, iar jocul se construiește de la zero, într-un folder curat, cu o singură frază: "construiește jocul după specificația din fișier". Sandboxul și-a făcut treaba.

E același lanț din prima secțiune, doar că pasul "Întrebări" a fost înlocuit aici de o buclă: când nu aveți ce întreba, mai întâi vă uitați, apoi notați. În jos, în specificație, ajunge un singur lucru - răspunsurile. Sandboxul nu are săgeată spre agent și nu e o scăpare: versiunea adevărată agentul o construiește într-un folder curat, de la zero. de aici încolo totul urmează lanțul.

6. Specificația stă într-un fișier

De ce un fișier și nu conversația. Conversația se pierde: după zece mesaje regula despre unirea plăcilor nu o mai găsiți. Fișierul stă în folderul proiectului, lângă cod, agentul îl citește singur când i-l indicați, iar după o corectură îl puteți da din nou cu aceeași frază. Numele poate fi oricare: SPEC_2048.md, SPEC_LANDING.md, chiar și sarcina.txt. E un fișier text obișnuit, fără niciun format special.

Îl dați agentului cu o singură frază. Comparați:

Înainte: "construiește jocul 2048, știi tu care, ceva mai interesant".

După: "construiește jocul după specificația din fișierul SPEC_2048.md".

A doua cerere e mai scurtă decât prima, dar are de zece ori mai multă informație - toată e în fișier. Nu trebuie să copiați textul specificației în chat, agentul deschide singur fișierul.

Ce schimbați în fișier și ce spuneți în cuvinte. Reperul e acesta: s-a schimbat o regulă sau o limită - corectați fișierul și îl dați din nou ("victorie la 2048, nu la 1024" - asta merge în fișier). S-a schimbat un mic detaliu vizual, care nu afectează regulile - puteți spune în cuvinte ("fă butonul albastru"). Dacă aveți dubii - în fișier: un rând în plus costă mai puțin decât o regulă uitată.

Despre dimensiune. Pentru o sarcină mică sunt șase-opt rânduri, ca blocul pentru 2048 de mai sus. Dacă specificația pentru un joc de o seară s-a întins pe două pagini, cel mai probabil a ajuns în ea ceva ce trebuia să ajungă la "nu facem".

Și ultimul lucru înainte să-i dați fișierul agentului: citiți-l o dată ca și cum ar fi al altcuiva. Un rând care nu se poate verifica se găsește aproape mereu. eu găsesc de fiecare dată.

7. Ce face agentul cu specificația și ce vă rămâne dumneavoastră

Să punem totul într-o singură imagine: ce face Claude Code în această schemă și ce rămâne de partea dumneavoastră. Pereche cu pereche.

Rostul specificației nu e ca agentul să înțeleagă. Și din două cuvinte va construi ceva. Rostul e ca dumneavoastră să știți ce ați comandat și să puteți verifica.