Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Testerka požiada interného AI asistenta:
„Priprav mi testovacie scenáre pre zmenu spôsobu platby.“
AI vytvorí prehľadný zoznam testov. Overí výber platobnej metódy, úspešnú platbu, zamietnutie platby aj zobrazenie chybovej správy. Odpoveď pôsobí profesionálne a na prvý pohľad jej nič nechýba.
Až počas testovania sa ukáže, že scenáre nie sú použiteľné.
AI nevedela, že:
- zmena sa týka iba platieb kartou,
- platí len pre objednávky vytvorené v mobilnej aplikácii,
- nový proces sa používa iba pri jednom zákazníkovi,
- bankový prevod zostáva bez zmeny,
- po neúspešnej platbe sa objednávka nemá zrušiť, ale prejsť do stavu Čaká na platbu,
- opakovanú platbu možno spustiť najviac trikrát,
- testovacie prostredie používa simulátor platobnej brány s vlastnými testovacími údajmi.
AI teda nevytvorila nesprávne scenáre preto, že by nepoznala testovanie platieb. Dostala príliš málo informácií na to, aby rozlíšila všeobecné pravidlá od konkrétnej zmeny v projekte.
Požiadavka bola stručná, ale nebola jednoznačná.
Čo sa tu vlastne pokazilo (analýza systému)
Pri práci s AI sa stručnosť často zamieňa za presnosť.
Krátke zadanie môže byť presné, ak všetci poznajú rovnaký kontext. V projektovej praxi však veľká časť významu zostáva mimo samotnej otázky:
- v user story,
- v akceptačných kritériách,
- vo funkčnej špecifikácii,
- v technickej dokumentácii,
- v komentároch v Jire,
- v rozhodnutí zo stretnutia,
- v znalostiach seniora,
- v konfigurácii konkrétneho zákazníka.
Človek, ktorý na projekte pracuje niekoľko rokov, si tieto súvislosti doplní automaticky. Vie, ktorý modul sa mení, čo je Core, čo je Custom a ktoré staršie rozhodnutie stále platí.
AI tento nepovedaný kontext nemá. Ak ho nenájde v dostupných zdrojoch alebo ho nedostane priamo v zadaní, musí pracovať s pravdepodobným významom otázky.
Výsledkom môže byť odpoveď, ktorá je:
- všeobecne správna, ale nepoužiteľná pre konkrétny projekt,
- správna pre inú verziu systému,
- založená na štandardnom správaní namiesto zákazníckej úpravy,
- úplná z pohľadu zadania, ale neúplná z pohľadu reálneho workflow,
- presvedčivo napísaná, hoci vychádza z nesprávneho predpokladu.
Riešením nie je vložiť do zadania všetky dokumenty, ktoré firma má. Nadbytok nesúvisiaceho textu môže podstatnú informáciu prekryť.
AI nepotrebuje čo najviac kontextu. Potrebuje dostatok relevantného kontextu na to, aby správne pochopila úlohu, jej hranice a podmienky platnosti.
Skutočné náklady (čas, chaos, riziko)
Nedostatočný kontext sa často odhalí až po vytvorení odpovede.
Testerka dostane scenáre, ktoré musí prerobiť. Analytik opravuje návrh procesu, pretože AI nepoznala výnimku. Support pošle zákazníkovi všeobecný návod, ktorý nezodpovedá jeho konfigurácii. Vývojár vytvorí technický návrh pre nesprávnu verziu rozhrania.
Náklady nevznikajú iba tým, že AI odpovie nesprávne.
Vznikajú aj tým, že človek musí:
- zistiť, ktorý predpoklad bol chybný,
- porovnať odpoveď s viacerými dokumentmi,
- doplniť chýbajúce informácie,
- preformulovať zadanie,
- vytvoriť odpoveď znova,
- skontrolovať, či nová verzia neobsahuje ďalšie domyslené súvislosti.
Ak tím nepozná príčinu, môže problém riešiť stále podrobnejšími promptmi. Do každého zadania začne kopírovať celé dokumenty, dlhé histórie tiketov a zápisy zo stretnutí.
Tým vzniká ďalší chaos. Nie je jasné, ktorá informácia je rozhodujúca, ktorá je iba historická a ktorá už neplatí.
Riziko je najvyššie vtedy, keď odpoveď vyzerá dôveryhodne. Chybný predpoklad nemusí byť viditeľný, pretože AI ho nepomenuje. Človek potom kontroluje formuláciu odpovede, ale nie základ, z ktorého odpoveď vznikla.
Minimálny model riešenia
Dobré zadanie pre AI nemusí byť dlhé. Malo by však odpovedať na niekoľko základných otázok:
| Časť kontextu | Čo má byť jasné |
|---|---|
| Úloha | Čo má AI pripraviť, posúdiť alebo vysvetliť |
| Účel | Na čo sa výsledok použije |
| Rozsah | Ktorého modulu, procesu, klienta alebo verzie sa úloha týka |
| Východiská | Z ktorých dokumentov a overených údajov má AI vychádzať |
| Hranice | Čo do úlohy nepatrí a čo sa nemení |
| Očakávaný výstup | Akú štruktúru, podrobnosť a formu má mať výsledok |
| Neistota | Čo má AI urobiť, ak informácie nestačia alebo si odporujú |
Pôvodné zadanie:
„Priprav mi testovacie scenáre pre zmenu spôsobu platby.“
Použiteľnejšie zadanie:
„Priprav testovacie scenáre pre zmenu platby kartou v mobilnej aplikácii klienta ABC. Zmena sa týka objednávok vo verzii 4.8. Bankový prevod a webová aplikácia sa nemenia. Po neúspešnej platbe má objednávka prejsť do stavu Čaká na platbu. Používateľ môže platbu zopakovať najviac trikrát. Vychádzaj z priložených akceptačných kritérií a popisu stavového modelu. Výstup rozdeľ na pozitívne, negatívne a hraničné scenáre. Pri každom scenári uveď vstupné podmienky, kroky a očakávaný výsledok. Ak v podkladoch chýba pravidlo potrebné na vytvorenie scenára, nevymýšľaj ho a označ ho ako otvorenú otázku.“
Takéto zadanie nie je zbytočne dlhé. Každá veta znižuje konkrétne riziko:
- určuje dotknutý kanál a klienta,
- oddeľuje zmenu od oblastí, ktoré zostávajú bez zmeny,
- uvádza očakávané správanie,
- určuje zdroje informácií,
- definuje formu výsledku,
- zakazuje dopĺňať chýbajúce projektové pravidlá odhadom.
Pri opakovaných úlohách nie je potrebné písať celý kontext zakaždým. Stabilné informácie majú byť v udržiavanej dokumentácii a v šablóne zadania. Do konkrétnej požiadavky sa doplní iba aktuálna zmena.
Pred odoslaním zadania možno použiť krátku kontrolu:
- Je jasné, čo má AI vytvoriť?
- Vie AI, na čo sa výsledok použije?
- Je určený produkt, modul, verzia a prostredie?
- Je rozlíšené Core a Custom správanie?
- Je uvedené, čo sa mení a čo zostáva bez zmeny?
- Sú priložené relevantné a aktuálne zdroje?
- Je jasné, ako má vyzerať výsledok?
- Vie AI, čo má urobiť pri chýbajúcej alebo protichodnej informácii?
Ak odpoveď na niektorú z týchto otázok znie nie, zadanie môže byť jazykovo zrozumiteľné, ale projektovo neúplné.
Prepojenie na kvalitu a workflow
Kvalita odpovede AI sa nezačína pri písaní promptu. Začína pri kvalite projektovej dokumentácie.
Ak dokumentácia neobsahuje verziu, rozsah, vlastníka, stav platnosti alebo rozlíšenie Core a Custom, používateľ tieto informácie nemá odkiaľ bezpečne doplniť. Problém sa potom prenesie zo zdrojového dokumentu do zadania a zo zadania do odpovede AI.
Preto má byť kontext súčasťou bežného workflow projektu.
Pri príprave user story alebo zmenovej požiadavky má byť jasné:
- čo sa mení,
- pre koho zmena platí,
- ktorých častí systému sa dotýka,
- čo zostáva nezmenené,
- podľa ktorého pravidla sa má vyhodnotiť správny výsledok,
- ktoré otvorené otázky ešte neboli rozhodnuté.
Pri uzatváraní úlohy nestačí potvrdiť, že bol upravený kód. Treba overiť aj to, či dokumentácia obsahuje kontext potrebný na ďalšiu prácu ľudí a AI.
Do Definition of Done možno zaradiť formuláciu:
„Dokumentácia zmeny uvádza dotknutý modul, verziu, prostredie, cieľové roly, rozlíšenie Core a Custom, hranice zmeny, očakávané správanie a otvorené otázky. Zdroje použiteľné pre AI sú aktuálne, jednoznačne označené a neobsahujú neodlíšené protichodné pravidlá.“
Testerka môže pri kontrole dokumentácie overiť aj to, či sa podľa nej dá vytvoriť jednoznačné zadanie.
Ak musí pred použitím AI telefonovať seniorovi a zisťovať, čo sa vlastne mení, problém nie je iba v prompte. Chýbajúci kontext odhalil nedostatok v projektovej dokumentácii.
Krátke zhrnutie
Stručné zadanie nie je automaticky kvalitné zadanie.
AI potrebuje toľko kontextu, aby vedela:
- čo má urobiť,
- na čo sa výsledok použije,
- pre ktorý systém a situáciu informácia platí,
- z ktorých zdrojov má vychádzať,
- čo do úlohy nepatrí,
- ako má vyzerať výsledok,
- čo má urobiť, keď informácie nestačia.
Viac textu samo osebe správnu odpoveď nezaručí. Rozhodujúci je relevantný, aktuálny a jednoznačne označený kontext.
Ak AI musí podstatné projektové pravidlá odhadovať, zadanie ešte nie je pripravené. A ak tieto pravidlá nevieme do zadania doplniť bez telefonátu seniorovi, treba najprv opraviť dokumentáciu.