Jak doložit opravu

Přidělování bodů jsme opravili. V odpovědi je výpis z terminálu, snímek skóre a krátké "hotovo", souborů je spousta, ale otázka je prostá: co z toho odpovídá na požadavek úkolu?

Důkaz není jakýkoli soubor, který se náhodou ocitl vedle opravy. Je to výsledek konkrétní kontroly, ze kterého poznáte, co se ověřovalo, v jakém stavu byl kód a jak to dopadlo. Různé podklady odpovídají na různé otázky a žádný z nich nepokryje všechno.

Podíváme se, jak z požadavku udělat ověřitelné tvrzení, co zaznamenat o spuštění příkazu a co dokládá log, diff nebo snímek obrazovky. Pak to shrneme do stručného šestipoložkového deníku EVIDENCE_LOG a posoudíme, jestli je připravená sada podkladů dostačující.

Kritérium určuje kontrolu

Celým článkem nás provede příklad s malou bonusovou hrou a skóre na výsledkové tabuli. Na začátku je skóre 0, tři shody mají přidat 3 body, ale před opravou přidávaly 30. Pravidlo bodování platí pro tuto hru; v jiném projektu může být úplně jiné, nepřenášejte ho tam.

Tvrzení "skóre je opravené" ověřit nelze: není jasné, co spustit a na co se dívat. Ověřitelné tvrzení se skládá ze tří částí: počáteční stav, akce a očekávané pozorování. Například: "Při skóre 0 přidají tři shody 3 body a na tabuli se zobrazí 3." Teď už víme, jak tvrzení ověřit.

Tvrzení se dál rozpadá na samostatná pozorování. Výpočet a to, co vidí hráč, jsou dvě různé věci a každou dokládá něco jiného. Třetí řádek tabulky se týká uložení skóre do žebříčku. Tento požadavek v zadání být nemusí, ale pokud tam je, musí mít vlastní pozorování.

Nejužitečnější je tady třetí sloupec. Důkaz téměř vždy potvrzuje méně, než bychom chtěli, a hranice vede tam, kde končí provedená akce. V našem příkladu test výpočtu nekontroluje tabuli a snímek tabule neukazuje změněný řádek kódu.

Držte také odděleně dvě věci: požadavek říká, co má na konci platit, zatímco výsledek je to, co jste skutečně získali. Když se smíchají v jednom odstavci, "má přidat 3" se nenápadně změní na "přidává 3", přestože nikdo nic nespustil.

Příkaz a jeho výsledek

Spuštění kontroly popisuje pět údajů. Člověk, který ji bude za týden opakovat, žádný z nich nemusí znát:

• složka, ze které se příkaz spustil;
• přesné znění příkazu;
• stav kódu: před úpravou, po ní a s jakými necommitnutými změnami;
• jak to dopadlo: návratový kód a konečné počty;
• které kontroly se skutečně spustily a které ne.

Je důležité rozlišovat mezi "je potřeba spustit npm test" a "spustil jsem npm test, tady je výpis". První je instrukce, plán do budoucna. Druhé je fakt. Právě tady se snadno vydává záměr za výsledek, zvlášť když odpověď pečlivě popisuje, co se mělo ověřit.

npm test nespouští "všechny testy vůbec". Provede to, co je zapsané v poli test v sekci scripts konkrétního package.json - vybraného npm projektu. Abyste nemuseli hádat, který projekt je vybraný, spusťte příkaz z jeho kořenové složky a zapište ji do deníku. V sousedním projektu může stejný název spouštět jiný nástroj, jinou sadu kroků, nebo vůbec nic.

Příkaz skončí návratovým kódem: 0 obvykle znamená, že "nástroj považuje spuštění za úspěšné". V bashi ho hned po příkazu zobrazí echo $?; v PowerShellu ho u externího programu, jako je npm, najdete v $LASTEXITCODE. Nula ale neříká, zda se spustil požadovaný test: mohl být přeskočen, odfiltrován podle názvu nebo vůbec neexistovat. Vedle návratového kódu proto vždy uveďte počty a název testu, který vás zajímá.

Co uchovat z logu

Výpis ze spuštění bývá dlouhý a do deníku ho nikdo nepřepisuje celý. Krátký úryvek obsahuje čtyři věci: název neúspěšného testu, očekávanou a skutečnou hodnotu, příčinu selhání a konečné počty. Zbytek zůstane v souboru, na který odkážete. Níže je zkrácená ukázka výpisu pro výuku, ne záznam skutečného spuštění.

✖ 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

Tohle je jen úryvek; celý výpis je uložený třeba v souboru logs/test-fail.txt. Už z něj je patrné to podstatné: selhal právě test se třemi shodami, očekávali jsme 3, dostali 30 a žádná kontrola nebyla přeskočena.

Původní výpis patří do deníku beze změny. Vlastní převyprávění ("test selhal kvůli špatnému násobiteli") zní srozumitelněji, ale už je to závěr, ne pozorování, a podle deníku ho nelze ověřit. Uveďte obojí vedle sebe: nejdřív řádky nástroje, potom vlastní vysvětlení.

Adresa v řádku stack trace ukazuje, kde kontrola selhala - v souboru testu. Příčinu hledáme v kódu hry; nalezený násobitel je výsledek čtení kódu, ne řádek z logu. V deníku tyto dva zdroje označte odlišně, jinak později nebude jasné, odkud se vzalo číslo 10.

Co dokládá diff

Diff ukazuje rozdíl mezi dvěma stavy souboru. Neříká, zda se kód po úpravě vůbec spustil, natož jestli se chování změnilo podle očekávání.

--- 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 tímto úryvkem uveďte jeden řádek popisku: které stavy se porovnávaly. Například "pracovní strom proti commitu a1b2c3d před úpravou, příkaz git diff HEAD"; identifikátor je jen výukový, v deníku použijte skutečný. Tento příkaz porovnává aktuální sledované soubory s HEAD včetně změn připravených ke commitu. Běžný git diff bez HEAD ukazuje jen rozdíl oproti připravenému stavu a po git add může být prázdný. Bez popisku diff vypadá jako "něco s něčím" a porovnání už nepůjde zopakovat.

Zvlášť ověřte, že očekávaný výsledek testu zůstal 3. Pokud se spolu s kódem změnilo i očekávané číslo, je to jiný příběh: kontrola se přizpůsobila chování místo toho, aby se chování přizpůsobilo požadavku.

Ještě jedna technická drobnost, na které se dá snadno splést. Dokud změna není commitnutá, uvidíte ji při porovnání pracovního stromu s posledním commitem. Po commitu bude stejné porovnání prázdné. Neznamená to, že se v úkolu nic nezměnilo; změna se jen přesunula do historie a je třeba porovnat commit s předchozím stavem. Samotný prázdný diff nic nedokazuje. Záleží na tom, které dva stavy porovnáváte.

Co je vidět na snímku obrazovky

Stav a akce

Snímek s číslem 3 na tabuli potvrzuje jen jednu věc: v okamžiku pořízení bylo na tabuli 3. To není totéž jako tvrzení "tři shody přidaly 3 body". Mezi těmito tvrzeními je všechno, co na snímku chybí: s jakým skóre se začalo a co se vlastně udělalo.

Aby se snímek stal důkazem, zaznamenejte vedle něj scénář:

1. co jste otevřeli: adresu stránky nebo způsob spuštění a zda šlo o verzi s opravou, nebo bez ní;
2. počáteční stav: skóre na začátku 0, stará data se nenačetla;
3. akce: vytvořili jste tři shody;
4. pozorování: na tabuli je 3, snímek byl pořízen hned po akci.

Bez tohoto záznamu lze stejný snímek pořídit desítkami způsobů. Otevřená karta se starou verzí ze včerejška, jiné spuštění nebo skóre, které už nebylo nulové - to všechno vytvoří přesvědčivě vypadající obrázek, který ale nic nedokazuje.

Snímek tabule v tomto článku záměrně není. Pro ověření pořiďte snímek až po zopakování scénáře v požadované verzi, ručně nebo automatizovaně. Nakreslená nebo ilustrační tabule se důkazem nestane, ani když vypadá úplně stejně. Až budete pořizovat vlastní snímek, zachyťte celou tabuli, do záznamu scénáře uveďte adresu stránky a snímek uložte vedle záznamu. Jinak si za týden nevzpomenete, o jaké spuštění šlo.

Co dokáže přečíst model

Obrázek můžete předat do relace a požádat o jeho přečtení. Na formulaci záleží: požádejte o pojmenování viditelného čísla a výčet pochybností ("je vidět počáteční stav", "je jasné, o jakou verzi jde"), ne o potvrzení předem daného závěru. Na žádost "potvrď, že je chyba opravená" snadno dostanete zdvořilý souhlas, který nic neověřuje.

Možnost předat obrázek závisí na modelu a prostředí, ve kterém pracujete. V Claude Code můžete uvést cestu k uloženému obrázku a požádat, aby ho přečetl. Pokud se obrázek nenačte, nejprve ověřte cestu a dostupnost souboru; samotná změna modelu problém nutně nevyřeší.

Stejný scénář před opravou a po ní

Užitečná dvojice vypadá takto: stejná kontrola selže na chybné implementaci a projde na opravené. Selhání ukazuje, že kontrola tuto chybu vůbec odhalí; úspěch potvrzuje, že se v ověřovaném scénáři po opravě chyba neprojevuje.

Funguje to za jedné podmínky: porovnávají se stejné vstupní údaje a stejná očekávání. Stejné počáteční skóre, stejný počet shod i stejná očekávaná hodnota 3. Tady je úspěšný výsledek stejného testu po opravě:

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

Mezi spuštěními se mění implementace, ale test, vstupní data, očekávání i podmínky spuštění zůstávají stejné. Pokud bylo nutné změnit požadavek nebo opravit očekávání v testu, vytvořte pro tuto kontrolu novou dvojici spuštění. Slovní vysvětlení nenahradí spuštění v obou stavech. Mlčky podané "předtím červené, teď zelené" je v takové situaci zavádějící.

Ani dva soubory s názvy before.txt a after.txt samy o sobě nic nezaručují. Název souboru není důkaz. Podívejte se dovnitř: je tam stejný příkaz, stejný test a stejné očekávání? Kontrolní návrat k chybnému stavu (známý postup s git stash) je samostatná kontrola s vlastními pravidly. Tady stačí vědět, že neúspěšný výsledek před opravou pochází ze skutečného spuštění, ne z paměti.

Stručný EVIDENCE_LOG

EVIDENCE_LOG je v tomto článku běžný textový deník se šesti poli v tomto pořadí: PŘÍZNAK, STOPA V LOGU, SELHÁNÍ PŘED OPRAVOU, OPRAVA, SKUTEČNÝ ÚSPĚCH, SNÍMEK OBRAZOVKY. Tak lze snadněji propojit příznak, opravu a výsledek. Samotné pořadí polí ale spolehlivost záznamu nezaručuje.

Všechno, co jsme dosud shromáždili, se dá rozdělit do těchto polí. Příkaz a složka patří k selhání, porovnávané stavy k opravě a odkazy na úplné soubory k místu, odkud pocházejí. Není potřeba zakládat další balík dokumentů.

Níže je výuková ukázka vyplnění. Ukazuje, co do každého pole zapsat, nehlásí ale výsledky skutečně provedených kontrol. Ve vlastním deníku text nahraďte skutečnými výsledky.

PŘÍZNAK: v bonusové hře při počátečním skóre 0 přidají tři shody
30 bodů místo 3. Opakuje se to pokaždé: otevřít hru,
vytvořit tři shody a podívat se na tabuli.

STOPA V LOGU: ve výpisu spuštění je "30 !== 3" v testu
"three matches give 3 points", celý výpis je v logs/test-fail.txt.
Samostatně, ze čtení kódu: v src/bonus-game/score.js
má násobitel POINTS_PER_MATCH hodnotu 10. To je výsledek čtení kódu,
číslo 10 se ve výpisu testu nevyskytuje.

SELHÁNÍ PŘED OPRAVOU: HEAD a1b2c3d (výukový identifikátor),
pracovní strom je čistý; commit obsahuje chybný výpočet a test.
Složka - /project/bonus-game, příkaz - npm test.
V package.json scripts.test = node --test. Selže "three matches give 3 points",
příčina "30 !== 3", tests 1, pass 0, fail 1, skipped 0, návratový kód 1.
Úryvek výpisu je výše, celý výpis - logs/test-fail.txt.

OPRAVA: POINTS_PER_MATCH změněn z 10 na 1 v souboru
src/bonus-game/score.js; žádné další změny. HEAD zůstává a1b2c3d.
Diff: git diff HEAD, pracovní strom proti tomuto commitu;
uložený v diffs/score-fix.diff.
Očekávaná hodnota v testu zůstala 3.

SKUTEČNÝ ÚSPĚCH: stejný příkaz npm test ze stejné složky nad kódem
po popsané opravě. Stejný test prošel: tests 1, pass 1,
fail 0, skipped 0, návratový kód 0.
Celý výpis - logs/test-pass.txt.
Scénář s pěti shodami se nespouštěl.

SNÍMEK OBRAZOVKY: screenshots/bonus-score-3.png. Hra byla znovu otevřena
na adrese http://localhost:3000 ze stejného pracovního stromu
po opravě. Počáteční skóre 0, byly vytvořeny tři shody,
na tabuli je 3. Uložení výsledku do žebříčku nebylo ověřeno.

Cesty v ukázce jsou jen příklad. Úplné logy, diffy a obrázky ukládejte tam, kde už se podobné soubory v projektu nacházejí; není potřeba vytvářet samostatnou povinnou strukturu složek.

Všimněte si posledních dvou řádků polí 5 a 6. Vynechanou kontrolu označte přímo, jednou větou: "nespouštěl se", "nebylo ověřeno". Není to přiznání lenosti, ale hranice závěru. Bez těchto řádků deník vypadá úplněji, ale ve skutečnosti jen mlčí o tom, co nikdo neudělal.

Ověřte si to

Úkol má dvě kritéria: výpočet přidá 3 body za tři shody při počáteční nule a rozhraní po těchto třech shodách ukáže 3. Máte šest podkladů:

1. zprávu agenta "hotovo, chyba je opravená";
2. instrukci spustit npm test;
3. skutečná spuštění jednoho testu: neúspěšné před úpravou a úspěšné po ní;
4. diff se změnou násobitele;
5. samostatný snímek s číslem 3 bez popisu spuštění;
6. záznam zopakovaného scénáře s připojeným snímkem.

Které z nich stačí pro obě kritéria a co zůstává neověřené? Zkuste si odpověď promyslet, než budete číst dál.

Rozbor. První kritérium pokrývá bod 3: skutečnou dvojici spuštění stejného testu. Diff v bodě 4 vysvětluje, co se v kódu změnilo, ale spuštění nenahrazuje - změna a provedení jsou dvě různé věci. Druhé kritérium pokrývá bod 6: snímek spolu se záznamem scénáře, kde je vidět počáteční stav a akce. Body 1 a 2 nic nepotvrzují: zpráva o dokončení neobsahuje ověřitelný důkaz a instrukce popisuje budoucí akci. Bod 5 ukazuje číslo 3, ale tím končí; samotné přidělení bodů z něj zjistit nelze. A uložení výsledku do žebříčku zůstává neověřené i tehdy, když máte všech šest podkladů: žádný z nich nepopisuje scénář, ve kterém se uložená hodnota znovu načetla.

Takový deník můžete sestavit i v relaci. Tady je hotový prompt:

Sestav EVIDENCE_LOG se šesti poli. U každého závěru uveď
skutečnou kontrolu, stav kódu a zdroj výsledku.
Samostatně označ, co se nespouštělo. Na snímku obrazovky pojmenuj jen
to, co je vidět, a nevyvozuj z něj správnost interního výpočtu.

Jak shromáždit důkazy s Claude Code

Postup vypadá takto:

1. agent propojí každé kritérium s konkrétní kontrolou: co spustit, v jakém stavu kódu a co považovat za výsledek;
2. provede kontroly dostupné v daném prostředí a ukáže příkaz spolu s původním výpisem;
3. přiloží pozorování: úryvky výpisů, odkazy na úplné soubory a popis zopakovaného scénáře;
4. jasně vymezí hranice: co se nespustilo a co z dostupných podkladů nelze tvrdit.

Na vás zůstává kontrola samotných důkazů: otevřít přiložené soubory a podívat se dovnitř, porovnat scénář s tím, který popisuje kritérium, a položit jednu nepříjemnou otázku k bodu, u něhož kontrola chybí. Obvykle to stačí k rozlišení skutečně shromážděných důkazů od úhledně sepsaného převyprávění.

Technické reference: git diff, git stash, Node.js test runner, npm test, práce s obrázky v Claude Code.