Ako doložiť opravu

Oprava bodovania je hotová. V odpovedi je výpis z terminálu, snímka výsledkovej tabule a stručné "hotovo". Súborov je veľa, otázka je však jednoduchá: čo z toho dokladá splnenie požiadavky?

Dôkaz nie je len hocijaký súbor, ktorý sa ocitol pri oprave. Je to výsledok konkrétnej kontroly, z ktorého vidno, čo sa overovalo, v akom stave bol kód a čo kontrola priniesla. Rôzne podklady odpovedajú na rôzne otázky a žiadny z nich nepokryje všetko naraz.

Pozrime sa, ako zmeniť požiadavku na overiteľné tvrdenie, čo zaznamenať o spustení príkazu a čo dokladá log, diff a snímka obrazovky. Potom to usporiadame do stručného záznamu EVIDENCE_LOG so šiestimi poliami a posúdime, či je pripravený súbor podkladov dostatočný.

Kritérium určuje kontrolu

Príkladom, ku ktorému sa v článku vrátime, je malá bonusová hra so skóre na tabuli. Na začiatku je skóre 0, tri zhody majú pridať 3 body, no pred opravou pridávali 30. Pravidlo bodovania je vymyslené pre túto hru. V inom projekte môže byť úplne iné, preto ho tam neprenášajte.

Vetu "skóre je opravené" nemožno overiť: nie je jasné, čo spustiť ani na čo sa pozerať. Overiteľné tvrdenie sa skladá z troch častí: počiatočný stav, akcia a očakávané pozorovanie. Napríklad: "pri skóre 0 pridajú tri zhody 3 body a na tabuli vidno 3". Teraz už vieme, ako tvrdenie overiť.

Tvrdenie sa ďalej rozdelí na samostatné pozorovania. Výpočet a to, čo vidí hráč, sú dve rôzne veci a každú treba doložiť inak. Tretí riadok tabuľky sa týka zápisu výsledku do rebríčka. Táto požiadavka nemusí byť súčasťou zadania, no ak tam je, potrebuje vlastné pozorovanie.

Tretí stĺpec je tu najužitočnejší. Dôkaz takmer vždy potvrdzuje menej, než by sme chceli, a jeho hranica je tam, kde sa končí vykonaná akcia. V našom príklade test výpočtu neoveruje tabuľu a snímka tabule neukazuje zmenený riadok kódu.

Oddeľujte tieto dve veci: požiadavka hovorí, čo má byť na konci pravda, výsledok zas, čo ste skutočne zistili. Keď ich zmiešame v jednom odseku, "má pridať 3" sa nenápadne zmení na "pridáva 3", hoci nikto nič nespustil.

Príkaz a jeho výsledok

Spustenie kontroly treba opísať piatimi údajmi. Ani jeden z nich nie je samozrejmý pre človeka, ktorý bude kontrolu o týždeň opakovať:

• priečinok, z ktorého sa príkaz spustil;
• presné znenie samotného príkazu;
• stav kódu: pred opravou, po nej a prípadné necommitnuté zmeny;
• ako sa spustenie skončilo: návratový kód a súhrnné počítadlá;
• ktoré kontroly sa naozaj vykonali a ktoré nie.

Rozlišujte medzi "treba spustiť npm test" a "spustil som npm test, tu je výpis". Prvé je pokyn, plán do budúcna. Druhé je fakt. Práve tu sa zámer ľahko vydá za výsledok, najmä keď odpoveď starostlivo opisuje, čo by sa malo skontrolovať.

npm test nespúšťa "všetky testy, ktoré existujú". Vykoná to, čo je uvedené v poli test v sekcii scripts konkrétneho package.json - teda vybraného npm projektu. Aby ste nemuseli hádať, ktorý projekt je vybraný, spúšťajte príkaz z jeho koreňového priečinka a tento priečinok zapíšte do záznamu. V inom projekte môže rovnaký názov znamenať iný nástroj, inú sadu krokov alebo vôbec nič.

Príkaz sa skončí návratovým kódom: 0 zvyčajne znamená "nástroj považuje spustenie za úspešné". V bashi ho hneď po príkaze zobrazí echo $?; v PowerShelli je pri externom programe, napríklad npm, k dispozícii $LASTEXITCODE. Nula však nehovorí, či sa požadovaný test naozaj vykonal. Mohol byť preskočený, odfiltrovaný podľa názvu alebo vôbec nemusel existovať. Preto k návratovému kódu vždy uveďte aj počítadlá a názov testu, ktorý vás zaujíma.

Čo si uložiť z logu

Výpis zo spustenia môže byť dlhý a nikto ho celý neprepisuje do záznamu. Stručný úryvok obsahuje štyri údaje: názov zlyhaného testu, očakávanú a skutočnú hodnotu, príčinu zlyhania a súhrnné počítadlá. Zvyšok zostáva v súbore, na ktorý vložíte odkaz. Nižšie je skrátený ukážkový výpis, nie záznam skutočného spustenia.

✖ 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

Toto je úryvok, celý výpis je uložený napríklad v súbore logs/test-fail.txt. Z úryvku už vidno to hlavné: zlyhal práve test o troch zhodách, očakávaná hodnota bola 3, skutočná 30 a žiadna kontrola sa nepreskočila.

Pôvodný výpis sa do záznamu vkladá bez úprav. Vlastnými slovami ("test zlyhal pre nesprávny násobiteľ") sa to vysvetľuje jednoduchšie, ale to je už záver, nie pozorovanie, a podľa logu sa nedá overiť. Uložte ich vedľa seba: najprv riadky nástroja, potom vaše vysvetlenie.

Adresa v riadku stack trace označuje miesto, kde sa kontrola vykonala, teda súbor testu. Príčinu hľadajte v kóde hry. Násobiteľ, ktorý tam nájdete, je výsledkom čítania kódu, nie riadkom z logu. V zázname tieto dva zdroje označte odlišne, inak neskôr nebude jasné, odkiaľ sa vzalo číslo 10.

Čo dokladá diff

Diff ukazuje rozdiel medzi dvoma stavmi súboru. Nehovorí, že sa kód po oprave čo i len raz spustil, a už vôbec nie, že sa správanie zmenilo podľa očakávania.

--- 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;
 }

Pod takýmto úryvkom má byť jeden riadok s popisom, ktoré stavy sa porovnali. Napríklad "pracovný strom oproti commitu a1b2c3d pred opravou, príkaz git diff HEAD". Identifikátor je tu len ukážkový, v zázname použite skutočný. Príkaz porovná aktuálne sledované súbory s HEAD vrátane zmien pripravených na commit. Bežný git diff bez HEAD ukazuje len rozdiely oproti pripravenému stavu a po git add už môže byť prázdny. Bez popisu diff hovorí len "niečo oproti niečomu" a porovnanie sa nedá zopakovať.

Ešte overte, že očakávaná hodnota v teste zostala 3. Ak sa spolu s kódom zmenilo aj očakávané číslo, je to iný príbeh: kontrola sa prispôsobila správaniu namiesto toho, aby sa správanie prispôsobilo požiadavke.

Ďalšia technická drobnosť, na ktorej sa dá ľahko pomýliť. Kým zmena nie je commitnutá, vidno ju pri porovnaní pracovného stromu s posledným commitom. Po commite to isté porovnanie ukáže prázdny výsledok. Neznamená to, že sa v úlohe nič nezmenilo, len zmena pribudla do histórie a treba porovnať commit s predchádzajúcim stavom. Prázdny diff sám osebe nič nedokazuje. Záleží na tom, ktoré dva stavy porovnávate.

Čo ukazuje snímka obrazovky

Stav a akcia

Snímka s číslom 3 na tabuli potvrdzuje presne jednu vec: v čase jej vytvorenia bolo na tabuli číslo 3. Nie je to to isté ako tvrdenie "tri zhody pridali 3 body". Medzi týmito tvrdeniami je všetko, čo na snímke nevidno: s akým skóre sa začalo a čo sa vlastne urobilo.

Aby sa snímka stala dôkazom, zaznamenajte k nej aj scenár:

1. čo ste otvorili: adresu stránky alebo spôsob spustenia a verziu, s opravou alebo bez nej;
2. počiatočný stav: skóre na začiatku je 0, staré údaje sa nenačítali;
3. akcia: vytvorili ste tri zhody;
4. pozorovanie: na tabuli je 3, snímka vznikla hneď po akcii.

Bez takého záznamu sa dá každá snímka vytvoriť desiatkami spôsobov. Karta so starou verziou otvorená od včera, iné spustenie, skóre, ktoré už nebolo nulové - to všetko vytvorí presvedčivý obrázok, ktorý nič nedokazuje.

Snímka výsledkovej tabule v tomto článku zámerne nie je. Kontrolný záber vytvorte až po zopakovaní scenára v správnej verzii, ručne alebo automatizovane. Nakreslená či ilustračne zostavená tabuľa sa dôkazom nestane, ani keď vyzerá úplne rovnako. Keď budete robiť vlastnú snímku, zachyťte celú tabuľu, do záznamu scenára uveďte adresu stránky a snímku uložte spolu so záznamom. Inak si o týždeň nespomeniete, o ktoré spustenie išlo.

Čo dokáže prečítať model

Obrázok môžete priložiť k relácii a požiadať model, aby ho prečítal. Rozhoduje formulácia: požiadajte ho, aby pomenoval viditeľné číslo a uviedol pochybnosti ("vidno počiatočný stav?", "je jasné, o ktorú verziu ide?"), nie aby potvrdil vopred určený záver. Na žiadosť "potvrď, že chyba je opravená" ľahko dostanete zdvorilý súhlas, ktorý nič neoveruje.

Možnosť odovzdať obrázok závisí od modelu a prostredia, v ktorom pracujete. V Claude Code môžete uviesť cestu k uloženému obrázku a požiadať o jeho prečítanie. Ak sa obrázok nenačíta, najprv skontrolujte cestu a dostupnosť súboru. Samotná zmena modelu problém nemusí vyriešiť.

Rovnaký scenár pred opravou a po nej

Užitočná dvojica vyzerá takto: rovnaká kontrola zlyhá na chybnej implementácii a prejde na opravenej. Zlyhanie ukáže, že kontrola túto chybu vôbec zachytí; úspešný výsledok zas potvrdí, že po oprave sa v overenom scenári chyba neprejavila.

Funguje to len vtedy, keď porovnávate rovnaké vstupné údaje a rovnaké očakávania. Rovnaké počiatočné skóre, rovnaký počet zhôd, rovnaká očakávaná hodnota 3. Tu je úspešný výsledok toho istého testu po oprave:

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

Medzi spusteniami sa zmení implementácia, ale test, vstupné údaje, očakávaná hodnota aj podmienky spustenia zostanú rovnaké. Ak ste museli zmeniť požiadavku alebo očakávanú hodnotu v teste, vytvorte novú dvojicu spustení s touto kontrolou. Slovné vysvetlenie nenahradí jej spustenie v oboch stavoch. Tiché "predtým červené, teraz zelené" by v takej situácii zavádzalo.

Samotné dva súbory s názvami before.txt a after.txt nič nezaručujú. Názov súboru nie je dôkaz. Pozrite sa dovnútra: je tam rovnaký príkaz, rovnaký test a rovnaké očakávanie? Kontrolný návrat k chybnému stavu (pomocou git stash) je samostatná kontrola s vlastnými pravidlami. Tu stačí vedieť, že červený výsledok pred opravou pochádza zo skutočného spustenia, nie zo spomienky.

Stručný EVIDENCE_LOG

EVIDENCE_LOG je v tomto článku obyčajný textový záznam so šiestimi poliami v tomto poradí: PRÍZNAK, INDÍCIA Z LOGU, ZLYHANIE PRED OPRAVOU, OPRAVA, POCTIVÝ ÚSPEŠNÝ VÝSLEDOK, SNÍMKA OBRAZOVKY. Takto sa príznak, oprava a výsledok ľahšie porovnávajú. Samotné poradie polí však dôveryhodnosť záznamov nezaručí.

Všetko, čo sme vyššie zhromaždili, patrí do týchto polí. Príkaz a priečinok uveďte pri zlyhaní, stavy na porovnanie pri oprave a odkazy na celé súbory pri zdroji, z ktorého pochádzajú. Ďalší balík dokumentov netreba zakladať.

Nižšie je ukážka vyplnenia. Naznačuje, čo patrí do každého poľa, nie je to však správa o skutočne vykonaných kontrolách. Vo vlastnom zázname nahraďte text skutočnými výsledkami.

PRÍZNAK: v bonusovej hre pri počiatočnom skóre 0 dajú tri zhody
30 bodov namiesto 3. Zopakuje sa to vždy: otvorte hru,
vytvorte tri zhody a pozrite sa na tabuľu.

INDÍCIA Z LOGU: vo výpise zo spustenia je "30 !== 3" v teste
"three matches give 3 points", celý výpis je v logs/test-fail.txt.
Samostatne, na základe čítania kódu: v src/bonus-game/score.js
má násobiteľ POINTS_PER_MATCH hodnotu 10. To vyplýva z čítania kódu,
číslo 10 sa vo výpise testu nenachádza.

ZLYHANIE PRED OPRAVOU: HEAD a1b2c3d (ukážkový identifikátor),
pracovný strom je čistý; commit obsahuje chybný výpočet a test.
Priečinok - /project/bonus-game, príkaz - npm test.
V package.json scripts.test = node --test. Zlyhá "three matches give 3 points",
príčina "30 !== 3", tests 1, pass 0, fail 1, skipped 0, návratový kód 1.
Úryvok výpisu je vyššie, celý výpis - logs/test-fail.txt.

OPRAVA: hodnota POINTS_PER_MATCH sa v súbore
src/bonus-game/score.js zmenila z 10 na 1; iné zmeny nie sú. HEAD je stále a1b2c3d.
Diff: git diff HEAD, pracovný strom oproti tomuto commitu;
uložený v diffs/score-fix.diff.
Očakávaná hodnota v teste zostala 3.

POCTIVÝ ÚSPEŠNÝ VÝSLEDOK: ten istý príkaz npm test z toho istého priečinka
na kóde po opísanej oprave. Ten istý test prejde: tests 1, pass 1,
fail 0, skipped 0, návratový kód 0.
Celý výpis - logs/test-pass.txt.
Scenár s piatimi zhodami sa nespustil.

SNÍMKA OBRAZOVKY: screenshots/bonus-score-3.png. Hra sa po oprave
znova otvorila na adrese http://localhost:3000 z toho istého pracovného stromu.
Počiatočné skóre je 0, vytvorili sa tri zhody
a na tabuli je 3. Uloženie výsledku do rebríčka sa neoverovalo.

Cesty v ukážke sú len príklady. Celé logy, diffy a obrázky ukladajte tam, kde už projekt podobné súbory má. Osobitnú povinnú štruktúru priečinkov netreba.

Všimnite si posledné dva riadky polí 5 a 6. Vynechaný krok pomenujte priamo, jednou vetou: "nespustilo sa", "neoverovalo sa". Nie je to priznanie lenivosti, ale hranica toho, čo možno vyvodiť. Bez takýchto riadkov záznam pôsobí úplnejšie, no v skutočnosti len mlčí o tom, čo nikto neurobil.

Skúste si to

Úloha má dve kritériá: výpočet pridá 3 body za tri zhody pri počiatočnom skóre nula a rozhranie po týchto troch zhodách ukáže 3. K dispozícii je šesť podkladov:

1. správa agenta "hotovo, chyba je opravená";
2. pokyn spustiť npm test;
3. skutočné spustenia jedného testu: neúspešné pred opravou a úspešné po nej;
4. diff so zmenou násobiteľa;
5. samostatná snímka s číslom 3 bez opisu spustenia;
6. záznam zopakovaného scenára s priradenou snímkou.

Ktoré z nich stačia na potvrdenie oboch kritérií a čo ešte zostáva neoverené? Skúste si odpoveď premyslieť skôr, než budete čítať ďalej.

Rozbor. Prvé kritérium pokrýva bod 3: skutočná dvojica spustení toho istého testu. Diff v bode 4 vysvetľuje, čo sa v kóde zmenilo, ale spustenie nenahrádza. Zmena a vykonanie sú dve rôzne veci. Druhé kritérium pokrýva bod 6: snímka spolu so záznamom scenára, na ktorom vidno počiatočný stav a vykonanú akciu. Body 1 a 2 nič nepotvrdzujú: správa o dokončení neposkytuje overiteľný dôkaz a pokyn opisuje budúcu akciu. Bod 5 ukazuje číslo 3, no tým sa končí; samotná snímka neukáže, ako sa skóre vypočítalo. A uloženie výsledku do rebríčka zostáva neoverené aj vtedy, keď máte všetkých šesť podkladov: chýba scenár, v ktorom sa uložená hodnota znova načítala.

Takýto záznam môžete zostaviť aj v relácii. Tu je hotový prompt:

Zostav EVIDENCE_LOG so šiestimi poliami. Pri každom závere uveď
skutočnú kontrolu, stav kódu a zdroj výsledku.
Osobitne označ, čo sa nespustilo. Na snímke pomenuj iba
to, čo je viditeľné, a nevyvodzuj z nej správnosť interného výpočtu.

Ako zhromaždiť dôkazy s Claude Code

Postup môže vyzerať takto:

1. agent prepojí každé kritérium s konkrétnou kontrolou: čo spustiť, v akom stave kódu a aký výsledok očakávať;
2. vykoná kontroly dostupné v danom prostredí a ukáže príkaz aj pôvodný výpis;
3. priloží pozorovania: úryvky výpisov, odkazy na celé súbory a opis zopakovaného scenára;
4. jasne označí hranice: čo sa nespustilo a čo nemožno tvrdiť na základe dostupných podkladov.

Samotné dôkazy musíte skontrolovať vy: otvoriť priložené súbory a pozrieť sa na ich obsah, porovnať scenár s kritériom a položiť jednu nepríjemnú otázku o bode, ku ktorému nevidno žiadnu kontrolu. Zvyčajne to stačí na rozlíšenie medzi zhromaždenými dôkazmi a úhľadne upraveným prerozprávaním.

Technická dokumentácia: git diff, git stash, Node.js test runner, npm test, obrázky v Claude Code.