Cum să formulați un criteriu verificabil pentru /goal

Imaginați-vă: îi cereți agentului să joace o partidă într-un joc care rulează deja în browser. Face câteva mutări, descrie poziția și se oprește. Partida continuă. Îi scrieți "continuă". Mută din nou piesele și iar așteaptă un mesaj. La un moment dat vă dați seama că dumneavoastră faceți cea mai monotonă parte a muncii.

Goal este un obiectiv cu un criteriu de finalizare, pe care îl definiți pentru agent prin comanda /goal. De exemplu: "jucați pe rând cu ambele părți până când pagina arată că partida s-a încheiat". După fiecare tură de lucru, un model separat verifică din conversație dacă obiectivul a fost atins. Dacă nu, lucrul continuă fără să-i mai scrieți "continuă". Astfel puteți aștepta rezultatul, deși un obstacol sau o eroare poate opri lucrul mai devreme.

Vom porni de la un criteriu gata formulat pentru joc, apoi vom defini obiective pentru căutare, un formular și o pagină mobilă. Fiecare va avea un rezultat clar și o metodă de verificare. Vom vedea și cum îi puteți cere agentului să formuleze criteriul și cum deosebiți finalizarea propriu-zisă de o oprire fără rezultat.

Ce continuă /goal

În conversația despre joc sunt implicate două mecanisme diferite, pe care le puteți confunda ușor. Unul acționează în browser: dă clic, face mutări și citește ce afișează pagina. Celălalt nu dă clic deloc - citește întreaga conversație și decide dacă lucrul trebuie să continue.

Primul mecanism este Playwright, un instrument de browser conectat în prealabil prin MCP. Al doilea este pornit de comanda /goal. Playwright mută piesele, /goal decide dacă e timpul ca lucrul să se oprească - sunt două sarcini diferite, chiar dacă din exterior par una și aceeași.

Un detaliu important: evaluarea nu are loc după fiecare clic de mouse, ci după ce agentul și-a încheiat tura de lucru - cu alte cuvinte, după întregul său răspuns. Într-o singură tură agentul poate face mai multe acțiuni la rând: să mute o piesă, să citească rezultatul și să reacționeze la el. /goal intervine abia după aceea, când are ce evalua.

Pregătiți jocul pentru rulare

Înainte să definiți un criteriu, exemplul trebuie să fie funcțional: pagina se deschide la o adresă cunoscută, instrumentele necesare pentru joc sunt deja conectate (același Playwright), iar pagina are un marcaj care arată dacă partida s-a încheiat.

În exemplul nostru, acesta este un atribut data: data-game-over="false" cât timp partida continuă și data-game-over="true" după încheiere. Convenția e stabilită de autorul paginii jocului - agentul nu o inventează, ci doar o citește.

E ușor de verificat: cereți-i agentului să deschidă pagina și să citească valoarea atributului. Pentru o partidă abia începută, va primi false. E în regulă, exact asta ar trebui să apară la început.

Dacă atributul lipsește cu totul, e prea devreme să definiți un obiectiv. Criteriul se poate baza doar pe ceva ce poate fi citit efectiv, așa că mai întâi trebuie readus marcajul, nu inventată o alternativă pe loc. Și, odată ce exemplul e configurat, nu schimbați criteriul în timpul partidei și nu adăugați un cronometru separat doar ca demonstrația să se termine mai repede. Criteriul rămâne același de la început până la sfârșit.

Porniți obiectivul pregătit

Urmează comanda propriu-zisă. Criteriul pentru exemplul nostru poate arăta astfel:

/goal jucați pe rând cu ambele părți prin interfața paginii.
După fiecare mutare, citiți data-game-over și arătați ce se vede
pe pagină. Partida este încheiată când data-game-over devine
true. Dacă nu se întâmplă după 40 de mutări, opriți-vă și descrieți
unde v-ați blocat. Nu modificați codul jocului.

Să analizăm formularea pe părți. Le puteți folosi și în propriile sarcini:

• "jucați... prin interfața paginii" - o acțiune măsurabilă, pe care agentul o poate demonstra în conversație;
• "partida este încheiată când data-game-over devine true" - singurul lucru care contează aici drept rezultat real. Evaluatorul va căuta tocmai această dovadă în conversație;
• "după fiecare mutare citiți... și arătați" - faptul care îi permite evaluatorului să verifice ceva. Fără această cerință, nu are ce analiza;
• "dacă nu se întâmplă după 40 de mutări, opriți-vă și descrieți" - o instrucțiune separată pentru cazul în care true nu apare. Nu face parte din succes, ci oferă o cale de oprire fără rezultat: limitează volumul de lucru, dar nu ține locul rezultatului. Rămâne o instrucțiune în text, nu un cronometru programatic strict - și ea este evaluată pe baza conversației;
• "nu modificați codul jocului" - ceva ce nu trebuie să se întâmple cât timp agentul încearcă să obțină rezultatul.

Nu se știe dinainte ce se va întâmpla - nu putem promite un anumit câștigător, durata partidei sau chiar încheierea ei. Știm însă ce trebuie să arate agentul: starea jocului pe care a citit-o și motivul pentru care continuă sau oprește lucrul.

Din ce să formulați criteriul

Porniți de la expresia "sarcina e încheiată când...". Dacă fraza continuă cu "totul merge mai bine", agentul va trebui să ghicească ce ați vrut să spuneți. Înlocuiți aprecierea cu un comportament observabil: "după golirea căutării, toate cardurile apar din nou". Puteți defini mai multe verificări, dacă descriu același rezultat, de exemplu repararea căutării.

• Numiți rezultatul. "Reparați căutarea" indică direcția, în timp ce "căutarea găsește cardul după nume și afișează lista completă după golire" stabilește punctul de finalizare.
• Precizați verificarea. Scrieți ce trebuie deschis, ce trebuie introdus și ce răspuns se așteaptă. Cereți-i agentului să arate rezultatul efectiv în conversație, ca evaluatorul să-l poată citi.
• Limitați modificările. Dacă trebuie schimbate doar stilurile, spuneți asta. Dacă agentul verifică un joc deja pregătit, interziceți modificarea codului pentru a obține rezultatul dorit.
• Prevedeți o oprire fără succes. De exemplu, după trei încercări de remediere cu reverificare, agentul trebuie să descrie problema rămasă. Aceasta e o limită a lucrului, nu o altă modalitate de a declara sarcina încheiată.

Înainte de pornire, verificați dacă agentul are acces la pagina, fișierele și instrumentele necesare. Adresa și numele elementelor din criteriu trebuie să corespundă proiectului dumneavoastră. Limita de încercări formulată în text ajută la gestionarea lucrului, dar nu impune o limită tehnică strictă de timp sau cost.

Uitați-vă la săgeata de întoarcere. Dacă rezultatul nu a fost încă atins, agentul primește următoarea tură de lucru, poate remedia problema și apoi verifica din nou. Dar ieșirea din acest ciclu nu înseamnă întotdeauna succes: obstacolul sau limita convenită trebuie menționate separat. Schema arată logica de lucru a criteriului; agentul și evaluatorul urmăresc numărul de încercări pe baza conversației.

Trei exemple pentru propriile sarcini

Mai jos găsiți formulări didactice pentru pagini deja existente. Înlocuiți adresele, datele și comportamentul așteptat cu cele din proiectul dumneavoastră înainte de pornire. Sunt exemple de criterii, nu rapoarte despre lucrări efectuate.

Reparați căutarea în catalog

Să presupunem că un catalog local conține cardurile "Atlas" și "Orion", dar lista rămâne goală după golirea câmpului de căutare. Cererea "faceți o căutare ca lumea" nu spune ce comportament vă trebuie. Mai utile sunt trei cazuri concrete:

/goal reparați căutarea din catalogul http://localhost:3000/catalog.
Sarcina e încheiată când interogarea "atlas" găsește cardul "Atlas",
interogarea "zzzz-no-match" afișează "Nu s-au găsit rezultate",
iar golirea câmpului readuce toate cardurile inițiale.
Verificați toate cele trei cazuri prin Playwright și arătați în conversație
interogarea, rezultatul așteptat și cardurile sau mesajul afișat efectiv.
Repetați toate cele trei verificări după ultima modificare.
Schimbați doar logica de căutare; nu modificați datele sau aspectul catalogului.
Dacă problema persistă după trei încercări de remediere și verificare,
opriți-vă și enumerați cazurile care încă nu funcționează.

Aici contează cuvântul "toate": găsirea unui singur card nu confirmă încă faptul că căutarea a fost reparată. Datele catalogului sunt fixe, deci nu puteți obține rezultatul dorit redenumind cardurile. Iar reverificarea după ultima modificare e importantă fiindcă remedierea golirii ar fi putut strica însăși căutarea.

Verificați formularul fără să-l modificați

Rezultatul unui obiectiv poate fi o listă de observații. Să presupunem că trebuie verificat un formular de înregistrare deja existent, iar remedierile vreți să le discutați separat. Atunci obiectivul se încheie după verificarea tuturor cazurilor, chiar dacă se găsesc erori.

/goal verificați formularul de la http://localhost:3000/signup
prin Playwright, fără să modificați fișierele proiectului.
Verificați două cazuri, pornind de fiecare dată cu formularul gol:
1. Apăsați "Înregistrați-vă" fără să completați câmpurile.
Rezultat așteptat: apare un mesaj despre câmpul obligatoriu, înregistrarea nu are loc.
2. Introduceți "alex" în câmpul email și completați celelalte câmpuri
obligatorii cu valori de test valide, apoi apăsați butonul.
Rezultat așteptat: apare o eroare de format pentru email, înregistrarea nu are loc.
Sarcina e încheiată când conversația conține un raport despre ambele cazuri:
ce s-a introdus, ce se aștepta, ce a afișat pagina și dacă există diferențe.
Nu trimiteți formularul cu o adresă email validă și nu creați conturi.
Dacă pagina sau un element nu poate fi deschis, opriți verificarea
și precizați ce caz a rămas neverificat și de ce.

Observați diferența: "verificați formularul" și "faceți formularul să funcționeze" sunt două sarcini diferite. O eroare în formular nu împiedică încheierea raportului, dacă agentul a verificat într-adevăr ambele cazuri și a arătat rezultatele. Dar o pagină inaccesibilă împiedică încheierea: presupunerile nu țin locul observațiilor.

Adaptați pagina pentru telefon

"Faceți pagina frumoasă pe mobil" lasă prea mult la latitudinea agentului. Alegeți pagina concretă, dimensiunile ferestrei și elementele care trebuie să rămână accesibile.

/goal ajustați stilurile paginii http://localhost:3000
pentru ferestrele 390x844 și 1440x900.
Sarcina e încheiată când nu există derulare orizontală la niciuna dintre dimensiuni,
titlul și butonul "Începeți" sunt vizibile complet și nu se suprapun,
iar clicul pe "Începeți" deschide în continuare secțiunea jocului.
Verificați ambele dimensiuni prin Playwright după ultima modificare.
Arătați capturile de ecran, rezultatul clicului și valorile măsurate
scrollWidth și clientWidth pentru elementul rădăcină al paginii:
scrollWidth nu trebuie să fie mai mare decât clientWidth.
Modificați doar CSS. Nu ascundeți și nu decupați conținutul
ca să eliminați derularea. Păstrați textul și comportamentul jocului.
Dacă după trei încercări de modificare și verificare criteriile nu sunt îndeplinite,
opriți-vă și arătați ce diferență a rămas.

Aici dimensiunile reprezintă lățimea și înălțimea ferestrei browserului, în pixeli. scrollWidth arată lățimea conținutului, inclusiv zona care depășește marginea, iar clientWidth arată lățimea disponibilă. Compararea lor ajută la detectarea depășirilor, dar nu dovedește singură că textul nu e tăiat și că butonul poate fi folosit. De aceea criteriul mai cere capturi de ecran și un clic. Nici două dimensiuni nu demonstrează că pagina e comodă pe toate dispozitivele - ele definesc volumul acestei sarcini.

Cereți agentului să pregătească un goal

Nu trebuie să formulați criteriul de la zero. Colecția Claude Code Best Practice adună două sfaturi din comunitate: cereți-i agentului să propună obiective pe baza contextului proiectului și să-i cereți să formuleze textul după ce citește conversația și fișierele. Mai jos adaptăm aceste idei pentru o sarcină mică.

Dacă încă nu știți ce să-i încredințați agentului pentru o activitate de durată, începeți cu un mesaj obișnuit, fără /goal:

Citiți conversația curentă și fișierele proiectului relevante pentru sarcină.
Propuneți trei obiective utile, care pot fi duse până la un
rezultat verificabil. Pentru fiecare, numiți rezultatul, metoda de verificare,
limitele modificărilor și ce informații mai lipsesc pentru a începe.
Țineți cont de ce am stabilit. Nu porniți încă obiectivele,
nu modificați fișierele. Dacă intenția nu e clară, puneți întrebări.

Alegeți un obiectiv. Lucrul de durată nu e un avantaj în sine: o căutare reparată e mai utilă decât câteva ore de "îmbunătățiri" neclare. Când sarcina e deja clară, puteți sări peste primul mesaj și cere direct o schiță a criteriului:

Formulați textul /goal pentru sarcina aleasă, pe baza conversației,
a fișierelor proiectului și a documentației sale. Nu executați nimic încă.
Precizați rezultatul observabil, cum se verifică și ce trebuie arătat
în conversație. Adăugați limitele modificărilor și o condiție de oprire fără succes.
Nu inventați adrese, comenzi sau criterii de finalizare:
găsiți-le în proiect sau cereți-mi clarificări.
Returnați un singur text gata de folosit și enumerați separat neclaritățile.

Înainte să trimiteți schița, verificați dacă are sens. Rezultatul corespunde cu ce v-ați dorit? Pagina indicată există? Nu cumva agentul a permis în treacăt și modificarea datelor sau adăugarea de funcții? Dacă au rămas neclarități la final, lămuriți-le mai întâi. Porniți lucrul doar cu textul clarificat: comanda /goal începe imediat execuția.

Verificați starea și opriți lucrul

Cât timp obiectivul este activ, îi puteți urmări progresul: comanda /goal fără argumente afișează starea curentă - criteriul, timpul și numărul de ture scurse, plus ultimul motiv returnat de evaluator.

Puteți opri obiectivul mai devreme cu comanda /goal clear. Aceasta elimină criteriul chiar dacă partida nu s-a încheiat.

Două situații pot fi considerate rezultate confirmate: criteriul a fost îndeplinit, iar răspunsul evaluatorului din conversație arată asta, sau ați eliminat manual obiectivul cu /goal clear înainte să se dovedească ceva. Celelalte moduri în care obiectivul se poate opri de la sine nu intră în aceste două situații și nu confirmă rezultatul.

Ce primește modelul evaluator

Evaluatorul /goal nu vede pagina, ci conversația: ce a scris agentul și ce a copiat acolo din observațiile browserului. Evaluatorul nu are instrumente proprii - nu redeschide pagina și nu execută singur comenzi, ci doar citește textul adunat până atunci.

Consecința e simplă. Afirmația agentului "partida s-a încheiat" nu dovedește nimic, nici pentru evaluator, nici pentru dumneavoastră. Dovadă este rezultatul citit efectiv de agent de pe pagină - valoarea data-game-over. Prima e o relatare, a doua e o observație; sunt lucruri diferite, chiar dacă sună asemănător.

Merită să înțelegeți și limitele acestui indicator. data-game-over comunică starea unei anumite aplicații - cea stabilită de autorul paginii. Nu spune dacă întreaga partidă a fost jucată după regulile șahului fără nicio greșeală. La fel, lipsa derulării nu dovedește că butonul funcționează. Alegeți un indicator potrivit rezultatului pe care chiar vreți să-l obțineți și nu-i atribuiți mai mult decât arată.

Ce schimbă asta în modul de lucru

Pentru propria sarcină, puteți urma același traseu scurt:

• un rezultat clar și o metodă accesibilă de verificare;
• un criteriu cu limite pentru modificări și oprire, stabilit prin comanda /goal;
• o stare pe care o puteți verifica oricând - /goal fără argumente;
• un rezultat susținut de observații și verificări;
• obiectivul eliminat manual cu /goal clear, dacă lucrul s-a blocat sau criteriul nu a fost potrivit.

Continuarea automată a lucrului și decizia despre ce urmează sunt două lucruri diferite. Pe prima o puteți încredința comenzii /goal într-o singură sesiune. A doua - să analizați ce s-a obținut de fapt, să eliminați obiectivul neîncheiat și să definiți următoarea sarcină - vă revine în continuare dumneavoastră.

Comportamentul exact al evaluatorului și formatul stării pot varia puțin în funcție de versiunea Claude Code. Principiul general rămâne același: evaluarea se bazează pe conversație, nu pe accesul direct la pagină.