Cum dovediți că o problemă a fost rezolvată

Punctajul a fost reparat. Răspunsul conține ieșirea din terminal, o captură a tabelei de scor și un scurt "gata"; sunt multe fișiere, dar întrebarea e simplă: care dintre ele răspunde cerinței?

O dovadă nu este orice fișier aflat pe lângă remediere. Este rezultatul unei verificări concrete, din care se vede ce a fost verificat, în ce stare era codul și ce rezultat a apărut. Materiale diferite răspund la întrebări diferite, iar niciunul nu răspunde la toate deodată.

Vom vedea cum transformăm cerința într-o afirmație verificabilă, ce notăm despre rularea unei comenzi și ce dovedesc logul, diff-ul și captura de ecran. Apoi le adunăm într-un jurnal concis, EVIDENCE_LOG, cu șase câmpuri și verificăm dacă un set de materiale oferă suficiente dovezi.

Criteriul definește verificarea

Vom folosi același exemplu pe tot parcursul articolului: un mic joc bonus, cu scorul afișat pe tabelă. Scorul inițial este 0; trei potriviri ar trebui să adauge 3 puncte, însă înainte de remediere adăugau 30. Regula de punctare a fost inventată pentru acest joc - într-un alt proiect poate fi cu totul diferită, așa că nu o transferați acolo.

Afirmația "scorul a fost reparat" nu se poate verifica: nu e clar ce să rulați și la ce să vă uitați. O afirmație verificabilă are trei părți: starea inițială, acțiunea și observația așteptată. De exemplu: "cu scorul la 0, trei potriviri adaugă 3 puncte, iar tabela afișează 3". Acum afirmația poate fi verificată.

Apoi o descompunem în observații separate. Calculul și ceea ce vede jucătorul sunt lucruri diferite și se dovedesc în moduri diferite. Al treilea rând din tabel se referă la înregistrarea punctajului în clasament. Poate că sarcina nici nu conține această cerință, dar, dacă o conține, are nevoie de propria observație.

A treia coloană este cea mai utilă. O dovadă confirmă aproape întotdeauna mai puțin decât ne-am dori, iar limita ei se află acolo unde se termină acțiunea efectuată. În exemplul nostru, testul de calcul nu verifică tabela, iar captura tabelei nu arată rândul de cod modificat.

Țineți separat două lucruri: cerința descrie ce ar trebui să fie adevărat la final, iar rezultatul arată ce ați obținut de fapt. Când le amestecați în același paragraf, "ar trebui să adauge 3" se transformă pe nesimțite în "adaugă 3", deși nimeni n-a rulat nimic.

Comanda și rezultatul ei

O rulare de verificare este descrisă prin cinci lucruri. Pentru cineva care va repeta verificarea peste o săptămână, niciunul nu e de la sine înțeles:

• directorul din care a fost rulată comanda;
• comanda exactă, fără modificări;
• starea codului: înainte sau după remediere și cu ce modificări necomise;
• rezultatul: codul de ieșire și contoarele finale;
• ce verificări au participat efectiv și care nu.

Faceți distincția între "trebuie rulat npm test" și "am rulat npm test, iată rezultatul". Prima formulare este o instrucțiune, un plan pentru mai târziu. A doua descrie un fapt. Aici intenția trece ușor drept rezultat, mai ales când răspunsul enumeră frumos ce ar fi trebuit verificat.

npm test nu rulează "toate testele, în general". Execută ce este definit în câmpul test din secțiunea scripts a unui anumit package.json - cel al proiectului npm selectat. Ca să nu ghiciți ce proiect a fost ales, rulați comanda din rădăcina lui și notați directorul în jurnal. În alt proiect, același nume poate desemna un alt instrument, un alt set de pași sau nimic.

Comanda se încheie cu un cod de ieșire: 0 înseamnă de obicei că "instrumentul consideră rularea reușită". În bash, îl afișează echo $? imediat după comandă; în PowerShell, pentru un program extern precum npm, îl găsiți în $LASTEXITCODE. Totuși, valoarea zero nu arată dacă testul de care aveți nevoie a fost rulat: poate să fi fost omis, filtrat după nume sau să nu fi fost scris deloc. De aceea, notați întotdeauna contoarele și numele testului relevant, alături de codul de ieșire.

Ce să păstrați din log

Ieșirea unei rulări poate fi lungă, așa că nimeni nu o copiază integral în jurnal. Fragmentul scurt păstrează patru lucruri: numele testului eșuat, valoarea așteptată și cea obținută, motivul eșecului și contoarele finale. Restul rămâne într-un fișier către care adăugați un link. Mai jos este un exemplu didactic prescurtat, nu înregistrarea unei rulări efectuate.

✖ three matches give 3 points (2.4108ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  30 !== 3
      at TestContext.<anonymous> (src/bonus-game/score.test.js:8:10)
ℹ tests 1
ℹ pass 0
ℹ fail 1
ℹ skipped 0

Acesta este un fragment; ieșirea completă este salvată într-un fișier, de exemplu logs/test-fail.txt. Fragmentul arată deja esențialul: a eșuat testul pentru trei potriviri, valoarea așteptată era 3, cea obținută a fost 30, iar niciun test nu a fost omis.

Ieșirea originală se pune în jurnal exact așa cum este. O parafrazare ("testul a eșuat din cauza multiplicatorului greșit") pare mai clară, dar este deja o concluzie, nu o observație, și nu poate fi verificată pe baza jurnalului. Păstrați-le alături: mai întâi rândurile instrumentului, apoi explicația dumneavoastră.

Adresa din stack trace indică locul în care s-a declanșat verificarea, adică fișierul testului. Cauza se caută în codul jocului, iar multiplicatorul găsit acolo rezultă din citirea codului, nu dintr-un rând al logului. În jurnal, notați distinct aceste două surse; altfel, mai târziu nu veți ști de unde a apărut valoarea 10.

Ce dovedește diff-ul

Diff-ul arată diferența dintre două stări ale unui fișier. Nu arată dacă ați rulat măcar o dată codul după remediere și, cu atât mai puțin, dacă comportamentul s-a schimbat așa cum vă așteptați.

--- a/src/bonus-game/score.js
+++ b/src/bonus-game/score.js
@@ -1,5 +1,5 @@
-const POINTS_PER_MATCH = 10;
+const POINTS_PER_MATCH = 1;

 function calcScore(matches) {
   return matches * POINTS_PER_MATCH;
 }

Sub acest fragment, adăugați un singur rând care precizează ce stări ați comparat. De exemplu: "arborele de lucru față de commit-ul a1b2c3d de dinaintea remedierii, comanda git diff HEAD"; identificatorul este didactic, în jurnal folosiți unul real. Comanda compară fișierele urmărite curente cu HEAD, inclusiv modificările pregătite pentru commit. Comanda obișnuită git diff, fără HEAD, arată doar diferența față de starea pregătită și poate să nu afișeze nimic după git add. Fără această notă, diff-ul arată doar "ceva față de altceva", iar comparația nu poate fi repetată.

Verificați separat că valoarea așteptată de test a rămas 3. Dacă ați schimbat și valoarea așteptată împreună cu codul, situația e alta: testul s-a adaptat comportamentului, nu comportamentul s-a adaptat cerinței.

Urmează un mic detaliu tehnic, ușor de încurcat. Cât timp modificarea nu a fost comisă, o vedeți comparând arborele de lucru cu ultimul commit. După commit, aceeași comparație va fi goală; asta nu înseamnă că nu s-a schimbat nimic în sarcină, ci doar că modificarea a intrat în istoric, iar acum trebuie să comparați commit-ul cu starea anterioară. Un diff gol nu dovedește nimic de unul singur; contează care sunt cele două stări comparate.

Ce se vede în captura de ecran

Starea și acțiunea

O captură în care tabela afișează 3 confirmă un singur lucru: în momentul capturii, pe tabelă era afișat 3. Nu este același lucru cu afirmația "trei potriviri au adăugat 3 puncte". Între cele două afirmații se află tot ce nu apare în imagine: scorul de la care ați pornit și ce ați făcut.

Pentru ca imaginea să devină o dovadă, notați alături scenariul:

1. ce ați deschis: adresa paginii sau modul de pornire și versiunea folosită, cu sau fără remediere;
2. starea inițială: scorul de la început era 0, fără date vechi preluate;
3. acțiunea: ați obținut trei potriviri;
4. observația: tabela afișa 3, iar captura a fost făcută imediat după acțiune.

Fără această notă, aceeași captură poate fi obținută în zeci de feluri. O filă deschisă de ieri cu o versiune veche, o altă pornire sau un scor care nu era zero de la început - toate pot produce o imagine convingătoare, dar lipsită de sens.

Articolul nu include intenționat o captură a tabelei. Pentru verificare, faceți captura după ce reproduceți scenariul pe versiunea potrivită, manual sau cu instrumente de automatizare. O tabelă desenată ori compusă pentru ilustrație nu devine dovadă, chiar dacă arată identic. Când faceți captura, includeți tabela în întregime, notați adresa paginii în descrierea scenariului și păstrați imaginea lângă acea notă; altfel, peste o săptămână nu vă veți mai aminti ce rulare era.

Ce poate citi modelul

Puteți trimite imaginea în sesiune și îi puteți cere modelului s-o citească. Formularea contează: cereți să indice numărul vizibil și să enumere incertitudinile ("se vede starea inițială?", "este clar ce versiune apare?"), nu să confirme o concluzie stabilită dinainte. Dacă îi cereți "confirmă că problema a fost rezolvată", puteți primi cu ușurință un acord politicos care nu verifică nimic.

Posibilitatea de a trimite o imagine depinde de model și de mediul în care lucrați. În Claude Code, puteți indica calea către imaginea salvată și îi puteți cere să o citească. Dacă imaginea nu s-a încărcat, verificați mai întâi calea și dacă fișierul este accesibil; simpla schimbare a modelului nu garantează rezolvarea problemei.

Același scenariu, înainte și după

O comparație utilă arată astfel: aceeași verificare eșuează pe implementarea defectă și trece pe cea remediată. Eșecul arată că verificarea detectează defectul; reușita arată că, după remediere, defectul nu mai apare în scenariul verificat.

Comparația este validă doar dacă folosiți aceleași date de intrare și aceleași așteptări: același scor inițial, același număr de potriviri și aceeași valoare așteptată, 3. Iată rezultatul reușit al aceluiași test după remediere:

✔ three matches give 3 points (1.3983ms)
ℹ tests 1
ℹ pass 1
ℹ fail 0
ℹ skipped 0

Între rulări se schimbă implementarea, iar testul, datele de intrare, rezultatul așteptat și condițiile de rulare rămân aceleași. Dacă a trebuit să schimbați cerința sau valoarea așteptată în test, faceți o nouă pereche de rulări cu această verificare: o explicație în cuvinte nu înlocuiește rularea în ambele stări. Într-o astfel de situație, un simplu "era roșu, acum e verde", spus fără nicio explicație, induce în eroare.

Nici două fișiere numite before.txt și after.txt nu garantează ceva de la sine. Numele fișierului nu este o dovadă. Verificați conținutul: este aceeași comandă, același test, aceeași valoare așteptată? Revenirea de control la starea defectă (tehnica aceea cu git stash) este o verificare separată, cu propriile reguli. Aici e suficient să rețineți că rezultatul roșu de dinaintea remedierii trebuie să provină dintr-o rulare reală, nu din memorie.

Un EVIDENCE_LOG concis

EVIDENCE_LOG este, în acest articol, un jurnal text obișnuit cu șase câmpuri, în această ordine: SIMPTOM, DOVADĂ DIN LOG, EȘEC PE CODUL DEFECT, REMEDIERE, REZULTAT VERDE REAL, CAPTURĂ DE ECRAN. Astfel, simptomul, remedierea și rezultatul se compară mai ușor. Ordinea câmpurilor nu garantează însă că înregistrările sunt corecte.

Tot ce am adunat mai sus se potrivește în aceste câmpuri. Comanda și directorul apar la câmpul despre eșec, stările comparate la remediere, iar linkurile către fișierele complete în câmpul din care provin. Nu e nevoie să creați un alt pachet de documente.

Mai jos este un exemplu didactic de completare: arată ce să scrieți în fiecare câmp, nu raportează verificări efectuate. În jurnalul dumneavoastră, înlocuiți textul cu rezultatele obținute de fapt.

SIMPTOM: în jocul bonus, cu scorul inițial 0, trei potriviri
acordă 30 de puncte în loc de 3. Se reproduce de fiecare dată:
deschideți jocul, obțineți trei potriviri, verificați tabela.

DOVADĂ DIN LOG: ieșirea rulării arată "30 !== 3" la testul
"three matches give 3 points"; ieșirea completă este în logs/test-fail.txt.
Separat, din citirea codului: în src/bonus-game/score.js,
multiplicatorul POINTS_PER_MATCH este 10. Această valoare provine
din cod; numărul 10 nu apare în ieșirea testului.

EȘEC PE CODUL DEFECT: HEAD a1b2c3d (identificator didactic),
arborele de lucru este curat; commit-ul conține calculul defect și testul.
Directorul - /project/bonus-game, comanda - npm test.
În package.json, scripts.test = node --test. Eșuează "three matches give 3 points",
motivul "30 !== 3", tests 1, pass 0, fail 1, skipped 0, cod de ieșire 1.
Fragmentul de ieșire este mai sus, iar cel complet - logs/test-fail.txt.

REMEDIERE: POINTS_PER_MATCH a fost schimbat de la 10 la 1 în fișierul
src/bonus-game/score.js; nu există alte modificări. HEAD este același a1b2c3d.
Diff: git diff HEAD, arborele de lucru comparat cu acest commit;
salvat în diffs/score-fix.diff.
Valoarea așteptată în test a rămas 3.

REZULTAT VERDE REAL: aceeași comandă npm test, din același director,
pe codul de după remedierea descrisă. Același test trece: tests 1, pass 1,
fail 0, skipped 0, cod de ieșire 0.
Ieșirea completă - logs/test-pass.txt.
Scenariul cu cinci potriviri nu a fost rulat.

CAPTURĂ DE ECRAN: screenshots/bonus-score-3.png. Jocul a fost redeschis
la adresa http://localhost:3000 din același arbore de lucru,
după remediere. Scorul inițial era 0, au fost obținute trei potriviri,
tabela afișa 3. Salvarea rezultatului în clasament nu a fost verificată.

Căile din exemplu sunt doar orientative. Păstrați logurile complete, diff-urile și imaginile acolo unde proiectul stochează deja materiale similare; nu este nevoie de o structură separată și obligatorie de directoare.

Observați ultimele două rânduri din câmpurile 5 și 6. Menționați omisiunea direct, într-o singură formulare: "nu a fost rulat", "nu a fost verificat". Nu e o recunoaștere a lenei, ci limita concluziei. Fără aceste precizări, jurnalul pare mai complet, dar de fapt nu spune nimic despre ce nu a făcut nimeni.

Verificați ce ați reținut

Sarcina are două criterii: calculul acordă 3 puncte pentru trei potriviri pornind de la zero, iar interfața afișează 3 după aceleași trei potriviri. Aveți la dispoziție șase materiale:

1. mesajul agentului "gata, problema a fost rezolvată";
2. instrucțiunea de a rula npm test;
3. rulările efective ale aceluiași test: eșuează înainte de remediere și trece după;
4. diff-ul care arată schimbarea multiplicatorului;
5. o singură captură cu numărul 3, fără descrierea pornirii;
6. înregistrarea scenariului reprodus, cu captura asociată.

Care dintre ele sunt suficiente pentru cele două criterii și ce rămâne neverificat? Încercați să răspundeți înainte să continuați.

Răspunsul. Primul criteriu este acoperit de punctul 3: perechea reală de rulări ale aceluiași test. Diff-ul din punctul 4 explică ce s-a schimbat în cod, dar nu înlocuiește rularea - modificarea și executarea sunt lucruri diferite. Al doilea criteriu este acoperit de punctul 6: captura împreună cu descrierea scenariului, în care se văd starea inițială și acțiunea. Punctele 1 și 2 nu dovedesc nimic: mesajul că totul e gata nu oferă o dovadă verificabilă, iar instrucțiunea descrie o acțiune viitoare. Punctul 5 arată numărul 3, dar atât; nu se poate stabili cum a fost calculat. Iar salvarea rezultatului în clasament rămâne neverificată chiar și cu toate cele șase materiale în față: lipsește scenariul în care valoarea salvată este citită înapoi.

Puteți alcătui un astfel de jurnal și într-o sesiune. Iată un prompt gata de folosit:

Alcătuiește un EVIDENCE_LOG cu șase câmpuri. Pentru fiecare concluzie,
indică verificarea efectuată, starea codului și sursa rezultatului.
Menționează separat ce nu a fost rulat. În captura de ecran, descrie doar
ce se vede și nu deduce din ea corectitudinea calculului intern.

Cum adunați dovezi cu Claude Code

Fluxul de lucru arată astfel:

1. agentul leagă fiecare criteriu de o verificare concretă: ce să ruleze, în ce stare a codului și ce să considere rezultat;
2. rulează verificările disponibile în acel mediu și arată comanda împreună cu ieșirea originală;
3. atașează observațiile: fragmente din ieșire, linkuri către fișierele complete și descrierea scenariului reprodus;
4. precizează clar limitele: ce nu a fost rulat și ce nu se poate afirma pe baza materialelor disponibile.

Verificarea dovezilor vă revine: deschideți fișierele atașate și vedeți ce conțin, comparați scenariul cu cel descris în criteriu și puneți o întrebare incomodă despre punctul pentru care nu se vede nicio verificare. De obicei, e suficient ca să deosebiți dovezile adunate de o relatare doar frumos aranjată.

Referințe tehnice: git diff, git stash, Node.js test runner, npm test, imagini în Claude Code.